Skip to content

Tracking

pkl.tracking turns "create a resource" into "create a resource and record it under whoever is running".

ResourceTracker

A PluginTracker (who is running?) paired with a ResourceRegistry (where do their resources go?). The registry is the passive map; the tracker is the active step.

tracker = ResourceTracker(plugins, runtime)
tracker.track(resource)            # explicit form: registers under plugins.current

If no plugin is executing, track raises NoCurrentPluginError: an owner-less resource could never be released. ResourceTracker(..., allow_orphans=True) instead lets such resources be host-owned (not recorded anywhere).

Tracked

An abstract base class whose instances register themselves. Bind it with the tracker class keyword; subclasses inherit the binding:

class RuntimeResource(Tracked[AppPlugin], tracker=ResourceTracker(plugins, runtime)): ...
class PersistentResource(Tracked[AppPlugin], tracker=ResourceTracker(plugins, persistent)): ...

Subclasses implement on_release(). Properties: owner (typed as your plugin), tracker, released. Lifetime is therefore not a library type: two bases bound to two registries are two lifetimes.

Instantiating a class that is not bound to a tracker raises UnboundResourceError.

Several trackers from one class

zone_timer = Timer.with_tracker(ResourceTracker(zone.plugins, zone.registry))
zone_timer.interval(callback, 1.0)

with_tracker returns the same class bound to another tracker (cached per tracker, fully typed). Seal a base with allow_tracker_override=False and it raises TrackerOverrideError instead; use that in an SDK that is single-host by design.

Callbacks

For a one-off resource, or a function that must run as its creator, no class is needed:

tracker.callback(on_message, finalizer=connection.close)   # tracked; runs as its creator; inert once released

Your own resources

class Socket(RuntimeResource):
    def __init__(self, address: str) -> None:
        self.connection = connect(address)       # self.owner is already available here
        # work on threads pkl does not control: bind it to the owner
        threading.Thread(target=self.bind(self.serve), daemon=True).start()
    def on_release(self) -> None:
        self.connection.close()