tractor/docs/index.rst

tractor

distributed structured concurrency: a multi-processing runtime built on (and shaped entirely like) trio.

tractor provides parallelism via trio "actors": independent Python processes (ie. non-shared-memory threads) each running a trio task tree, all composed into a distributed supervision tree with end-to-end structured concurrency (SC) — spawning, cancellation, error propagation and teardown that work across processes (and hosts) exactly the way they work across tasks.

tl;dr

It's just trio, but with nurseries that spawn processes and streams that cross them. If you can read a trio program you can read a tractor one — that's the whole pitch.

Sixty seconds of why

Spawn one actor per core, crash the root on purpose, and watch the runtime contain the blast: errors propagate, every child is reaped, zero zombies — guaranteed (it's a bug otherwise).

../examples/parallelism/we_are_processes.py

Like every snippet in these docs this file lives in the repo's examples/ dir and runs under CI — docs code that can't rot.

Dig in

1 2 2 3

Get started

Install + your first actor tree in ~20 lines; causality, daemons and the trynamic scene.

The big ideas

SC across processes, distilled — then the runtime architecture under it.

Debug like a local

await tractor.pause() anywhere in the tree: one terminal, every process, zero socket-juggling.

Streaming + contexts

Bidirectional, cancellation-safe msg streams between any two actors.

Guides

RPC, supervision, clustering, "infected asyncio", typed msging + more.

API reference

The curated public surface; everything importable from tractor.

Features

• It's just a trio API — same nursery discipline, same cancellation semantics, one level up the process tree.
• Infinitely nestable process trees: sub-actors can spawn sub-actors, supervision stays transitive.
• A "native UX" multi-process debugger REPL: built on pdbp with tree-wide tty locking (see guide/debugging).
• Built-in, cancellation-safe bidirectional streaming via a cheap or nasty (un)protocol.
• Typed IPC: msgspec-backed wire msgs with optional per-dialog payload specs (guide/msging).
• Swappable process-spawn backends + modular IPC transports (TCP today, UDS on same-host, more planned).
• Optionally distributed: the same APIs work over multiple hosts as on multiple cores.
• "Infected asyncio" mode: SC-supervise asyncio tasks from trio (guide/asyncio).
• trio extension goodies via tractor.trionics (acm gathering, single-resource caching, broadcast channels).

Where do i start!?

The first step to grok tractor is to get an intermediate knowledge of trio and structured concurrency B)

Some great places to start are,

• the seminal blog post,
• obviously the trio docs,
• wikipedia's nascent SC page,
• the fancy diagrams @ libdill-docs,

then come back and hit start/quickstart.

Get started <start/index> Big ideas <explain/index> Guides <guide/index> API <api/index> Project <project/index>