tractor/docs/api/context.rst

Contexts and streaming

The modern core of tractor: a Context links a task in one actor to a task in another as a single structured concurrency (SC) scope stretched across the IPC boundary — errors, results and cancellation flow between the pair exactly like trio tasks under a common nursery. Open one with Portal.open_context() (see tractor._context.open_context_from_portal in /api/core), then optionally bridge a bidirectional MsgStream between the two tasks.

For the guided, example-driven tour see /guide/context; this page is the precise API surface.

tractor

The @context decorator

context

Note

The decorated function must declare a parameter annotated tractor.Context (any param name works); the runtime injects the context instance there on each remote invocation. Pass pld_spec to type-restrict (and validate) the payloads this endpoint may shuttle — violations raise MsgTypeError. See examples/typed_payloads.py.

Context

Context

0.1.0a6

Context.result() warns; use Context.wait_for_result.

Note

A Context is not a trio.CancelScope: Context.cancel requests cancellation of the remote peer task and does not cancel the local scope. If you requested the cancel, the resulting ContextCancelled is absorbed at open_context() exit; a cancel originating anywhere else (the peer, or a third-party actor recorded in ContextCancelled.canceller) is raised locally. This self-vs-cross-cancel rule is the key to writing correct inter-actor teardown logic — see /guide/context.

Bidirectional streaming

tractor._streaming.open_stream_from_ctx

Note

~tractor._streaming.open_stream_from_ctx is bound as the method-alias Context.open_stream() — call it as async with ctx.open_stream() as stream:. Both sides of the context must enter it for the dialog to be open.

MsgStream

Note

A MsgStream is one-shot use: once closed it can never be "re-opened" — open a fresh Context instead. Remote end-of-stream surfaces as StopAsyncIteration from async for; un-consumed sends overrun the receiver and raise tractor._exceptions.StreamOverrun unless the context was opened with allow_overruns=True.

MsgStream.subscribe fans a single IPC stream out to multiple local tasks via a tractor.trionics.BroadcastReceiver (see /api/trionics); the underlying allocation is idempotent and non-reversible for the stream's lifetime. See examples/streaming_broadcast_fanout.py for the pattern in action.

Legacy one-way streaming

stream

Warning

@tractor.stream and Portal.open_stream_from() are the legacy one-way streaming API kept for backward compat: a plain async-generator function streamed parent-ward with no child-side receive leg. New code should use @tractor.context + ctx.open_stream() (bidirectional, SC-linked, typed). Note ctx is now a reserved param name for @context endpoints — @stream functions must use stream instead, and ctx.send_yield() is deprecated in favor of MsgStream.send.

/api/errors for ContextCancelled / MsgTypeError semantics, /api/msg for payload typing via pld_spec and codecs, /api/trionics for the broadcast fan-out machinery, and the guided tours in /guide/streaming + /guide/cancellation.