The `_pubsub.pub` decorator's usage example predates several API
generations: ancient positional-arg-order `run_in_actor()` (a
missing `await` too) plus the deprecated `portal.result()` — and
`run_in_actor()` never allowed streaming funcs anyway. Show the
canonical `start_actor()` + `Portal.open_stream_from()`
consumption instead (#477 removal sweep).
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
The 8-page docs sweep of the #477 removal, ahead of the API's
excision,
- `start/quickstart.rst`: the first-actor-tree walkthrough now
narrates the (migrated) `to_actor.run()` example — no portal
in hand until the daemon section introduces `start_actor()`.
- `guide/spawning.rst`: the one-shot section becomes
`to_actor.run()` (blocking call, placement opts, "built on the
primitives" note); lifetime/teardown rules update — one-shots
never make it to nursery exit since each is reaped inside its
own call.
- `guide/rpc.rst`: the `wait_for_result()` section (an API that
dies with the reap cluster, incl. the `NoResult` sentinel)
becomes a `to_actor.run()` one-shot section.
- `api/core.rst`: drop `run_in_actor`/`wait_for_result` from the
autodoc member lists, drop the `Portal.result()` deprecation
note, add a "One-shot task actors" `tractor.to_actor.run`
autodoc section.
- `guide/{asyncio,context,cancellation,parallelism}.rst`:
mention swaps to the successor API.
Gate: `make -C docs html` builds clean; `to_actor.run` autodoc
renders in `api/core.html`.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
The 8 `examples/debugging/` scripts driven by the pexpect'd
`test_debugger.py` REPL-flows (#477 removal),
- blocking one-shots (`subactor_error`, `subactor_breakpoint`,
`shielded_pause`): straight `to_actor.run(fn, an=an)` — the
boxed error/`BdbQuit` raises in the root's task.
- `multi_subactors`: introduces the "collect all errors" pattern
— each one-shot catches + stashes its `RemoteActorError` (vs
raising) so no child's crash cancels its siblings before
they've had their own REPL sessions, then a
`BaseExceptionGroup` of the lot raises at the end; preserves
the legacy teardown-reap REPL flow exactly (28/28 debugger
suite unchanged).
- `multi_nested_subactors_error_up_through_nurseries` +
`root_cancelled_but_child_is_in_tty_lock`: recursive
`spawn_until` levels each block on their one-shot child; the
parallel spawner-trees run as bg task-nursery one-shots where
the first tree's error cancels the other.
- `multi_subactor_root_errors` +
`root_timeout_while_child_crashed`: `start_actor()` + bg
`Portal.run()` tasks so the root's own error/timeout races the
already-crashed children, same as before.
- `sync_bp`: TODO-comment x-ref update only.
`test_debugger.py`: the nested-nurseries test's final-output
patterns update to the new relay shape — the LAST-released leaf
REPL's error chain wins each level's relay-vs-cancel race and
relays as a `collapse_eg()`-annotated collapsed chain, while the
sibling tree is cancelled + absorbed. (The legacy teardown-reap
grouped BOTH the `name_error` and bp-quit chains — explaining
the previously-mysterious "extra" `src_uid`/`relay_uid` patterns
noted in the old TODO.)
Gate: `tests/devx/test_debugger.py` = 28 passed, 6 skipped —
identical to the pre-migration baseline.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
4 example scripts of the #477 removal sweep, each exercised by
`test_docs_examples.py`,
- `actor_spawning_and_causality.py`: the simplest possible
`to_actor.run()` demo — private call-scoped nursery, block on
and print the one-shot's result.
- `remote_error_propagation.py`: blocking `to_actor.run(an=n)`
raises the boxed `AssertionError` in the caller's task,
cancelling the sibling daemons.
- `parallelism/single_func.py`: bg-burn a core in the parent via
a local task-nursery while the one-shot burns (and returns
from) a subactor.
- `a_trynamic_first_scene.py`: donny + gretchen wait on each
*other* so their one-shots run concurrently in a local
task-nursery against a shared `an` (mirrors the migrated
`test_trynamic_trio`).
Gate: all 4 green via the example-runner suite.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
The known-flaky dynamic pubsub test's 3 fire-and-forget spawn
sites (#477 removal),
- the forever-streaming `publisher` + N `consumer` one-shots now
bg-schedule as `to_actor.run(fn, an=n)` tasks in a local `trio`
task-nursery (`publisher`'s rendezvous name still derives from
`fn.__name__`).
- the simulated user-cancel raise (`KeyboardInterrupt` /
`TooSlowError` params) cancels the task-nursery, each one-shot
reaping its subactor via `to_actor.run()`'s shielded
`Portal.cancel_actor()`; `_run_and_match()`'s existing
`BaseExceptionGroup.split()` walk covers the (possibly nested)
relay shapes unchanged.
- spawns now issue concurrently rather than sequentially —
comment on the fork-backend budget updated to match.
Gate: both params x4 runs green on `trio` + x1 on `mp_spawn`;
full module green.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Final `test_cancellation.py` group of the `run_in_actor` removal
(#477) — cancel-mechanics tests, so clean conversions,
- `test_cancel_via_SIGINT_other_task`: the 3 keep-alive
`run_in_actor(sleep_forever)` one-shots become plain
`start_actor()` daemons (an idle daemon needs no "main" task,
and no longer shares a single dup'd `namesucka` name).
- `spawn_sub_with_sync_blocking_task`: the middle layer's spawn
becomes a blocking `to_actor.run(spin_for, an=an)` which parks
awaiting the sync-sleeping grandchild's result until cancelled
from above.
- `test_cancel_while_childs_child_in_sync_sleep`: the
fire-and-forget middle-actor spawn becomes a bg
`to_actor.run()` task in a local task-nursery; the root's
`assert 0` cancels it, driving the same
graceful-cancel-then-zombie-reap cascade on the sync-blocked
grandchild. The `man_cancel_outer` xfail param is unchanged.
Zero live `run_in_actor()` call-sites remain in this suite.
Gate: full `test_cancellation.py` module green on both `trio`
(18p/1xf) + `mp_spawn` (18p/1xf).
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Third `test_cancellation.py` group of the `run_in_actor` removal
(#477),
- `spawn_and_error` fans out each level's erroring one-shots as
concurrent `to_actor.run(fn, an=an)` tasks in a local `trio`
task-nursery (recursing per spawner subactor), as does the
test-body's top-level spawner loop.
- the deterministic exact-breadth nested-BEG shape dies with the
legacy teardown-reap: each level now groups whatever subset of
sub-tree errors relay before the first one's cancel wins, and
a single-member group gets unwrapped by the runtime's own
`collapse_eg()` at every actor boundary — so a fully-raced
tree relays a bare `RemoteActorError` chain.
- loosen the shape walk accordingly: accept a lone
`RemoteActorError` or a 1..breadth group whose members box
`ExceptionGroup` (multi-relay), `AssertionError` (collapsed
leaf chain), `RemoteActorError` (re-boxed collapsed chain) or
`BaseExceptionGroup` (runtime reap-deadline `Cancelled`
upgrade); fold the windows-only tolerances into the same walk.
- raced sibling `trio.Cancelled`s are now ABSORBED by the
task-nursery instead of landing in the group, so the MTF
shape-mismatch xfail should consistently xpass — note added to
drop the marker once CI confirms.
- add an `else: pytest.fail()` so a silently-clean tree can no
longer pass.
Gate: both depths green on `trio` (10 consecutive runs) +
`mp_spawn`.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
`test_nested_multierrors`'s backend/depth budget `match` only
carries arms for the `trio` + `main_thread_forkserver` spawn
backends, so running under any other (e.g. `mp_spawn`) leaves
`timeout` unbound and crashes with an `UnboundLocalError` at the
headroom-scaling below. Add default per-depth arms riding the MTF
budgets (same per-spawn round-trip cost class).
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Second `test_cancellation.py` group of the `run_in_actor` removal
(#477),
- one-shot subactors now run as concurrent `to_actor.run(fn,
an=an)` tasks in a local `trio` task-nursery, so their errors
raise WHILE the actor-nursery block is open (vs the legacy
teardown-reap) and the first error cancels sibling one-shots.
- wrap the task-nursery in `collapse_eg()` so the deterministic
single-error cases still surface a bare `RemoteActorError`.
- loosen the group-shape assertion: the relay-vs-cancel race
populates anywhere from 1 to `num_actors` `RemoteActorError`s
(the exact-`num_actors` BEG was `run_in_actor`'s
reap-all-at-teardown); group members are always
`RemoteActorError` now since sibling `trio.Cancelled`s are
absorbed by the task-nursery.
- move the daemon-portal call loop inside the task-nursery body
so the sleep-forever one-shot case is cancelled by the daemon
error raise.
- rename the `*run_in_actor*` param ids to `*one_shot*`.
Gate: 6 passed on both `trio` + `mp_spawn` backends.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Append two sections to the ria-removal plan capturing the
2026-07-02 hang episode + the resulting design pivot.
Regression writeup: the full-suite hang on
`test_tractor_cancels_aio` root-caused to the step-A reaper
hoist (`5cd190c5`), not the B2 handler merge. The happy-path
`_reap_ria_portals()` parks unbounded on `wait_for_result()`
after a user `portal.cancel_actor()`; the old spawn-backend
reaper raced `soft_kill()`'s scope-cancel, the hoist dropped
it. Records the `proc.poll()` death-watch fix + why poll (not
the event `wait_func`) bc `soft_kill` already awaits
`proc.sentinel` (a 2nd `wait_readable` -> `BusyResourceError`).
Pause writeup: user's insight that the hoist landed in the
wrong scope — result-waiting belongs in the `to_actor`
one-shot scope (`_invoke_in_subactor()`), beside `an` + a
local task-nursery + cancel-scope, where bounding the wait is
trivial + the hang dissolves. So the poll fix is likely
SUPERSEDED (flagged do-not-land); the anti-hang guard commit
(`d1fb4a1a`) stays red-first per the failing-test convention.
(this patch was generated in some part by `claude-code` using
`claude-opus-4-8` (`anthropic`))
First group of the `test_cancellation.py` `run_in_actor` removal
(#477),
- `test_remote_error` -> blocking `to_actor.run()` (single erroring
one-shot; a bad-arg `TypeError` still relays as a
`RemoteActorError`).
- `test_multierror` -> concurrent fan-out via
`gather_contexts([p.open_context(assert_err_ctx) ...])` over
`start_actor()` portals. NB `gather_contexts` is cancel-on-first
so the 2nd errorer is usually cancelled before relaying its own
exc and the pair collapses to a single `RemoteActorError` (vs the
legacy reap-all-at-teardown `BEG`-of-N) — the assertion now
accepts either shape.
- delete `test_multierror_fast_nursery` — a 25-actor stress test of
`run_in_actor`'s teardown-reap; no analogous surface under the
`to_actor` fan-out.
- add an `assert_err_ctx` `@context` shim for the `open_context`
fan-out.
Remaining `test_cancellation` groups (some_cancels_all, nested,
SIGINT, sync-blocking) still on `run_in_actor` — ported next.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Two sites migrated (#477 removal),
- `test_trynamic_trio`: donny + gretchen each wait on the *other*
to register, so they must run CONCURRENTLY — was two
non-blocking `run_in_actor()`s awaited after; now two
`to_actor.run()` one-shots scheduled into a local `trio`
task-nursery.
- the unregister-on-cancel cluster test: its non-streaming branch
spawned `run_in_actor(trio.sleep_forever)` purely to keep each
subactor alive + registered — a `start_actor()` daemon does that
without a "main" task, so the spawn loop collapses to the same
`start_actor()` the streaming branch already used.
Suite: 16 passed.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
`test_multi_actor_subs_arbiter_pub` used `run_in_actor()` to spawn
two forever-ish subscriber actors and hold their portals for a
later `cancel_actor()` (its `.result()` was commented out exactly
because `subs()` never cleanly returns). That deferred-spawn +
cancel shape isn't a blocking `to_actor.run()`, so convert to the
successor primitives (#477 removal),
- `start_actor()` per subscriber — keeps the portal for the
existing `cancel_actor()` teardown,
- run `subs()` on each via a background `Portal.run()` task in a
local `trio` nursery so both subscribe concurrently with the
test's `wait_for_actor` / topic checks,
- each bg runner swallows the `RemoteActorError`/`ContextCancelled`
that `cancel_actor()` relays; a trailing `tn.cancel_scope.cancel()`
drops any lingering runner.
Suite: 8 passed.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Migrate all 4 sites to blocking `tractor.to_actor.run()` (#477
removal),
- rename the two API-named tests to `test_to_actor_run_*`
(`same_func_in_child`, `can_skip_parent_main_inheritance`) —
they exercise the same spawn / `inherit_parent_main` path via
the successor API.
- the recursive `spawn()` helper drops its white-box
`an._children` / portal-`_peers` asserts (which probed
`run_in_actor`'s portal + nursery-tracking internals);
`to_actor.run()` returns the result and reaps internally, so
keep the user-facing `result == 10` check.
- `test_most_beautiful_word` drops the 2nd `wait_for_result()`
(the legacy result-cache re-fetch) — `to_actor.run()` delivers
the value once, no cache.
Suite: 9 passed.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Sole call-site: `run_in_actor(sleep_back_actor, ...)` ->
blocking `tractor.to_actor.run(..., an=n, ...)` (#477 removal).
The RPC-callback subactor is awaited in-caller instead of
reaped at nursery teardown; `name=`/`enable_modules=` map to
`to_actor.run()`'s same-named params, the rest to `**fn_kwargs`.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Sole call-site: an inlined `run_in_actor(...).result()` ->
blocking `tractor.to_actor.run(fn, an=an, ...)` (#477 removal).
Behaviour identical — the one-shot's result/error is awaited
in the caller's task rather than reaped at nursery teardown;
the enclosing `move_on_after` still cancels the sub in the
`error_in_child=False` case.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
First test-file of the #477 `.run_in_actor()` removal (blocking
`to_actor.run()` is the successor; the legacy non-blocking one-shot
is dropped, not replaced). All 9 call-sites migrated,
- blocking result/error/streaming-result tests -> `to_actor.run(fn,
an=an, ...)`; the "streaming" ones stream aio<->trio INSIDE the
subactor so the caller only awaits the final result.
- forever-task + cancel tests (`test_tractor_cancels_aio`,
`test_trio_cancels_aio`) -> `start_actor()` +
`Portal.open_context()` + cancel — can't block on a
never-returning task. Adds a small `sleep_forever_aio_ctx`
`@context` shim.
- greens the red `test_tractor_cancels_aio` anti-hang guard from
the prior commit: under the correctly-scoped API the wait is
bounded by the caller's cancel scope, so the hang is structurally
gone — not patched.
Suite: 34 passed, 2 xfailed (trio backend).
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Wrap `test_tractor_cancels_aio`'s `main()` in a
`trio.fail_after(9 * cpu_perf_headroom())` so a wedged remote
runtime can't hang the test forever. This is the blessed
anti-hang guard here bc `pytest-timeout`'s global cap is
intentionally off (it breaks `trio` under the fork backends,
per the `pyproject` NOTE).
The cap is generous + CPU-headroom-scaled bc it's an anti-hang
guard, not a perf assertion. Motivated by the
`._ria_nursery`-removal regression where a wedged ria-reaper
once hung this exact test indefinitely.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Step B2 of the `._ria_nursery` removal (issue #477; see
`ai/conc-anal/ria_nursery_removal_plan.md`). With the 2ndary
nursery gone (step B), the two nested error handlers in
`_open_and_supervise_one_cancels_all_nursery` collapse to one,
- the outer `except (Exception, BaseExceptionGroup,
trio.Cancelled)` existed to catch errors bubbling from the
old `._ria_nursery.__aexit__` reaper-group; that nursery no
longer exists.
- trace shows the outer handler's `raise` was already DEAD: the
inner handler records `errors[uid]` as its first action, so
`errors` is always non-empty by the time anything could reach
the outer handler, and the `finally`'s raise-from-`errors`
always superseded the outer `raise`.
- so fold both into a single `except BaseException as
_scope_err` guarding the lone daemon nursery; the `finally`
(unchanged) still raises the collected `errors` as a single
exc or `BaseExceptionGroup`.
- drop the now-unused `outer_err`/`inner_err` locals.
Behaviour-preserving (net ~30 lines lighter); the big diff is
the one-level de-indent of the handler body. The two remaining
`maybe_wait_for_debugger()` guards collapse to the single
pre-teardown wait.
Prompt-IO: ai/prompt-io/claude/20260702T222544Z_9201a2ed_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
Split from the step-B2 code commit to keep the runtime diff
free of `ai/` meta noise,
- `ai/conc-anal/ria_nursery_removal_plan.md`: add a "Step-B2
outcome" section — the dead-outer-`raise` trace, why the
merge is behavior-preserving, and the gate results.
- `ai/prompt-io/claude/20260702T222544Z_9201a2ed_*`: NLNet
provenance (log + unedited raw) for the step-B2 work.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Step B of the `._ria_nursery` removal (issue #477; see
`ai/conc-anal/ria_nursery_removal_plan.md`). With step A having
rerouted `.run_in_actor()` children onto the daemon nursery,
the 2ndary "run-in-actor" nursery spawns nothing and its stored
ref is never read — pure dead weight,
- collapse the inner `async with trio.open_nursery() as
ria_nursery` layer in
`_open_and_supervise_one_cancels_all_nursery`; `da_nursery` is
now the single nursery for ALL subactors.
- `ActorNursery.__init__` loses the `ria_nursery` param + the
`self._ria_nursery` attr; `start_actor()` loses its `nursery=`
escape-hatch (spawns via `self._da_nursery` directly).
- `._cancel_after_result_on_exit` stays — still the ria-child
discriminator for `_reap_ria_portals()`.
Behavior-preserving: a zero-task `trio.open_nursery()` only adds
a checkpoint. The two error handlers are KEPT (now nested under
the single nursery); merging them changes error/cancel
propagation and is deferred to its own PR (TODO left at the
outer `except`).
Prompt-IO: ai/prompt-io/claude/20260702T172233Z_5cd190c5_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
Split from the step-B code commit to keep the runtime diff
free of `ai/` meta noise,
- `ai/conc-anal/ria_nursery_removal_plan.md`: add a "Step-B
outcome" section — the empty-nursery collapse, why it's
behavior-preserving, the deliberate handler-merge deferral,
and the targeted-gate result.
- `ai/prompt-io/claude/20260702T172233Z_5cd190c5_*`: NLNet
provenance (log + unedited raw) for the step-B work.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Step A of the `._ria_nursery` removal (issue #477 follow-up, see
`ai/conc-anal/ria_nursery_removal_plan.md`): `.run_in_actor()`
children now spawn via the default daemon nursery and their
result-reaping moves up into the `ActorNursery` machinery,
- new `_supervise._reap_ria_portals()`: one
`_spawn.cancel_on_completion()` task per ria child, run AFTER
`._join_procs` is set — replacing the per-child reaper task the
backends formerly spawned (keyed off
`._cancel_after_result_on_exit` membership) which required
routing such children into `._ria_nursery`.
- happy path: reap awaited right after `._join_procs.set()`,
preserving "collect ria results before daemon join" sequencing.
- error path: snapshot ria `(portal, subactor)` pairs (backend
`finally`s pop `._children` as procs reap), `await an.cancel()`,
THEN a 0.5s-bounded reap over the snapshot; anything collectable
is already queued in the local ctx and a parked reaper
self-cleans (`trio.Cancelled` results are never stashed). NB: a
concurrent reap+cancel variant deadlocked `test_multierror` and
a 3s bound blew `test_cancel_while_childs_child_in_sync_sleep`'s
deadline — deats in the plan doc's probe history.
- `spawn/_trio.py` + `spawn/_mp.py`: drop the membership branch,
per-child reaper nursery + now-unused `cancel_on_completion`
imports; the join phase is a bare `soft_kill()`.
`._ria_nursery` is now vestigial (zero spawn users): step B
deletes it + `start_actor()`'s `nursery=` escape hatch and merges
the supervisor's two error handlers.
Prompt-IO: ai/prompt-io/claude/20260702T165806Z_a34aaf98_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
Split from the step-A code commit to keep the runtime diff
free of `ai/` meta noise,
- `ai/conc-anal/ria_nursery_removal_plan.md`: agent-verified
machinery map + 3-step (A/B/C) design + probe history
(reap-relocation deadlock -> sequencing fix -> bound
tighten) + risk register for the `._ria_nursery` excision.
- `ai/prompt-io/claude/20260702T165806Z_a34aaf98_*`: NLNet
provenance (log + unedited raw) for the step-A work.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Demo both flavors of the new API in a runnable script
(auto-collected by `test_docs_examples.py`),
- the fully-implicit one-shot which boots (and tears down) the
actor-runtime around a single `to_actor.run()` call,
- the concurrent "worker-pool-ish" prime-check pattern: a local
`trio` task nursery scheduling one-shots against a shared
caller-managed `an`, mirroring (in miniature) the neighboring
`concurrent_actors_primes.py` example per issue #477.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Cover every placement variant + failure mode of the new
`to_actor.run()`,
- private-nursery one-shot + implicit runtime boot via pass-through
`runtime_kwargs`,
- remote-error relay to the caller's task (bare and inside a
caller-managed `an`) as boxed `RemoteActorError`s,
- caller-nursery spawn + portal-reuse w/o implicit reap,
- the concurrent "worker-pool-ish" pattern: a local `trio` task
nursery scheduling one-shots against a shared `an`,
- the 4 pre-spawn validation rejections (sync fn, async-gen fn,
`portal`+`an` combo, `runtime_kwargs`+placement combo).
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
First cut at the `to_thread`/`to_process`-style "run it over there"
wrapper layer from issue #477: a single-remote-task invocation API
decoupled from the `ActorNursery` spawn machinery, composed purely
from the lower level daemon-actor + portal primitives,
- `to_actor.run(fn, **fn_kwargs)` spawns a subactor via
`ActorNursery.start_actor()`, schedules `fn` as its lone task
with `Portal.run()` and ALWAYS reaps it via a `finally`-scoped
`Portal.cancel_actor()` (whose bounded cancel-req wait is
internally shielded so the reap also runs under caller-scope
cancellation).
- remote errors raise directly in the caller's task as boxed
`RemoteActorError`s, moving error collection/propagation up into
whatever local `trio` scope encloses the call.
- "placement" opts: `portal=` reuses a running actor (no
spawn/reap), `an=` spawns from a caller-managed actor-nursery,
neither opens a private call-scoped `open_nursery()` (implicitly
booting the runtime, tunable via pass-through `runtime_kwargs`).
- fail-fast validation BEFORE any spawn: non-streaming async fn
only (same constraint as `Portal.run()`), `portal=`/`an=` mutual
exclusion and no `runtime_kwargs` alongside a placement opt.
Also,
- x-ref the successor API from `.run_in_actor()`'s deprecation TODO
+ docstring; emitting a formal `DeprecationWarning` waits on
migrating in-repo usage.
- log prompt-io provenance per NLNet policy incl. the driver prompt
file.
Prompt-IO: ai/prompt-io/claude/20260702T154255Z_65bf9df5_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
Copilot's 2nd-pass review (PR #468) caught a regression I landed in
the uds fix: `UDSAddress.get_random()` put the per-call token AFTER
`@{pid}` (`no_runtime_*@{pid}.{token}.sock`), which breaks the
`tractor._testing._reap` matcher
`^(?P<name>.+)@(?P<pid>\d+)\.sock$` — so no-runtime orphan socks
stopped matching and never got reaped/attributed. Move the token
INTO the name (`{prefix}.{token}@{pid}.sock`) so the canonical
`@{pid}.sock` suffix stays intact for both that regex and the
`spawn._reap` reconstruction; also bump the token to 8 hex chars.
Also two robustness nits from the same review,
- `tests.conftest._measure_sustained_headroom()`: guard `frac <= 0`
before `1./frac` — a 0/parked-core freq read would
`ZeroDivisionError`, get swallowed by the broad `except` into a
1.0 (no-throttle), defeating the probe on the exact broken box it
should flag; read 0 as max throttle.
- `scripts/cpu-perf-check`: mark the burn procs `daemon=True` and
wrap sampling in `try/finally` so a Ctrl-C / error reaps them
instead of leaving stray CPU hogs.
Regressed-by: 09c50f49 (uds no-runtime token placed after `@pid`)
Found-via: Copilot review #4595803812 (`_testing._reap` regex)
Review: PR #468 (Copilot)
https://github.com/goodboy/tractor/pull/468#pullrequestreview-4595803812
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Finish TODO #2 from PR #468: the last raw `cpu_scaling_factor()`
call-sites still used the static-only check (blind to the
sustained-load power-cap). Point them at the `cpu_perf_headroom()`
SUPERSET — it calls `cpu_scaling_factor()` internally + the
session-cached throttle probe, so it's always >= the old factor
(never LESS headroom, so CI stays green).
Migrated,
- `test_spawning`: the `fail_after(1 * ...)` smoke deadline
(#465-added).
- `test_inter_peer_cancellation`: `this_fast` budget.
- `test_docs_examples`: example-run `timeout`.
- `test_resource_cache`: fan-out `timeout`.
`test_cancellation` already used `cpu_perf_headroom()`; only its
explanatory comments still name the static helper.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
W/o a live runtime `get_random()` named UDS socks purely by
`(prefix, pid)`, so two calls in one proc returned the SAME
`no_runtime_*@{pid}.sock` — the 2nd `.bind()` then tripped
`EADDRINUSE`. Append a per-call `uuid4().hex[:6]` token so
each call yields a distinct sockpath.
This fixes the 3 `tests.discovery.test_tpt_bind_addrs` uds
failures (one registrar + disjoint-bind, two non-registrar
binds) where `reg_addr` and a "random" bind addr aliased —
the uds CI job's only red, surfaced when this branch rebased
onto the newer base that carries those tests.
Scoped to the no-runtime branch ON PURPOSE: the runtime
`{name}@{pid}` convention stays deterministic so
`spawn._reap.unlink_uds_bind_addrs()` can still reconstruct
+ unlink a SIGKILL'd subactor's sock (#454).
Deats,
- `_uds.py`: add `uuid4` import + token in the no-runtime
branch
- `_testing.addr`: tighten `get_rando_addr()` docstring re the
intra-proc per-call token (not just pid-keyed namespacing)
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Both `_burn()` impls (the `cpu-perf-check` script + the
`_measure_sustained_headroom()` probe in `tests.conftest`) grew `x`
~x**2 per iter, so the loop quickly went bigint alloc/mul-bound — a
noisy CPU load + needless memory across N procs. Mask each step to
64-bit for a steady, fixed-width ALU burn (still pegs every core,
which is all the freq probe needs).
Also, `_read_mhz()` opened the sysfs freq files without a ctx-mgr;
`with open(...)` so the FD closes deterministically (matches the
script's own `_read()`).
Review: PR #468 (Copilot)
https://github.com/goodboy/tractor/pull/468
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
`cpu_perf_headroom()` is a strict SUPERSET of `cpu_scaling_factor()`
— it folds in static cpu-freq scaling + the slow-CI bump AND the
sustained-load power-cap throttle probe. Point the timing-deadline
call sites at it so they're robust to sustained throttling too (the
gremlin behind mass `trio` deadline-miss flakes),
- `test_legacy_one_way_streaming`: `time_quad_ex` cancel-deadline +
`test_a_quadruple_example`'s `this_fast` smoke bound.
- `test_cancellation`: `test_cancel_via_SIGINT_other_task` +
`test_fast_graceful_cancel_*` deadlines.
`cpu_perf_headroom >= cpu_scaling_factor` always, so never less
headroom (CI stays green); `cpu_scaling_factor()` remains the
internal static component.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Standalone CLI companion to `cpu_perf_headroom()` (20cb99ec): idle
freq snapshots LIE — every static knob (`governor`, EPP,
`platform_profile`, `scaling_max_freq`) can read "performance"
while a firmware/EC power cap (AMD PPT/STAPM + friends) clamps the
package to ~30% the moment a sustained multi-core load lands,
masquerading as a `trio`-backend deadline-miss "regression" on
byte-identical code.
Deats,
- burns every core for `CPU_PERF_SECS` (default 4s) and samples the
ACHIEVED `scaling_cur_freq` steady-state (post boost-ramp) vs the
package max ceiling,
- exits 0 when the sustained fraction clears
`CPU_PERF_HEALTHY_FRAC` (default 0.45), 1 when throttled — so it
gates a suite run: `scripts/cpu-perf-check && pytest tests/ ...`,
- prints the static knobs first (to show they all read fine) then
the remediation list on failure (`platform_profile` bounce, USB-C
PD replug, `ryzenadj`, reboot) w/ the key reminder: do NOT bump
test budgets — the box is slow, not the code.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Mass `trio` deadline-miss failures on byte-identical code turned
out to be a firmware/EC power-cap (AMD PPT/STAPM) clamping the
all-core sustained clock while every static knob (`governor`,
`scaling_max_freq`, EPP, platform-profile) still read "performance"
— invisible to the existing `cpu_scaling_factor()` check. See
`scripts/cpu-perf-check` + the
`ai/conc-anal/trio_033_cancel_cascade_slowdown_depth3_issue.md`
notes.
Deats,
- add `_measure_sustained_headroom()` to `tests/conftest.py`: a
one-shot ~0.9s all-core burn (explicit `fork`-ctx `mp` procs)
sampling achieved-vs-max freq AFTER the boost window; under a 0.6
gate it returns the full inverse fraction (capped 4x), else 1.0;
best-effort 1.0 on non-linux or any error,
- add `cpu_perf_headroom()`: `max()` of the static scaling factor
and the (session-cached) sustained probe,
- inflate deadline budgets by it in `test_dynamic_pub_sub`, both
`test_clustering` cases, the
`test_multi_nested_subactors_error_through_nurseries` pexpect
waits + `test_nested_multierrors`,
- `xfail(strict=False)` `test_nested_multierrors` depth=3 under
throttle: the deep tree trips tractor's INTERNAL reap deadlines
(`soft_kill`/`hard_kill` `terminate_after=1.6`) minting a
`Cancelled` inside the runtime — not fixable by test-budget
inflation; auto-clears once the box un-throttles.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
`uds_transport_actor_tree.py` (new in 759d46dd) reliably fails on
macOS CI with a bare `returncode 1`. The example forces
`enable_transports=['uds']`, and UDS-on-macOS is otherwise
un-exercised by the matrix (there's no `tpt_proto=uds` macOS job),
so it's the first thing to surface a macOS UDS-path issue.
It passes cleanly on Linux, and the peer-cred paths are already
platform-guarded + graceful (`get_peer_info`/SO_PEERCRED on linux
vs `get_peer_pid`/LOCAL_PEERPID elsewhere) - so the crash is deeper
in the macOS UDS stack. The test swallows the subproc stderr (only
re-raises when the last line has "Error"), so the exact failure
can't be pinned from CI logs; needs a macOS box to root-cause.
Skip it on `_friggin_macos and ci_env` (same shape as the existing
`full_fledged_streaming_service` skip) so #460 lands green; the
macOS UDS root-cause is a follow-up.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
The `context_handshake` sequence diagram only showed the graceful
`Return` ending - underselling the whole SC pitch (errors + cancels
propagate *both* ways across the wire). Add a "... or, instead of a
graceful Return" group with the non-graceful endings,
- parent-initiated: `ctx.cancel()` (or a parent-side error) ->
child relays `Error: ContextCancelled`,
- child-initiated: child ships `Error: <raised>` (or
`ContextCancelled`).
Labelled `Error: ...` since `ContextCancelled` is an exception that
rides inside an `Error` wire msg, not its own msg type - keeping
the diagram's wire-level labels honest. Re-render the committed
`_diagrams/context_handshake.svg` fallback (CI has no `d2` bin) to
match.
Also cache-bust d2 images in `d2diagrams.py`: sphinx tags css/js
with `?v=<hash>` but not images, so an edited diagram kept serving
the browser's stale copy at the stable `_images/<stem>.svg` url
(cost us a manual hard-refresh). Hash each rendered svg + rewrite
only the d2 `<img src>` to `...svg?v=<hash8>` via the
`html-page-context` hook - content-addressed, so unchanged diagrams
keep their query.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Continuing the README slim-down: stop inlining content that now
lives (and renders better) on the GitHub Pages site, and just
point readers there.
- "Where do i start" drops the SC reading-list links in favor of
a single nudge to the docs quickstart.
- "Example codez" drops the full `we_are_processes.py` listing -
keep the one-minute pitch prose + the docs/examples links.
- "What's on the TODO" collapses the inline bullet list down to a
link to the docs roadmap ("what the future holds").
Also,
- prune the now-dead RST link targets (`blog post`, `trio docs`,
`SC`, `libdill-docs`, `async sandwich`, `messages`, ..).
- swap the `|docs|` badge from readthedocs over to the GitHub
Pages `docs.yml` action badge + `goodboy.github.io` target.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Continuing the README slim-down: stop inlining content that now
lives (and renders better) on the GitHub Pages site, and just
point readers there.
- "Where do i start" drops the SC reading-list links in favor of
a single nudge to the docs quickstart.
- "Example codez" drops the full `we_are_processes.py` listing -
keep the one-minute pitch prose + the docs/examples links.
- "What's on the TODO" collapses the inline bullet list down to a
link to the docs roadmap ("what the future holds").
Also,
- prune the now-dead RST link targets (`blog post`, `trio docs`,
`SC`, `libdill-docs`, `async sandwich`, `messages`, ..).
- swap the `|docs|` badge from readthedocs over to the GitHub
Pages `docs.yml` action badge + `goodboy.github.io` target.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
The reworked `we_are_processes.py` (now `Context`-API based) prints
different stdout, so the hardcoded expected-output block went
stale: swap the old `Yo, i'm 'worker_N'...` / "self-destruct in 1
sec" lines for the real run - "self-destruct in 2s.." then the
per-worker `Started ep-task in subactor,` / `N::'worker_N'@<pid>`
blocks.
Also retell the prose to match: subs spawn concurrently from bg
`trio` tasks, each runs a `@tractor.context` `endpoint()` that
`ctx.started()`-hands its name + pid back through
`Portal.open_context()`, then parks in `trio.sleep_forever()`
before the root crashes + the tree is reaped.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
The README inlined six example scripts; per our own "point at
`examples/`, don't duplicate" philosophy that's a lot of rot
surface. Drop all but the showcase and rework it onto the modern
`Context` API to mirror the docs landing + `we_are_processes.py`:
spawn a subactor per core, `open_context()` each, crash the root,
reap the tree.
Replace the rest with a short "want more?" pointer to the docs site
+ the `examples/` dir (where the debugger, streaming, cancellation,
`asyncio`, msging + cluster demos all live, CI-run).
Also tidy a few nits while here,
- fix the title typo "structurred" -> "structured",
- close the unterminated quote in the `UV_PROJECT_ENVIRONMENT`
install snippet,
- add the blank line a nested `trionics` bullet list needs so the
PyPI long-desc (this file) renders as valid RST.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
`run_in_actor()` is slated to become a hilevel wrapper
(`runtime/_supervise.py` "TODO: DEPRECATE THIS"), so the showcase
`we_are_processes.py` shouldn't lead with it. Move it to the modern
API: each `worker_<i>` subactor runs a `@tractor.context`
`endpoint()` that `started()`-hands its name + pid back over
`Portal.open_context()` and parks; the root sleeps then raises on
purpose so the runtime reaps the whole tree (zero zombies).
The subs spawn concurrently from bg `trio.Task`s so each child's
cold `import tractor` (~0.4s, see #470) overlaps instead of
stacking; a comment flags the coming `main_thread_forkserver`
backend (#463) which'll make serial spawns cheap enough to just
loop.
Match the landing prose to the snippet — name the `Context` +
`started()` handshake it now leads with.
Also, document `--watch examples` on the `sphinx-autobuild` cmds so
edits to `literalinclude`-d example scripts (which live outside
`docs/`) live-reload too.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
The gh-pages deploy workflow already exists (build on PR + main,
deploy on main push via `actions/deploy-pages`); wire up the sphinx
side,
- `sphinx.ext.githubpages`: emits a `.nojekyll` so Pages serves the
`_static/` + `_images/` dirs (Jekyll otherwise drops `_`-prefixed
paths, breaking every asset),
- `html_baseurl`: the canonical site root
(`https://goodboy.github.io/tractor/`) for the `<link
rel="canonical">` + `og:url` tags.
The one remaining (one-time, manual) step is the repo setting:
Settings -> Pages -> Source = "GitHub Actions".
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Rework the landing top into a left-anchored hero row and match the
navbar branding to it.
- `index.rst` + new `tractor_hero.html`: an inline-svg hero
(`[logo] distributed structured concurrency`) with a full-width
sub-tagline, plus a single screen-reader-only `<h1>` ("tractor")
so the section headings become proper `<h2>` (was 4x `<h1>`), and
the intro prose reflowed into 3 bullets,
- `conf.py`: a `logo.text` ("tractor") beside the navbar wireframe,
polars-style,
- `custom.css`: the hero-row layout (logo + tagline + sub-line,
single row on desktop / stack on mobile), the navbar brand styled
like the centered nav tabs with `display:inline-block` to kill
the parent link's propagated hover-underline, and smaller landing
section headings w/ their `tl;dr` margin-note pulled level.
The hero linework stays `fill: currentColor` so the whole thing
flips with the light/dark toggle.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Capture the (easy-to-forget) logo recolour + theme-preview flow,
- new `notes_to_self/svgtool.py`: a headless-firefox svg helper
(`colors`/`recolor`/`preview`/`page`); its `page --theme
dark|light` injects a `localStorage` pin so a pydata `auto`-mode
build renders its dark variant in a screenshot — the only way to
verify theme-adaptive bits headlessly,
- `howtodocs.md`: a "Tweaking the logo" table (which file +
`color:` knob per context) and an `svgtool` section that breaks
down the `--theme` trick for the sphinx-rusty.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Carry the landing hero's transparent-faces wireframe look to the
two other logo contexts. An `<img>`-embedded svg can't read the
page CSS (no `currentColor`), so the colours are baked per target,
- navbar: 2 variants (`tractor_logo_nav_light.svg` near-black
lines, `…_nav_dark.svg` near-white) wired via the pydata
`logo.image_light`/`image_dark` opts so it swaps with the theme
toggle, matching the hero,
- README: `tractor_logo_wire.svg` — one neutral-grey, with INLINE
fills (no `<style>`) so it reads on both GitHub light + dark and
survives GitHub's svg sanitiser.
Faces are `fill: none` throughout; the filled `tractor_logo_side`
stays the recolour source + favicon.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Swap the landing-page hero from a static `<img>` (white-faced —
which glared as a light box on the dark theme) to an INLINE svg
whose linework uses `fill: currentColor` and whose faces are
transparent. The wireframe now inherits the theme text colour
(`svg.hero-logo { color: var(--pst-color-text-base); }`) and the
page background shows through, so it flips correctly with the
light/dark toggle.
- `tractor_logo_hero.html`: the inline svg partial (`.st0` ->
`currentColor`, `.st1` -> `none`), `.. raw:: html :file:`-d into
`index.rst`,
- the shared `tractor_logo_side.svg` is untouched here (navbar +
favicon still ride it).
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Add a "Share on your LAN" blurb to both docs how-to homes
(`notes_to_self/howtodocs.md` + the dev-tips "Building these docs"
section): bind the server to all ifaces — via `sphinx-autobuild
--host 0.0.0.0` (live-reload) or `python -m http.server --bind
0.0.0.0` (static) — so a peer on your subnet can hit
`http://<lan-ip>:8000` (`hostname -I` prints the ip).
Verified a LAN-ip `curl` returns 200 + the socket binds `0.0.0.0`;
includes a trusted-LAN-only caveat since it's an unauthenticated
server on every interface.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Collect the sphinx build + live-preview one-liners (incl. the nix
`.#docs` opt-in shell and the `d2` diagram specifics) so
contributors don't have to reverse-engineer them,
- new `notes_to_self/howtodocs.md` terse cheat-sheet (force-added
past the `notes_to_self/` ignore, same as `howtorelease.md`),
- a rendered "Building these docs" section in the dev-tips guide
(`docs/project/dev-tips.rst`),
- a README pointer to the note.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Gud Boi
Bd