5.1 KiB
Runtime and spawning
The core lifecycle API: boot the runtime in your root process, spawn trio-"actors" (processes running trio.run() task trees) under a one-cancels-all supervisor, and talk to them through portals. This is structured concurrency (SC) applied transitively: every spawned process is owned by a nursery block and errors always propagate. If you can create zombies it is a bug.
tractor
Booting the runtime
open_root_actor
Note
The env vars TRACTOR_LOGLEVEL and TRACTOR_SPAWN_METHOD override the loglevel / start_method params so you can crank verbosity or swap spawn backends without touching app code. Exactly one IPC transport may be enabled per actor (see enable_transports and /api/ipc).
run_daemon
Spawning actors
open_nursery
ActorNursery
Note
ActorNursery.start_actor (daemon actor + portal) is the blessed spawning primitive; pair it with Portal.open_context() for SC-linked remote tasks.
One-shot task actors
tractor.to_actor.run
Note
tractor.to_actor.run (parlance of trio.to_thread.run_sync() and friends) is the convenience one-shot — spawn, run a single task, block on its result, reap — built entirely on ActorNursery.start_actor + Portal.run + Portal.cancel_actor, so don't design around it as the core model. It supersedes the removed (legacy, non-blocking) ActorNursery.run_in_actor().
0.1.0a6
ActorNursery.cancelled warns; use ActorNursery.cancel_called and ActorNursery.cancelled_caught. The rpc_module_paths kwarg is likewise deprecated in favor of enable_modules.
Portals
A Portal "opens a portal" into a peer actor's memory domain: you call functions and start SC-linked tasks over IPC as though they were local, with results, errors and cancellation flowing back exactly like trio.
Portal
0.1.0a6
The str-form Portal.run('mod.path', 'fn_name') warns; pass a function object whose module is listed in the target's enable_modules. Portal.channel is the legacy spelling of Portal.chan.
tractor._context.open_context_from_portal
Note
~tractor._context.open_context_from_portal is bound as the method-alias Portal.open_context() — that's the spelling you should actually call: portal.open_context(fn, **kwargs). See /api/context for the full Context + MsgStream API it unlocks.
Note
Portal.cancel_actor cancels the whole remote runtime and process (machine-level), not a single task — use Context.cancel for task-level cancellation. Pass raise_on_timeout=True to get an ActorTooSlowError you can escalate per SC discipline (see /api/errors).
Clusters
open_actor_cluster
Spawn a flat cluster of count worker actors (default: one per core) all serving the RPC modules list, yielding a dict[str, Portal] keyed by actor name. Handy for embarrassingly parallel fan-out; see examples/quick_cluster.py.
Runtime introspection
current_actor
Actor
Note
Actor is the per-process runtime singleton (msg loop, RPC scheduling, IPC server) — you never instantiate it yourself and should normally only touch the identity/introspection surface listed above. The canonical identity type is Actor.aid (a tractor.msg.Aid struct); Actor.uid is the legacy (name, uuid) 2-tuple which is still pervasive in logs and error metadata.
0.1.0a6
Actor.is_arbiter warns; use Actor.is_registrar. The arbiter_addr constructor kwarg is deprecated for registry_addrs.
current_ipc_ctx
is_root_process
get_runtime_vars
/api/context for the SC-linked remote task API, /api/discovery for finding actors by name, and the guided tours in /guide/spawning, /guide/rpc and /guide/context.