Gud Boi
7f1fa2c3a5
Promote `_subint_forkserver` from primitives-only into a
registered spawn backend: `'subint_forkserver'` is now a
`SpawnMethodKey` literal, dispatched via `_methods` to
the new `subint_forkserver_proc()` target, feature-gated
under the existing `subint`-family py3.14+ case, and
selectable via `--spawn-backend=subint_forkserver`.
Deats,
- new `subint_forkserver_proc()` spawn target in
`_subint_forkserver`:
- mirrors `trio_proc()`'s supervision model — real OS
subprocess so `Portal.cancel_actor()` + `soft_kill()`
on graceful teardown, `os.kill(SIGKILL)` on hard-reap
(no `_interpreters.destroy()` race to fuss over bc the
child lives in its own process)
- only real diff from `trio_proc` is the spawn mechanism:
fork from a main-interp worker thread via
`fork_from_worker_thread()` (off-loaded to trio's
thread pool) instead of `trio.lowlevel.open_process()`
- child-side `_child_target` closure runs
`tractor._child._actor_child_main()` with
`spawn_method='trio'` — the child is a regular trio
actor, "subint_forkserver" names how the parent
spawned, not what the child runs
- new `_ForkedProc` class — thin `trio.Process`-compatible
shim around a raw OS pid: `.poll()` via
`waitpid(WNOHANG)`, async `.wait()` off-loaded to a trio
cache thread, `.kill()` via `SIGKILL`, `.returncode`
cached for repeat calls. `.stdin`/`.stdout`/`.stderr`
are `None` (fork-w/o-exec inherits parent FDs; we don't
marshal them) which matches `soft_kill()`'s `is not None`
guards
Also, new backend-tier test
`test_subint_forkserver_spawn_basic` drives the registered
backend end-to-end via `open_root_actor` + `open_nursery` +
`run_in_actor` w/ a trivial portal-RPC round-trip. Uses a
`forkserver_spawn_method` fixture to flip
`_spawn_method`/`_ctx` for the test's duration + restore on
teardown (so other session-level tests don't observe the
global flip). Test module docstring reworked to describe
the three tiers now covered: (1) primitive-level, (2)
parent-trio-driven primitives, (3) full registered backend.
Status: still-open work (tracked on `tractor#379`) doc'd
inline in the module docstring — no cancel/hard-kill stress
coverage yet, child-side subint-hosted root runtime still
future (gated on `msgspec#563`), thread-hygiene audit
pending the same unblock.
(this patch 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!