Write the big boi docs content tree
Replace the ancient `docs/index.rst` (still teaching
`tractor.run()`, `@stream` + arbiters..) with a full ~32 page tree
teaching ONLY the current api (`.wait_for_result()`, registrar
naming, `@context` + `open_context()` as the core model),
- landing: hero example, feature cards + canon links,
- `start/`: install + a 4-example quickstart on-ramp,
- `explain/`: an "SC across processes" essay distilling the essence
per #157's orig ask + a runtime architecture tour,
- `guide/`: 12 task-focused pages incl the flagship multi-process
debugging walkthrough, `Context` + `MsgStream` deep-dives,
cancellation semantics (self-vs-cross cancel rules), discovery,
infected `asyncio`, typed msging + the #126 testing-tips page,
- `api/`: 10 curated autodoc pages (all targets import-verified vs
the reorg'd subpkg tree),
- `project/`: changelog include, ported dev-tips (drops old
`docs/dev_tips.rst`) + roadmap.
Every code block is a `literalinclude` from `examples/`
- zero duplication, all CI-run - w/ `d2` figs floated
into the RHS margin per the 3-col design. Build is green; the 24
remaining warnings all source from lib docstring rst-isms or legacy
`NEWS.rst` content.
Substantially resolves #157 (refine round pending); chips at #175 +
#126.
Prompt-IO: ai/prompt-io/claude/20260611T175152Z_8526985c_prompt_io.md
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
2026-06-11 19:17:14 +00:00
|
|
|
IPC and logging
|
|
|
|
|
===============
|
|
|
|
|
|
|
|
|
|
Under every portal, context and stream sits a per-peer
|
|
|
|
|
:class:`~tractor.Channel`: a msgpack-typed messaging link wrapping
|
|
|
|
|
one OS transport connection. Transports are pluggable per actor
|
Add a `tipc` guide page, roster it in the docs
Plan 01 §8's docs deliverable: `docs/guide/tipc.rst`, leading
w/ the `tipc nametable show` demo as the plan asked.
Frames the backend by what makes it different — every other tpt
gives you a pipe and leaves discovery to the registrar, whereas
TIPC's service names live in a kernel-maintained cluster-wide
name table, so a `.bind()` IS registration and a `.connect()` IS
the lookup. Then: push-based discovery via
`open_topology_events()`, scope-as-`.bindspace`, bearer setup
for spanning hosts, and the gotchas.
Also,
- roster it in `guide/index.rst` (prose list + toctree)
- `api/ipc.rst`'s transport line said `['tcp' | 'uds']` and
described only 2 unwrapped-addr shapes; now mentions `tipc`
and its proto-keyed `('tipc', stype, instance, scope)`.
Verified w/ a full `sphinx -b html` build: succeeded, page
renders, internal refs resolve.
(this patch was generated in some part by `claude-code` using `claude-opus-5` (`anthropic`))
2026-08-16 00:08:12 +00:00
|
|
|
via ``enable_transports=['tcp' | 'uds' | 'tipc']`` — TCP is the
|
|
|
|
|
default, UDS (unix domain sockets) gives you port-less, same-host
|
|
|
|
|
IPC with kernel-provided peer credentials for free, and TIPC is an
|
|
|
|
|
opt-in linux cluster protocol where the address *is* a
|
|
|
|
|
kernel-published service name (see :doc:`/guide/tipc`) — and
|
|
|
|
|
exactly **one** transport may currently be enabled per actor.
|
Write the big boi docs content tree
Replace the ancient `docs/index.rst` (still teaching
`tractor.run()`, `@stream` + arbiters..) with a full ~32 page tree
teaching ONLY the current api (`.wait_for_result()`, registrar
naming, `@context` + `open_context()` as the core model),
- landing: hero example, feature cards + canon links,
- `start/`: install + a 4-example quickstart on-ramp,
- `explain/`: an "SC across processes" essay distilling the essence
per #157's orig ask + a runtime architecture tour,
- `guide/`: 12 task-focused pages incl the flagship multi-process
debugging walkthrough, `Context` + `MsgStream` deep-dives,
cancellation semantics (self-vs-cross cancel rules), discovery,
infected `asyncio`, typed msging + the #126 testing-tips page,
- `api/`: 10 curated autodoc pages (all targets import-verified vs
the reorg'd subpkg tree),
- `project/`: changelog include, ported dev-tips (drops old
`docs/dev_tips.rst`) + roadmap.
Every code block is a `literalinclude` from `examples/`
- zero duplication, all CI-run - w/ `d2` figs floated
into the RHS margin per the 3-col design. Build is green; the 24
remaining warnings all source from lib docstring rst-isms or legacy
`NEWS.rst` content.
Substantially resolves #157 (refine round pending); chips at #175 +
#126.
Prompt-IO: ai/prompt-io/claude/20260611T175152Z_8526985c_prompt_io.md
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
2026-06-11 19:17:14 +00:00
|
|
|
|
|
|
|
|
.. d2:: diagrams/runtime_stack.d2
|
|
|
|
|
:caption: Where ``Channel`` sits in the runtime stack.
|
|
|
|
|
:margin:
|
|
|
|
|
:alt: layered runtime stack from app code down to transports
|
|
|
|
|
|
|
|
|
|
Addresses are "unwrapped" tuples at the API edges:
|
Add a `tipc` guide page, roster it in the docs
Plan 01 §8's docs deliverable: `docs/guide/tipc.rst`, leading
w/ the `tipc nametable show` demo as the plan asked.
Frames the backend by what makes it different — every other tpt
gives you a pipe and leaves discovery to the registrar, whereas
TIPC's service names live in a kernel-maintained cluster-wide
name table, so a `.bind()` IS registration and a `.connect()` IS
the lookup. Then: push-based discovery via
`open_topology_events()`, scope-as-`.bindspace`, bearer setup
for spanning hosts, and the gotchas.
Also,
- roster it in `guide/index.rst` (prose list + toctree)
- `api/ipc.rst`'s transport line said `['tcp' | 'uds']` and
described only 2 unwrapped-addr shapes; now mentions `tipc`
and its proto-keyed `('tipc', stype, instance, scope)`.
Verified w/ a full `sphinx -b html` build: succeeded, page
renders, internal refs resolve.
(this patch was generated in some part by `claude-code` using `claude-opus-5` (`anthropic`))
2026-08-16 00:08:12 +00:00
|
|
|
``('host', port)`` for TCP, filesystem-path pairs for UDS and the
|
|
|
|
|
proto-keyed ``('tipc', stype, instance, scope)`` for TIPC. For
|
Write the big boi docs content tree
Replace the ancient `docs/index.rst` (still teaching
`tractor.run()`, `@stream` + arbiters..) with a full ~32 page tree
teaching ONLY the current api (`.wait_for_result()`, registrar
naming, `@context` + `open_context()` as the core model),
- landing: hero example, feature cards + canon links,
- `start/`: install + a 4-example quickstart on-ramp,
- `explain/`: an "SC across processes" essay distilling the essence
per #157's orig ask + a runtime architecture tour,
- `guide/`: 12 task-focused pages incl the flagship multi-process
debugging walkthrough, `Context` + `MsgStream` deep-dives,
cancellation semantics (self-vs-cross cancel rules), discovery,
infected `asyncio`, typed msging + the #126 testing-tips page,
- `api/`: 10 curated autodoc pages (all targets import-verified vs
the reorg'd subpkg tree),
- `project/`: changelog include, ported dev-tips (drops old
`docs/dev_tips.rst`) + roadmap.
Every code block is a `literalinclude` from `examples/`
- zero duplication, all CI-run - w/ `d2` figs floated
into the RHS margin per the 3-col design. Build is green; the 24
remaining warnings all source from lib docstring rst-isms or legacy
`NEWS.rst` content.
Substantially resolves #157 (refine round pending); chips at #175 +
#126.
Prompt-IO: ai/prompt-io/claude/20260611T175152Z_8526985c_prompt_io.md
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
2026-06-11 19:17:14 +00:00
|
|
|
the full layering story — transport protocols, the IPC server,
|
|
|
|
|
address types and the msg loop — see
|
|
|
|
|
:doc:`/explain/architecture`.
|
|
|
|
|
|
|
|
|
|
.. currentmodule:: tractor
|
|
|
|
|
|
|
|
|
|
``Channel``
|
|
|
|
|
-----------
|
|
|
|
|
|
|
|
|
|
.. autoclass:: Channel
|
|
|
|
|
:members: from_addr,
|
|
|
|
|
send,
|
|
|
|
|
recv,
|
|
|
|
|
aclose,
|
|
|
|
|
connected,
|
|
|
|
|
apply_codec,
|
|
|
|
|
aid,
|
|
|
|
|
laddr,
|
|
|
|
|
raddr,
|
|
|
|
|
closed
|
|
|
|
|
|
|
|
|
|
.. deprecated:: 0.1.0a6
|
|
|
|
|
|
|
|
|
|
``Channel.uid`` warns; use :attr:`Channel.aid` which carries
|
|
|
|
|
richer (optional) identity fields beyond the legacy
|
|
|
|
|
``(name, uuid)`` pair.
|
|
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
|
|
You rarely construct a :class:`Channel` yourself — the runtime
|
|
|
|
|
hands them out via :attr:`Portal.chan <tractor.Portal.chan>`
|
|
|
|
|
and :attr:`Context.chan <tractor.Context.chan>`. Treat the
|
|
|
|
|
send/recv surface as advanced API: normal apps should speak
|
|
|
|
|
:class:`~tractor.MsgStream` instead.
|
|
|
|
|
|
|
|
|
|
Choosing a transport
|
|
|
|
|
--------------------
|
|
|
|
|
|
|
|
|
|
.. literalinclude:: ../../examples/uds_transport_actor_tree.py
|
|
|
|
|
:caption: examples/uds_transport_actor_tree.py
|
|
|
|
|
:language: python
|
|
|
|
|
|
|
|
|
|
Logging
|
|
|
|
|
-------
|
|
|
|
|
|
|
|
|
|
``tractor.log`` provides the structured, colorized console
|
|
|
|
|
logging used across the runtime — with actor-name + task-aware
|
|
|
|
|
record headers and extra log levels below :data:`logging.DEBUG`
|
|
|
|
|
(``'transport'``, ``'runtime'``, ``'cancel'``, ``'devx'``) for
|
|
|
|
|
spelunking the runtime itself. Use it for your app too: it's
|
|
|
|
|
already distributed-system aware.
|
|
|
|
|
|
|
|
|
|
.. currentmodule:: tractor.log
|
|
|
|
|
|
|
|
|
|
.. autofunction:: get_logger
|
|
|
|
|
|
|
|
|
|
.. autofunction:: get_console_log
|
|
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
|
|
The ``TRACTOR_LOGLEVEL`` env var overrides any caller-passed
|
|
|
|
|
``loglevel`` (e.g. to ``open_root_actor()``) so you can crank
|
|
|
|
|
console verbosity without touching code; subactors inherit
|
|
|
|
|
the root's level by default.
|
|
|
|
|
|
|
|
|
|
.. seealso::
|
|
|
|
|
|
|
|
|
|
:doc:`/explain/architecture` for the transport/server
|
|
|
|
|
internals, :doc:`/api/discovery` for how channel addresses
|
|
|
|
|
get registered and found, and :doc:`/api/msg` for the codec
|
|
|
|
|
layer every channel speaks.
|