tractor/docs/api/core.rst

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.