Skip to content

Context, syscalls, async and threads

Syscalls

A function marked with pkl.syscall.syscall runs as the plugin that defined it, whoever calls it, and the caller's plugin is restored afterwards.

syscall = partial(pkl.syscall.syscall, plugins)      # bind once per application

with plugins.executing(provider):
    @syscall
    def who_am_i() -> AppPlugin | None:
        return plugins.current

with plugins.executing(caller):
    who_am_i()                   # provider
    plugins.current              # caller again

The defining plugin is the one executing when the decorator is applied (so, while a plugin's module loads). Defined outside any plugin it runs as the host. Plain and async functions are supported. Because the tracker is passed explicitly there is no hidden host: syscall works with any number of trackers.

Binding callbacks

plugins.bind(func) is the primitive behind syscalls: it captures the plugin executing now and returns a function that runs as that plugin, from any thread or task. plugins.bind_as(plugin, func) is the same for an explicit plugin. Everything in pkl that has to "run as someone" goes through it.

with plugins.executing(alpha):
    on_message = plugins.bind(handle)          # captured at creation, no need to remember later
threading.Thread(target=on_message).start()    # runs as alpha

Resources have a shortcut that binds to their owner: self.bind(func). And tracker.callback(func, finalizer=...) makes a tracked, releasable Callback (inert once released).

Async

The current plugin is in a ContextVar. Concurrent tasks that run as different plugins never see each other's plugin, also across awaits, and tasks inherit the plugin they were created under (create_task, TaskGroup).

Threads

New threads start with an empty context, so a plain threading.Thread has no current plugin. Bind the entry point (or copy the context):

threading.Thread(target=plugins.bind(work)).start()
# or: loop.run_in_executor(None, plugins.bind(work))
# or: context = contextvars.copy_context(); threading.Thread(target=context.run, args=(work,))

Creating a tracked resource in such a thread raises NoCurrentPluginError instead of leaking silently. pkl.timing.Timer re-enters its owner for you.