Gud Boi
483a00ef18
Fourth diagnostic pass — instrument `_worker`'s
fork-child branch (`pre child_target()` / `child_
target RETURNED rc=N` / `about to os._exit(rc)`)
and `_trio_main` boundaries (`about to trio.run` /
`trio.run RETURNED NORMALLY` / `FINALLY`). Test
config: depth=1/breadth=2 = 1 root + 14 forked =
15 actors total.
Fresh-run results,
- **9 processes complete the full flow**:
`trio.run RETURNED NORMALLY` → `child_target
RETURNED rc=0` → `os._exit(0)`. These are tree
LEAVES (errorers) plus their direct parents
(depth-0 spawners) — they actually exit
- **5 processes stuck INSIDE `trio.run(trio_
main)`**: hit "about to trio.run" but never
see "trio.run RETURNED NORMALLY". These are
root + top-level spawners + one intermediate
The deadlock is in `async_main` itself, NOT the
peer-channel loops. Specifically, the outer
`async with root_tn:` in `async_main` never exits
for the 5 stuck actors, so the cascade wedges:
trio.run never returns
→ _trio_main finally never runs
→ _worker never reaches os._exit(rc)
→ process never dies
→ parent's _ForkedProc.wait() blocks
→ parent's nursery hangs
→ parent's async_main hangs
→ (recurse up)
The precise new question: **what task in the 5
stuck actors' `async_main` never completes?**
Candidates:
1. shielded parent-chan `process_messages` task
in `root_tn` — but we cancel it via
`_parent_chan_cs.cancel()` in `Actor.cancel()`,
which only runs during
`open_root_actor.__aexit__`, which itself runs
only after `async_main`'s outer unwind — which
doesn't happen. So the shield isn't broken in
this path.
2. `actor_nursery._join_procs.wait()` or similar
inline in the backend `*_proc` flow.
3. `_ForkedProc.wait()` on a grandchild that DID
exit — but pidfd_open watch didn't fire (race
between `pidfd_open` and the child exiting?).
Most specific next probe: add DIAG around
`_ForkedProc.wait()` enter/exit to see whether
pidfd-based wait returns for every grandchild
exit. If a stuck parent's `_ForkedProc.wait()`
never returns despite its child exiting → pidfd
mechanism has a race bug under nested forkserver.
Asymmetry observed in the cascade tree: some d=0
spawners exit cleanly, others stick, even though
they started identically. Not purely depth-
determined — some race condition in nursery
teardown when multiple siblings error
simultaneously.
No code changes — diagnosis-only.
(this commit msg was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
(cherry picked from commit
|
||
|---|---|---|
| .claude | ||
| .github/workflows | ||
| ai | ||
| docs | ||
| examples | ||
| nooz | ||
| notes_to_self | ||
| scripts | ||
| tests | ||
| tractor | ||
| xontrib | ||
| .gitignore | ||
| LICENSE | ||
| MANIFEST.in | ||
| NEWS.rst | ||
| default.nix | ||
| flake.lock | ||
| flake.nix | ||
| mypy.ini | ||
| pyproject.toml | ||
| ruff.toml | ||
| uv.lock | ||
docs/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!