tractor/docs/api/trionics.rst

Trio patterns: tractor.trionics

Sugary structured concurrency (SC) patterns for plain trio code — no actor runtime required. These helpers grew out of real distributed-system needs in tractor apps but every one of them works in a single-process program too; import via from tractor import trionics.

tractor.trionics

Context-manager helpers

gather_contexts

maybe_open_context

maybe_open_nursery

Note

gather_contexts is "a nursery for async context managers": it enters N acms concurrently and yields their values in input order. maybe_open_context is the actor-wide cache/multiplex layer on top — the first task pays the acm setup cost, later callers get (cache_hit=True, ...) and share the same value until all users exit.

Broadcast fan-out

broadcast_receiver

BroadcastReceiver

Lagged

A single-producer, many-consumer broadcast layer over any trio-style receive channel: non-lossy for the fastest consumer while slower consumers raise Lagged (a trio.TooSlowError subtype) once they fall behind the internal ring. This is exactly the machinery behind tractor.MsgStream.subscribe — see examples/streaming_broadcast_fanout.py.

ExceptionGroup helpers

collapse_eg

maybe_raise_from_masking_exc

Note

collapse_eg "un-nests" single-exception ExceptionGroup wrappers from strict-eg trio nurseries so your except clauses match the original error; maybe_raise_from_masking_exc surfaces real errors that would otherwise be masked by trio.Cancelled during teardown.

/api/context for the IPC-stream consumer of BroadcastReceiver, /guide/streaming for fan-out in a worked pipeline, and the trio docs for the underlying channel and nursery semantics these helpers compose.