Gud Boi
4dfcf6f660
In `.open_channel_from()`, when the `trio`-side parent task exits, it
signals the running `asyncio`-side task with `TrioTaskExited`; this is
our internal exit signal to any still-running `asyncio` task. When the
`asyncio`-side raises the issued signal, previously
`translate_aio_errors()` let it escape despite
`suppress_graceful_exits=True`, (in `piker`'s case) turning an expected
(and cached via `.trionics.maybe_open_context`) channel teardown into
a (quote-feed) task-restart failure.
Now if that task raises the same signal, `translate_aio_errors()`
suppresses it when `suppress_graceful_exits=True`, while preserving any
original `trio`-side error. There are two cooperating fixes:
1. `translate_aio_errors()` returns early without raising that TTE. This
prevents normal channel teardown from propagating it back up to
the originating task.
2. The `asyncio` done callback `signal_trio_when_done()` now returns
early for that same TTE ack and prevents it from
recancelling the already-unwinding `trio-side` or raising the signal
again as an unhandled callback error.
Deats,
- record the issued `TrioTaskExited` instance in
`LinkedTaskChannel._aio_owner_exit` before signalling the
`asyncio`-side task, retaining the original `trio`-side error
as its cause when present.
- use exception identity (`is`), rather than type, to recognize
that issued signal; a separately raised TTE or another
`asyncio`-side cleanup error retains existing error handling.
- in `translate_aio_errors()`, require the `trio`-side parent
task to have exited before handling the acknowledged signal:
- raise any original `trio_err` first, without making its own
exit signal its cause and creating an exception-cause cycle;
- OW return early under `suppress_graceful_exits=True`;
- with suppression disabled, raise the exact issued TTE.
- in `signal_trio_when_done()`, retrieve the task exception but
skip parent-task recancellation and callback error relay when
it is that issued TTE and the `trio`-side has already exited.
- in `wait_on_coro_final_result()`, retain the issued TTE in
`chan._aio_err` for the reporting decision above, logging its
receipt as an exit acknowledgement rather than a task failure.
- retain the actual `maybe_signal_aio_task()` delivery report
for both acknowledgement logs; include the `trio`-side parent
task via `pformat_task()`, its original error/cancellation cause,
and runtime-level diagnostics for each reporting decision.
Update docs/reporting,
- document the signal writer, readers and teardown outcomes;
- retain the actual signalling report for both acknowledgements;
- use `pformat_task()` to identify the `trio.Task` in diagnostics;
- distinguish the parent's error from its issued TTE;
- log suppression, strict reporting and `trio`-side-error precedence;
- clarify graceful suppression for cached-channel teardown;
- keep the queue-shutdown TODO beside its existing handler.
Qualification using a separate, uncommitted regression module:
- original matrix 8 failed / 4 passed; candidate matrix 12 passed.
- selected bridge/formatter run: 41 passed / 18 deselected.
- earlier `piker` real-channel integration: 4 passed.
- human reset traces acknowledge owner exit and preserve a quote
`TimeoutError`.
Prompt-IO: ai/prompt-io/20261028T193020Z_b64c89f0_cached_owner.md
(this patch was generated in some part by `opencode` using
`gpt-6.1-sol` (`openai`))
|
||
|---|---|---|
| .. | ||
| _diagrams | ||
| _ext | ||
| _static | ||
| api | ||
| diagrams | ||
| explain | ||
| github_readme | ||
| guide | ||
| project | ||
| start | ||
| Makefile | ||
| README.rst | ||
| conf.py | ||
| index.rst | ||
| mk_gh_readme.sh | ||
README.rst
tractor: distributed structured concurrency
tractor is a structured concurrency (SC), multi-processing runtime built on trio.
Fundamentally, tractor provides parallelism via trio-"actors": independent Python processes (i.e. non-shared-memory threads) which can schedule trio tasks whilst maintaining end-to-end SC inside a distributed supervision tree.
Cross-process (and thus cross-host) SC is accomplished through the combined use of our,
- "actor nurseries" which provide for spawning multiple, and possibly nested, Python processes each running a
trioscheduled runtime - a call totrio.run(), - an "SC-transitive supervision protocol" enforced as an IPC-message-spec encapsulating all RPC-dialogs.
We believe the system adheres to the 3 axioms of an "actor model" but likely does not look like what you probably think an "actor model" looks like, and that's intentional.
Where do i start!?
New to trio and structured concurrency? Our docs collect the best starting points and then walk you straight into a hands-on quickstart:
Features
- It's just a
trioAPI! - Infinitely nesteable process trees running embedded
triotasks. - Swappable, OS-specific, process spawning via multiple backends.
- Modular IPC stack, allowing for custom interchange formats (eg. as offered from msgspec), varied transport protocols (TCP, RUDP, QUIC, wireguard), and OS-env specific higher-perf primitives (UDS, shm-ring-buffers).
- Optionally distributed: all IPC and RPC APIs work over multi-host transports the same as local.
- Builtin high-level streaming API that enables your app to easily leverage the benefits of a "cheap or nasty" (un)protocol.
- A "native UX" around a multi-process safe debugger REPL using pdbp (a fork & fix of pdb++)
- "Infected
asyncio" mode: support for starting an actor's runtime as a guest on theasyncioloop allowing us to provide stringent SC-styletrio.Task-supervision around anyasyncio.Taskspawned via ourtractor.to_asyncioAPIs. - A very naive and still very much work-in-progress inter-actor discovery sys with plans to support multiple modern protocol approaches.
- Various
trioextension APIs viatractor.trionicssuch as,- task fan-out broadcasting,
- multi-task-single-resource-caching and fan-out-to-multi
__aenter__()APIs for@acmfunctions, - (WIP) a
TaskMngr: one-cancels-one style nursery supervisor.
Status of main / infra
Install
tractor is still in a alpha-near-beta-stage for many of its subsystems, however we are very close to having a stable lowlevel runtime and API.
As such, it's currently recommended that you clone and install the repo from source:
pip install git+git://github.com/goodboy/tractor.gitWe use the very hip uv for project mgmt:
git clone https://github.com/goodboy/tractor.git
cd tractor
uv sync --dev
uv run python examples/rpc_bidir_streaming.pyConsider activating a virtual/project-env before starting to hack on the code base:
# you could use plain ol' venvs
# https://docs.astral.sh/uv/pip/environments/
uv venv tractor_py313 --python 3.13
# but @goodboy prefers the more explicit (and shell agnostic)
# https://docs.astral.sh/uv/configuration/environment/#uv_project_environment
UV_PROJECT_ENVIRONMENT="tractor_py313"
# hint hint, enter @goodboy's fave shell B)
uv run --dev xonshAlongside all this we ofc offer "releases" on PyPi:
pip install tractorJust note that YMMV since the main git branch is often much further ahead then any latest release.
Hacking on the docs themselves? The build + live-preview one-liners (incl. nix-shell specifics) are collected in notes_to_self/howtodocs.md, and rendered as the "Building these docs" section of our dev-tips guide.
Example codez
We prefer to point you at the runnable scripts under examples/ - each is CI-run and literalinclude-d straight into the docs, so what you read there is what actually runs - rather than inline a pile of them here. The one-minute pitch: spawn a subactor per core, open a Context into each, then crash the root on purpose and watch the runtime reap the whole tree - zero zombies, guaranteed (if you can make a zombie child without a system signal, it is a bug).
See it run - plus the full tour (the flagship multi-process debugger, bidirectional streaming over a Context, cancellation, discovery, "infected asyncio", typed messaging and worker-pool / cluster patterns) - in the docs:
- docs: https://goodboy.github.io/tractor/
- examples: https://github.com/goodboy/tractor/tree/main/examples
Under the hood
tractor is an attempt to pair trionic structured concurrency with distributed Python - think of it as trio -across-processes, or as an opinionated replacement for the stdlib's multiprocessing built on async primitives from the ground up. But really it is just trio: nurseries that spawn processes and cancel-able streaming IPC between them. If you can drive trio, you can drive tractor.
"But wait - don't 'actors' have mailboxes and messages and stuff?!" Well, we've got (well referenced) opinions on what an "actor model" actually is (tl;dr: the 3 axioms, not the cultural baggage) - that whole riff lives in our docs:
https://goodboy.github.io/tractor/explain/sc-distributed.html#hold-up-is-this-an-actor-model
What's on the TODO
The roadmap lives with our docs - see what the future holds for where tractor is headed.
Feel like saying hi?
This project is very much coupled to the ongoing development of trio (i.e. tractor gets most of its ideas from that brilliant community). If you want to help, have suggestions or just want to say hi, please feel free to reach us in our matrix channel. If matrix seems too hip, we're also mostly all in the the trio gitter channel!