Remove `run_in_actor()` + the ria reap cluster

The final excision of #477: with zero in-repo callers left (all
tests/examples/docs migrated to `to_actor.run()` et al) the
entire legacy one-shot machinery drops out,

- `runtime/_supervise.py`: `ActorNursery.run_in_actor()`, the
  `._cancel_after_result_on_exit` portal-set and the
  `_reap_ria_portals()` teardown-reaper (both its happy-path
  block-exit call AND the error-path snapshot + 0.5s-bounded
  collection) are deleted — one-shot result-waiting now lives
  entirely in the caller's task via `to_actor.run()`, whose
  enclosing cancel-scope bounds the wait by construction (the
  correct-scoping fix for the unbounded-reap hang class; the
  `d1fb4a1a` guard test now passes structurally).
- `runtime/_portal.py`: `Portal._submit_for_result()`,
  `._expect_result_ctx`, `._final_result_msg/_pld`,
  `.wait_for_result()` + the deprecated `.result()` alias are
  gone — a `Portal` no longer has any "main result" notion.
  NB `Context.wait_for_result()` is a different (very alive)
  API and is untouched.
- `spawn/_spawn.py`: `exhaust_portal()` +
  `cancel_on_completion()` (the reaper tasks) deleted; backend
  comment sweeps in `_trio.py`/`_mp.py`.
- `_exceptions.py`: the `NoResult` sentinel dies with its lone
  reader.
- `tests/test_ringbuf.py`: drop a daemon-portal `.result()`
  call that was already a warn + `NoResult` no-op (the ctx-acm
  exit does the real result-wait); unshadow the 2nd `sctx` as
  `rctx`.
- comment/docstring x-ref sweeps: `msg/types.py`,
  `_context.py`, `to_actor/`, `tests/test_to_actor.py`.

Gate: `test_to_actor test_spawning test_cancellation
test_infected_asyncio test_local test_rpc` = 81 passed,
3 xfailed on `trio`; +`test_ringbuf` = 70 passed, 3 skipped,
3 xfailed on `mp_spawn`.

(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code

ai/conc-anal/ria_nursery_removal_plan.md

@@ -276,6 +276,97 @@ Gate (box ran ~2.7x slow this session, load-induced
   completion). RECOMMEND a clean full-suite run on a
   normal-speed box before this merges.
 
+## Regression + fix: ria-reap hang (2026-07-02)
+
+Human hit a full-suite hang on
+`test_infected_asyncio.py::test_tractor_cancels_aio`. Bisected:
+passes at pre-ria `a34aaf98` (0.59s), hangs at B2 `e617b498`
+(90s+). Root-caused to the STEP-A reaper hoist (`5cd190c5`),
+NOT B2 (`_reap_ria_portals` is byte-identical A->B2).
+
+Bug: the test does `run_in_actor(asyncio_actor)` then a USER
+`portal.cancel_actor()` and exits the block cleanly -> the
+happy path's `await _reap_ria_portals()`, which waits UNBOUNDED
+on `cancel_on_completion -> wait_for_result()`. The child was
+cancelled out-of-band so no final result is relayed -> parked
+forever. The OLD spawn-backend reaper was raced against
+`soft_kill()` (per-child nursery `cancel_scope.cancel()` on
+subproc death); the hoist dropped that race.
+
+Fix: `_reap_ria_portals()` runs each `cancel_on_completion()`
+in a local nursery alongside a `proc.poll()` death-watch that
+cancels the parked reaper once the subproc exits — restoring
+the old race, backend-agnostic (guarded by
+`hasattr(proc, 'poll')` for a future `subint` handle).
+
+Why POLL (`proc.poll()`) not the event-driven `wait_func`:
+the mp waiter (`_spawn.proc_waiter`) does
+`wait_readable(proc.sentinel)`, and `soft_kill()` is ALREADY
+awaiting that same fd concurrently in the daemon nursery — a
+2nd `wait_readable` on one fd raises `trio.BusyResourceError`.
+(`trio.Process.wait()` IS multi-waiter-safe, but mp has no
+async equivalent.) `proc.poll()` — the same liveness check
+`soft_kill` itself falls back to — is the conflict-free common
+denominator. Verified: poll-fix passes on BOTH trio and
+mp_spawn.
+
+Also added a per-test anti-hang guard: wrapped
+`test_tractor_cancels_aio`'s `main()` in
+`with trio.fail_after(9 * cpu_perf_headroom())` — the blessed
+pattern (`pytest-timeout`'s global cap is intentionally off;
+breaks trio under fork backends, see `pyproject` NOTE). So a
+future recurrence FAILS FAST instead of hanging the suite.
+(Several other tests in the file are still guardless —
+`test_aio_simple_error`, `test_trio_error_cancels_intertask_chan`,
+`test_aio_errors_and_channel_propagates_and_closes` — candidate
+follow-up sweep.)
+
+Lesson: the B2 focused gate OMITTED `test_infected_asyncio`
+(and the full runs were clipped/slow), so the step-A hang
+slipped through. Any future ria-touching change MUST gate
+`test_infected_asyncio` explicitly.
+
+Gate: `test_tractor_cancels_aio` green (trio 1.53s, mp 3.98s);
+fix gate (`test_infected_asyncio test_cancellation test_to_actor
+test_spawning`) = 74 passed, 3 xfailed, 0 failures.
+
+## PAUSED (2026-07-02): re-assess the reaper's SCOPE
+
+User's insight (compelling — likely the real root cause of
+the hang, not just the missing proc-death race):
+
+> the "hoisting" of 5cd190c5 was just not really done right
+> — the hoist should have been into the `to_actor` scope,
+> not `_supervise`.
+
+The argument: `.run_in_actor()`'s result-waiting/reaping got
+hoisted into `_supervise._reap_ria_portals` (nursery-machinery
+scope), which has NO natural cancel-scope to bound a parked
+`wait_for_result()` — hence the awkward proc-death race +
+the poll-vs-`proc_waiter` dilemma. If the result-wait instead
+lived in the `to_actor` one-shot scope
+(`to_actor._invoke_in_subactor()`), it would sit right next to
+the caller's `an` + a local `trio` task-nursery + cancel-scope
+(the `trio.to_thread`-style model #477 actually wants) — so
+bounding/cancelling the wait is trivial and the hang
+dissolves from correct scoping rather than a bolt-on race.
+
+Follow-on to re-evaluate on resume:
+- should `_reap_ria_portals` exist AT ALL, or should
+  result-waiting move entirely into
+  `to_actor._invoke_in_subactor()`?
+- reimplement legacy `run_in_actor()` on top of
+  `to_actor.run()` so `_reap_ria_portals` +
+  `_cancel_after_result_on_exit` can be DROPPED from
+  `_supervise` entirely (the true #477 simplification)?
+- the poll-vs-event decision is MOOT under this re-scoping.
+
+State at pause: `test_infected_asyncio` anti-hang guard
+COMMITTED (`d1fb4a1a`, intentionally red w/o the fix — the
+user's failing-test-first convention). The poll-based reap
+fix in `_supervise.py` is UNCOMMITTED and likely SUPERSEDED
+by the re-scoping — do NOT land it as-is.
+
 ## Verification gate
 
 - `tests/test_cancellation.py test_spawning.py test_local.py

docs/api/core.rst

@@ -37,7 +37,6 @@ Spawning actors
 
 .. autoclass:: ActorNursery
    :members: start_actor,
-             run_in_actor,
              cancel,
              cancel_called,
              cancelled_caught
@@ -47,10 +46,22 @@ Spawning actors
    :meth:`ActorNursery.start_actor` (daemon actor + portal) is the
    blessed spawning primitive; pair it with
    ``Portal.open_context()`` for SC-linked remote tasks.
-   :meth:`ActorNursery.run_in_actor` is a *convenience* one-shot —
+
-   spawn, run a single task, auto-cancel after the result — slated
+One-shot task actors
-   to be rebuilt as a high-level wrapper, so don't design around
+--------------------
-   it as the core model.
+
+.. autofunction:: tractor.to_actor.run
+
+.. note::
+
+   :func:`tractor.to_actor.run` (parlance of
+   ``trio.to_thread.run_sync()`` and friends) is the
+   *convenience* one-shot — spawn, run a single task, block on
+   its result, reap — built entirely on
+   :meth:`ActorNursery.start_actor` + :meth:`Portal.run` +
+   :meth:`Portal.cancel_actor`, so don't design around it as the
+   core model. It supersedes the removed (legacy, non-blocking)
+   ``ActorNursery.run_in_actor()``.
 
 .. deprecated:: 0.1.0a6
 
@@ -71,14 +82,12 @@ flowing back `exactly like trio`_.
    :members: run,
              run_from_ns,
              open_stream_from,
-             wait_for_result,
              cancel_actor,
              chan
 
 .. deprecated:: 0.1.0a6
 
-   ``Portal.result()`` warns; use :meth:`Portal.wait_for_result`.
+   The str-form ``Portal.run('mod.path', 'fn_name')`` warns;
-   The str-form ``Portal.run('mod.path', 'fn_name')`` also warns;
    pass a function *object* whose module is listed in the target's
    ``enable_modules``. ``Portal.channel`` is the legacy spelling
    of :attr:`Portal.chan`.

docs/guide/asyncio.rst

@@ -76,8 +76,8 @@ Just flip the flag on :meth:`tractor.ActorNursery.start_actor`:
             infect_asyncio=True,
         )
 
-The one-shot convenience ``ActorNursery.run_in_actor()`` accepts
+The one-shot convenience ``tractor.to_actor.run()`` accepts the
-the same flag. The ``to_asyncio`` APIs may **only** be called from
+same flag. The ``to_asyncio`` APIs may **only** be called from
 tasks inside an infected actor; calling them anywhere else raises
 a loud ``RuntimeError``. You can introspect at runtime with
 ``tractor.current_actor().is_infected_aio()``.
@@ -229,7 +229,7 @@ dialog, skip the channel ceremony and use
 
 It schedules the fn as an ``asyncio.Task``, waits for completion
 and hands the return value back to ``trio``; think of it as the
-cross-loop sibling of ``ActorNursery.run_in_actor()``. Errors and
+cross-loop sibling of ``tractor.to_actor.run()``. Errors and
 cancellation are translated exactly as for channels.
 
 Cross-loop errors and cancellation

docs/guide/cancellation.rst

@@ -64,11 +64,13 @@ What's going on here?
 - three healthy actors are spawned as daemons via
   :meth:`tractor.ActorNursery.start_actor`; left alone they'd
   happily idle forever,
-- a fourth actor runs ``assert_err()`` via ``.run_in_actor()`` and
+- a fourth actor runs ``assert_err()`` via a blocking
-  promptly trips its ``assert 0``,
+  ``tractor.to_actor.run()`` one-shot and promptly trips its
+  ``assert 0``,
 - the resulting ``AssertionError`` ships back over IPC as a
-  serialized error msg and re-raises *boxed* inside the nursery
+  serialized error msg and re-raises *boxed* right at the call
-  block as a :class:`tractor.RemoteActorError`,
+  inside the nursery block as a
+  :class:`tractor.RemoteActorError`,
 - the nursery reacts like any ``trio`` nursery would: it cancels
   the three healthy siblings (graceful runtime-cancel requests,
   acks awaited), reaps all four processes, then re-raises,

docs/guide/context.rst

@@ -15,8 +15,8 @@ a single `structured concurrency`_ (SC) scope over IPC.
    :alt: sequence diagram of the context handshake msg flow
 
 Pretty much everything else is (or is slated to be) built on this
-one primitive: ``ActorNursery.run_in_actor()`` is a convenience
+one primitive: ``tractor.to_actor.run()`` is a convenience for
-for "spawn, open a context, await the result, tear down"; plain
+"spawn, run the lone task, await the result, tear down"; plain
 ``Portal.run()`` RPC is planned to be re-implemented on top of it;
 the multi-process debugger's tree-wide REPL lock rides one. Grok
 this page and the rest of the library reads as convenience

docs/guide/parallelism.rst

@@ -119,15 +119,16 @@ Run a func in a process
 
 Even a pool can be overkill; "run this one async func in a
 subprocess and give me the result" is a one-liner via
-:meth:`tractor.ActorNursery.run_in_actor`,
+:func:`tractor.to_actor.run`,
 
 .. literalinclude:: ../../examples/parallelism/single_func.py
    :caption: examples/parallelism/single_func.py
    :language: python
 
-``run_in_actor()`` is a *convenience wrapper* — spawn an actor, run
+``to_actor.run()`` is a *convenience wrapper* — spawn an actor,
-exactly one task in it, reap on result — not the core spawning
+run exactly one task in it, block on and return its result, reap
-model (that's :meth:`tractor.ActorNursery.start_actor` plus
+— not the core spawning model (that's
+:meth:`tractor.ActorNursery.start_actor` plus
 :meth:`tractor.Portal.open_context`; see :doc:`/guide/context`).
 But for this fire-and-collect shape it's exactly the right amount
 of typing.

docs/guide/rpc.rst

@@ -80,28 +80,30 @@ One special namespace exists: ``'self'`` resolves to the remote
 how internal machinery (cancel requests, registry ops) travels;
 don't build your app on it.
 
-One-shot results: ``wait_for_result()``
+One-shot subactors: ``to_actor.run()``
----------------------------------------
+--------------------------------------
-A portal returned from
+When a subactor's *entire job* is a single function call, skip
-:meth:`~tractor.ActorNursery.run_in_actor` has exactly one
+the portal plumbing with :func:`tractor.to_actor.run`: spawn,
-"main" task running remotely; that task's ``return`` value is
+run the lone task, return its result and reap the process — all
-delivered as the portal's *final result*:
+in one blocking call:
 
 .. code:: python
 
-    portal = await an.run_in_actor(fib, n=10)
+    final = await tractor.to_actor.run(fib, an=an, n=10)
-    final = await portal.wait_for_result()
 
 Semantics worth knowing:
 
 - it blocks until the remote task returns, re-raising any
-  remote error in the usual boxed form.
+  remote error in the usual boxed form right in the calling
-- once resolved it's idempotent: later calls return the same
+  task.
-  cached value.
+- "placement" is composable: ``an=`` spawns from an existing
-- a *daemon* portal (from ``start_actor()``) has no main task,
+  actor-nursery, ``portal=`` reuses an already-running actor
-  so there's no final result to wait for: you'll get a warning
+  (no spawn/reap, just a ``Portal.run()``), and passing
-  plus a ``NoResult`` sentinel. Results of individual daemon
+  neither opens a private call-scoped nursery (booting the
-  calls come straight back from each ``await portal.run()``.
+  runtime if needed).
+- concurrency composes the plain ``trio`` way: schedule
+  multiple ``run()`` calls into a local task nursery (see
+  ``examples/parallelism/to_actor_one_shots.py``).
 
 Pure RPC daemons: ``run_daemon()``
 ----------------------------------

docs/guide/spawning.rst

@@ -103,19 +103,22 @@ What's going on here?
   on him **forever**. Daemon lifetimes are *yours* to end; that
   explicitness is the point.
 
-``run_in_actor()``: quick one-shot parallelism
+``to_actor.run()``: quick one-shot parallelism
 ----------------------------------------------
-:meth:`~tractor.ActorNursery.run_in_actor` is the convenience
+:func:`tractor.to_actor.run` is the convenience wrapper: spawn
-wrapper: spawn an actor, run exactly one async function in it,
+an actor, run exactly one async function in it, block on the
-then reap the process as soon as the result arrives.
+result, then reap the process — the distributed sibling of
+``trio.to_thread.run_sync()``.
 
 .. code:: python
 
-    async with tractor.open_nursery() as an:
+    async with (
-        portal = await an.run_in_actor(burn_cpu)
+        tractor.open_nursery() as an,
+        trio.open_nursery() as tn,
+    ):
         # burn rubber in the parent too...
-        await burn_cpu()
+        tn.start_soon(burn_cpu)
-        total = await portal.wait_for_result()
+        total = await tractor.to_actor.run(burn_cpu, an=an)
 
 A few details worth knowing:
 
@@ -124,18 +127,21 @@ A few details worth knowing:
 - the function's module is auto-added to the child's
   ``enable_modules`` allowlist.
 - extra ``**kwargs`` are forwarded to the function itself.
-- the child is *auto-cancelled* once its "main" result lands;
+- the call blocks until the result (or error) lands and the
-  at nursery exit these run-once children are always reaped
+  child is *auto-cancelled* (reaped) right after — so remote
-  first (causality_ is paramount!).
+  errors raise directly in your calling task (causality_ is
+  paramount!).
+- "placement" composes: ``an=`` spawns from a caller-managed
+  actor-nursery, ``portal=`` reuses an already-running actor
+  (no spawn/reap), and passing neither opens a private
+  call-scoped nursery (booting the runtime if needed).
 
 .. note::
 
-   ``run_in_actor()`` is a convenience, **not** the core model.
+   ``to_actor.run()`` is a convenience, **not** the core model —
-   The source literally marks it for an eventual rebuild as
+   it's built *entirely* on ``start_actor()`` + ``Portal.run()``
-   a thin "hilevel" wrapper on top of
+   + ``Portal.cancel_actor()``. Teach your fingers to use it for
-   :meth:`~tractor.Portal.open_context` (the modern inter-actor
+   quick fire-and-collect parallelism — think a per-function
-   task API). Teach your fingers to use it for quick
-   fire-and-collect parallelism — think a per-function
    trio-parallel_ style one-shot — and reach for
    ``start_actor()`` + ``open_context()`` for anything
    long-lived, stateful or streaming
@@ -145,9 +151,9 @@ Actor lifetimes and teardown order
 ----------------------------------
 So we have two lifetime flavors:
 
-- **run-once** (``run_in_actor()``): lives exactly as long as
+- **one-shot** (``to_actor.run()``): lives exactly as long as
   its single task; reaped the moment its result (or error)
-  arrives.
+  arrives back in the (blocking) call.
 - **daemon** (``start_actor()``): lives until *someone* cancels
   it — an explicit ``await portal.cancel_actor()``, a bulk
   ``await an.cancel()``, or the one-cancels-all strategy kicking
@@ -155,11 +161,12 @@ So we have two lifetime flavors:
 
 On a clean exit of the nursery block the teardown order is:
 
-1. the nursery waits on every run-once actor's final result;
+1. one-shot actors never make it to nursery exit: each is
-   any errors from these are raised immediately so your code
+   reaped inside its own ``to_actor.run()`` call, any error
-   (acting as supervisor) gets first crack at handling them.
+   raising immediately in the calling task so your code
-2. then it waits on daemon actors — **indefinitely**. If you
+   (acting as supervisor) gets first crack at handling it.
-   spawned a daemon, you own its lifetime.
+2. the nursery then waits on daemon actors — **indefinitely**.
+   If you spawned a daemon, you own its lifetime.
 
 When a child *is* cancelled, teardown is graceful-first per SC
 discipline: the runtime sends an IPC cancel request and gives

docs/start/quickstart.rst

@@ -43,24 +43,20 @@ Run it::
 What's going on here?
 
 - ``trio.run(main)`` starts the **root actor**; the ``tractor``
-  runtime boots *implicitly* inside ``tractor.open_nursery()``
+  runtime boots *implicitly* inside ``tractor.to_actor.run()``
   whenever it isn't already up. No special entrypoint, no
   framework takeover - it's just a ``trio`` app,
 - inside ``main()`` a *subactor* is spawned via
-  ``ActorNursery.run_in_actor()`` and told to run exactly one
+  ``tractor.to_actor.run()`` and told to run exactly one
   function: ``cellar_door()``,
-- you get back a ``Portal``: your handle for invoking tasks in
-  the new process's (separate!) memory domain. We lean on it
-  much harder in the next section,
 - the subactor, *some_linguist*, boots a fresh ``trio.run()`` in
   a **new process** and executes ``cellar_door()`` as its *main
   task* (note the child proving it is *not* the root with
   ``tractor.is_root_process()``), then ships the return value
   back over IPC,
-- the parent grabs that *final result* with
+- the call *blocks* until that final result arrives, then
-  ``await portal.wait_for_result()``, much like you'd expect
+  returns it - causality is preserved: your task only proceeds
-  from a "future" - except causality is preserved: the nursery
+  once the child is *done*, dead, and reaped.
-  block only exits once the child is *done*, dead, and reaped.
 
 .. margin:: Just need a worker pool?
 
@@ -71,19 +67,22 @@ What's going on here?
 
 .. note::
 
-   ``run_in_actor()`` is the *convenience* wrapper: one-shot
+   ``to_actor.run()`` (parlance of ``trio.to_thread`` and
+   friends) is the *convenience* wrapper: one-shot
    spawn-run-reap semantics for when a subactor's entire job is
    a single function call. The core primitives are
-   ``ActorNursery.start_actor()`` (next up) paired with
+   ``ActorNursery.start_actor()`` (next up) — which hands you
+   a ``Portal``, your handle for invoking tasks in the new
+   process's (separate!) memory domain — paired with
    ``Portal.open_context()`` for full, SC-linked cross-actor
    dialogs - see :doc:`/guide/context`.
 
 Daemon actors and RPC
 ---------------------
-A ``run_in_actor()``-spawned actor terminates when its main task
+A ``to_actor.run()`` one-shot subactor terminates when its lone
-returns. But often you want long-lived *daemon* actors instead:
+task returns. But often you want long-lived *daemon* actors
-spawned once, then serving (allowlisted) RPC requests until told
+instead: spawned once, then serving (allowlisted) RPC requests
-otherwise. That's ``start_actor()``:
+until told otherwise. That's ``start_actor()``:
 
 .. literalinclude:: ../../examples/actor_spawning_and_causality_with_daemon.py
    :caption: examples/actor_spawning_and_causality_with_daemon.py
@@ -91,9 +90,9 @@ otherwise. That's ``start_actor()``:
 
 Two lifetime rules to internalize:
 
-- a ``run_in_actor()`` actor lives exactly as long as its main
+- a ``to_actor.run()`` one-shot actor lives exactly as long as
-  task; the nursery waits for that function (and thus the
+  its lone task; the call blocks until that function (and thus
-  process) to complete before unblocking,
+  the process) completes,
 - a ``start_actor()`` actor *lives forever* - an RPC daemon the
   nursery will happily wait on **indefinitely** - until some
   task explicitly cancels it via ``Portal.cancel_actor()`` (as

examples/a_trynamic_first_scene.py

@@ -17,27 +17,38 @@ async def say_hello(other_actor):
         return await portal.run(hi)
 
 
+async def run_and_print(
+    an: tractor.ActorNursery,
+    name: str,
+    other_actor: str,
+):
+    print(
+        await tractor.to_actor.run(
+            say_hello,
+            an=an,
+            name=name,
+            # arguments are always named
+            other_actor=other_actor,
+        )
+    )
+
+
 async def main():
     """Main tractor entry point, the "master" process (for now
     acts as the "director").
     """
-    async with tractor.open_nursery() as n:
+    async with (
+        tractor.open_nursery() as an,
+        trio.open_nursery() as tn,
+    ):
         print("Alright... Action!")
 
-        donny = await n.run_in_actor(
+        # both actors wait on the *other* to register so their
-            say_hello,
+        # one-shots must run concurrently.
-            name='donny',
+        tn.start_soon(run_and_print, an, 'donny', 'gretchen')
-            # arguments are always named
+        tn.start_soon(run_and_print, an, 'gretchen', 'donny')
-            other_actor='gretchen',
+
-        )
+    print("CUTTTT CUUTT CUT!!! Donny!! You're supposed to say...")
-        gretchen = await n.run_in_actor(
-            say_hello,
-            name='gretchen',
-            other_actor='donny',
-        )
-        print(await gretchen.wait_for_result())
-        print(await donny.wait_for_result())
-        print("CUTTTT CUUTT CUT!!! Donny!! You're supposed to say...")
 
 
 if __name__ == '__main__':

examples/actor_spawning_and_causality.py

@@ -10,17 +10,14 @@ async def cellar_door():
 async def main():
     """The main ``tractor`` routine.
     """
-    async with tractor.open_nursery() as n:
+    # spawn a subactor, run ``cellar_door()`` as its lone task,
-
+    # block until its result arrives and the subactor is reaped.
-        portal = await n.run_in_actor(
+    print(
+        await tractor.to_actor.run(
             cellar_door,
             name='some_linguist',
         )
-
+    )
-    # The ``async with`` will unblock here since the 'some_linguist'
-    # actor has completed its main task ``cellar_door``.
-
-    print(await portal.wait_for_result())
 
 
 if __name__ == '__main__':

examples/debugging/multi_nested_subactors_error_up_through_nurseries.py

@@ -1,3 +1,5 @@
+from functools import partial
+
 import trio
 import tractor
 
@@ -21,25 +23,36 @@ async def breakpoint_forever():
 async def spawn_until(depth=0):
     """"A nested nursery that triggers another ``NameError``.
     """
-    async with tractor.open_nursery() as n:
+    async with (
+        tractor.open_nursery() as an,
+        trio.open_nursery() as tn,
+    ):
         if depth < 1:
 
-            await n.run_in_actor(breakpoint_forever)
+            tn.start_soon(
-
+                partial(
-            p = await n.run_in_actor(
+                    tractor.to_actor.run,
-                name_error,
+                    breakpoint_forever,
-                name='name_error'
+                    an=an,
+                )
             )
+
             await trio.sleep(0.5)
             # rx and propagate error from child
-            await p.result()
+            await tractor.to_actor.run(
+                name_error,
+                an=an,
+                name='name_error',
+            )
 
         else:
             # recusrive call to spawn another process branching layer of
-            # the tree
+            # the tree; blocks (up) each level until the leaf's
+            # `name_error` relays through.
             depth -= 1
-            await n.run_in_actor(
+            await tractor.to_actor.run(
                 spawn_until,
+                an=an,
                 depth=depth,
                 name=f'spawn_until_{depth}',
             )
@@ -65,35 +78,34 @@ async def main():
              └─ python -m tractor._child --uid ('spawn_until_0', 'de918e6d ...)
 
     """
-    async with tractor.open_nursery(
+    async with (
-        debug_mode=True,
+        tractor.open_nursery(
-        loglevel='pdb',
+            debug_mode=True,
-    ) as n:
+            loglevel='pdb',
-
+        ) as an,
-        # spawn both actors
+        trio.open_nursery() as tn,
-        portal = await n.run_in_actor(
+    ):
-            spawn_until,
+        # spawn both spawner trees as concurrent one-shots; the
-            depth=3,
+        # first tree's (relayed) error cancels the other.
-            name='spawner0',
+        tn.start_soon(
+            partial(
+                tractor.to_actor.run,
+                spawn_until,
+                an=an,
+                depth=3,
+                name='spawner0',
+            )
         )
-        portal1 = await n.run_in_actor(
+        tn.start_soon(
-            spawn_until,
+            partial(
-            depth=4,
+                tractor.to_actor.run,
-            name='spawner1',
+                spawn_until,
+                an=an,
+                depth=4,
+                name='spawner1',
+            )
         )
 
-        # TODO: test this case as well where the parent don't see
-        # the sub-actor errors by default and instead expect a user
-        # ctrl-c to kill the root.
-        with trio.move_on_after(3):
-            await trio.sleep_forever()
-
-        # gah still an issue here.
-        await portal.result()
-
-        # should never get here
-        await portal1.result()
-
 
 if __name__ == '__main__':
     trio.run(main)

examples/debugging/multi_subactor_root_errors.py

@@ -16,11 +16,11 @@ async def spawn_error():
     """"A nested nursery that triggers another ``NameError``.
     """
     async with tractor.open_nursery() as n:
-        portal = await n.run_in_actor(
+        return await tractor.to_actor.run(
             name_error,
+            an=n,
             name='name_error_1',
-            )
+        )
-        return await portal.result()
 
 
 async def main():
@@ -38,29 +38,36 @@ async def main():
         - root actor should then fail on assert
         - program termination
     """
-    async with tractor.open_nursery(
+    async with (
-        debug_mode=True,
+        tractor.open_nursery(
-        loglevel='devx',
+            debug_mode=True,
-    ) as n:
+            loglevel='devx',
+        ) as an,
+        trio.open_nursery() as tn,
+    ):
+        # spawn both actors..
+        portal = await an.start_actor(
+            'name_error',
+            enable_modules=[__name__],
+        )
+        portal1 = await an.start_actor(
+            'spawn_error',
+            enable_modules=[__name__],
+        )
 
-        # spawn both actors
+        # ..and bg-schedule their erroring tasks.
-        portal = await n.run_in_actor(
+        tn.start_soon(portal.run, name_error)
-            name_error,
+        tn.start_soon(portal1.run, spawn_error)
-            name='name_error',
+
-        )
+        # yield to the bg tasks so both RPC requests are
-        portal1 = await n.run_in_actor(
+        # submitted (and start crashing) before the root's own
-            spawn_error,
+        # error below (the legacy `run_in_actor()` submitted
-            name='spawn_error',
+        # in-line with each spawn).
-        )
+        await trio.sleep(0.5)
 
         # trigger a root actor error
         assert 0
 
-        # attempt to collect results (which raises error in parent)
-        # still has some issues where the parent seems to get stuck
-        await portal.result()
-        await portal1.result()
-
 
 if __name__ == '__main__':
     trio.run(main)

examples/debugging/multi_subactors.py

@@ -18,11 +18,11 @@ async def spawn_error():
     """"A nested nursery that triggers another ``NameError``.
     """
     async with tractor.open_nursery() as n:
-        portal = await n.run_in_actor(
+        return await tractor.to_actor.run(
             name_error,
+            an=n,
             name='name_error_1',
         )
-        return await portal.result()
 
 
 async def main():
@@ -36,17 +36,39 @@ async def main():
     `-python -m tractor._child --uid ('spawn_error', '52ee14a5 ...)
        `-python -m tractor._child --uid ('name_error', '3391222c ...)
     """
+    errors: list[BaseException] = []
+
     async with tractor.open_nursery(
         debug_mode=True,
         # loglevel='runtime',
-    ) as n:
+    ) as an:
 
-        # Spawn both actors, don't bother with collecting results
+        async def run_and_collect(fn):
-        # (would result in a different debugger outcome due to parent's
+            '''
-        # cancellation).
+            One-shot whose (boxed) error is stashed instead of
-        await n.run_in_actor(breakpoint_forever)
+            raised so a sibling's crash never cancels the others
-        await n.run_in_actor(name_error)
+            before they've had their own debugger sessions (the
-        await n.run_in_actor(spawn_error)
+            "collect all errors" the legacy `run_in_actor()` API
+            did implicitly at nursery teardown).
+
+            '''
+            try:
+                await tractor.to_actor.run(fn, an=an)
+            except tractor.RemoteActorError as rae:
+                errors.append(rae)
+
+        # Spawn all one-shot task actors, collecting (vs.
+        # raising) their errors.
+        async with trio.open_nursery() as tn:
+            tn.start_soon(run_and_collect, breakpoint_forever)
+            tn.start_soon(run_and_collect, name_error)
+            tn.start_soon(run_and_collect, spawn_error)
+
+        if errors:
+            raise BaseExceptionGroup(
+                'multi_subactors errored!',
+                errors,
+            )
 
 
 if __name__ == '__main__':

examples/debugging/root_cancelled_but_child_is_in_tty_lock.py

@@ -1,3 +1,5 @@
+from functools import partial
+
 import trio
 import tractor
 
@@ -10,14 +12,14 @@ async def name_error():
 async def spawn_until(depth=0):
     """"A nested nursery that triggers another ``NameError``.
     """
-    async with tractor.open_nursery() as n:
+    async with tractor.open_nursery() as an:
         if depth < 1:
-            # await n.run_in_actor('breakpoint_forever', breakpoint_forever)
+            await tractor.to_actor.run(name_error, an=an)
-            await n.run_in_actor(name_error)
         else:
             depth -= 1
-            await n.run_in_actor(
+            await tractor.to_actor.run(
                 spawn_until,
+                an=an,
                 depth=depth,
                 name=f'spawn_until_{depth}',
             )
@@ -37,28 +39,33 @@ async def main():
        └─ python -m tractor._child --uid ('name_error', '6c2733b8 ...)
 
     '''
-    async with tractor.open_nursery(
+    async with (
-        debug_mode=True,
+        tractor.open_nursery(
-        enable_transports=['uds'],  # TODO, apss this via osenv?
+            debug_mode=True,
-        loglevel='devx',  # XXX, required for test!
+            enable_transports=['uds'],  # TODO, apss this via osenv?
-    ) as n:
+            loglevel='devx',  # XXX, required for test!
+        ) as an,
+        trio.open_nursery() as tn,
+    ):
+        # spawn the deeper tree in the bg..
+        tn.start_soon(
+            partial(
+                tractor.to_actor.run,
+                spawn_until,
+                an=an,
+                depth=1,
+                name='spawner1',
+            )
+        )
 
-        # spawn both actors
+        # ..while blocking on the shallow (faster to fail) tree
-        portal = await n.run_in_actor(
+        # whose propagated error triggers nursery cancellation.
+        await tractor.to_actor.run(
             spawn_until,
+            an=an,
             depth=0,
             name='spawner0',
         )
-        portal1 = await n.run_in_actor(
-            spawn_until,
-            depth=1,
-            name='spawner1',
-        )
-
-        # nursery cancellation should be triggered due to propagated
-        # error from child.
-        await portal.result()
-        await portal1.result()
 
 
 if __name__ == '__main__':

examples/debugging/root_timeout_while_child_crashed.py

@@ -13,17 +13,24 @@ async def main():
     simultaneously.
 
     '''
-    async with tractor.open_nursery(
+    async with (
-        debug_mode=True,
+        tractor.open_nursery(
-        # loglevel='debug'  # ?XXX required?
+            debug_mode=True,
-    ) as n:
+            # loglevel='debug'  # ?XXX required?
-
+        ) as n,
-        # spawn both actors
+        trio.open_nursery() as tn,
-        portal = await n.run_in_actor(key_error)
+    ):
+        # spawn the actor..
+        portal = await n.start_actor(
+            'key_error',
+            enable_modules=[__name__],
+        )
         print(
             f'Child is up @ {portal.chan.aid.reprol()}'
         )
-
+        # ..then schedule its erroring task in the bg while the
+        # root blocks below.
+        tn.start_soon(portal.run, key_error)
 
         # XXX: originally a bug caused by this is where root would enter
         # the debugger and clobber the tty used by the repl even though

examples/debugging/shielded_pause.py

@@ -75,10 +75,10 @@ async def main():
     async with tractor.open_nursery(
         debug_mode=True,
     ) as n:
-        portal: tractor.Portal = await n.run_in_actor(
+        await tractor.to_actor.run(
             cancelled_before_pause,
+            an=n,
         )
-        await portal.wait_for_result()
 
         # ensure the same works in the root actor!
         await pm_on_cancelled()

examples/debugging/subactor_breakpoint.py

@@ -19,10 +19,12 @@ async def main():
         loglevel='cancel',
     ) as n:
 
-        portal = await n.run_in_actor(
+        # parks awaiting a result which only arrives once the
+        # user quits (`BdbQuit`s) the child's REPL loop.
+        await tractor.to_actor.run(
             breakpoint_forever,
+            an=n,
         )
-        await portal.wait_for_result()
 
 
 if __name__ == '__main__':

examples/debugging/subactor_error.py

@@ -12,16 +12,12 @@ async def main():
     ) as an:
 
         # TODO: ideally the REPL arrives at this frame in the parent,
-        # ABOVE the @api_frame of `Portal.run_in_actor()` (which
+        # ABOVE the @api_frame of `to_actor.run()` ..
-        # should eventually not even be a portal method ... XD)
         # await tractor.pause()
-        p: tractor.Portal = await an.run_in_actor(name_error)
 
-        # with this style, should raise on this line
+        # the one-shot blocks on the subactor's result so the
-        await p.wait_for_result()
+        # boxed `NameError` raises right here.
-
+        await tractor.to_actor.run(name_error, an=an)
-        # with this alt style should raise at `open_nusery()`
-        # return await p.wait_for_result()
 
 
 if __name__ == '__main__':

examples/debugging/sync_bp.py

@@ -90,7 +90,7 @@ async def main() -> None:
 
         # TODO: 3 sub-actor usage cases:
         # -[x] via a `.open_context()`
-        # -[ ] via a `.run_in_actor()` call
+        # -[ ] via a `to_actor.run()` call
         # -[ ] via a `.run()`
         # -[ ] via a `.to_thread.run_sync()` in subactor
         async with p.open_context(

examples/parallelism/single_func.py

@@ -25,17 +25,15 @@ async def burn_cpu():
 
 async def main():
 
-    async with tractor.open_nursery() as n:
+    async with trio.open_nursery() as tn:
 
-        portal = await n.run_in_actor(burn_cpu)
+        # burn rubber in the parent too
+        tn.start_soon(burn_cpu)
 
-        #  burn rubber in the parent too
+        # run the same func as the lone task in a subactor,
-        await burn_cpu()
+        # block on (and collect) its result
+        pid = await tractor.to_actor.run(burn_cpu)
 
-        # wait on result from target function
-        pid = await portal.wait_for_result()
-
-    # end of nursery block
     print(f"Collected subproc {pid}")
 
 

examples/remote_error_propagation.py

@@ -15,11 +15,12 @@ async def main():
                 enable_modules=[__name__],
             ))
 
-        # start one actor that will fail immediately
+        # run one one-shot task actor that will fail immediately;
-        await n.run_in_actor(assert_err)
+        # its error raises right here in the caller's task..
+        await tractor.to_actor.run(assert_err, an=n)
 
-    # should error here with a ``RemoteActorError`` containing
+    # ..as a ``RemoteActorError`` containing an ``AssertionError``
-    # an ``AssertionError`` and all the other actors have been cancelled
+    # and all the other actors have been cancelled
 
 
 if __name__ == '__main__':

tests/devx/test_debugger.py

@@ -849,43 +849,36 @@ def test_multi_nested_subactors_error_through_nurseries(
             break
 
     # boxed source errors
+    #
+    # NB post-#477 (`to_actor.run()` one-shots in local
+    # task-nurseries) the final relay is the LAST-released
+    # (leaf) REPL's error chain: it wins each level's
+    # relay-vs-cancel race so every level's single-member
+    # group gets unwrapped by the runtime's `collapse_eg()`
+    # (annotated at each actor boundary) while the sibling
+    # tree ('spawner1') is cancelled + absorbed. The legacy
+    # `run_in_actor()` teardown-reap instead grouped BOTH the
+    # `name_error` and bp-quit chains into the final dump
+    # (the previously-unexplained "extra" patterns).
     expect_patts: list[str] = [
-        "NameError: name 'doggypants' is not defined",
         "tractor._exceptions.RemoteActorError:",
-        "('name_error'",
 
-        # first level subtrees
+        # each level's unwrapped-single-member-group
-        # "tractor._exceptions.RemoteActorError: ('spawner0'",
+        # annotation + the first-level subtree's boundary
-        "src_uid=('spawner0'",
+        # footer.
-
+        "( ^^^ this exc was collapsed from a group ^^^ )",
-        # "tractor._exceptions.RemoteActorError: ('spawner1'",
+        "------ ('spawner0'",
-
-        # propagation of errors up through nested subtrees
-        # "tractor._exceptions.RemoteActorError: ('spawn_until_0'",
-        # "tractor._exceptions.RemoteActorError: ('spawn_until_1'",
-        # "tractor._exceptions.RemoteActorError: ('spawn_until_2'",
-        # ^-NOTE-^ old RAE repr, new one is below with a field
-        # showing the src actor's uid.
-        "src_uid=('spawn_until_2'",
     ]
-    # XXX, I HAVE NO IDEA why these patts only show on the
-    # `trio`-spawner but it seems to have something to do with
-    # what gets dumped in prior-prompt latches somehow??
-    # TODO for claude, explain and or work through how this is
-    # happening but ONLY WHEN RUN FROM THE TEST, bc when i try to
-    # run the test script manually the correct output ALWAYS seems
-    # to be in the last `str(child.before.decode())` output !?!?
     if (
         not is_forking_spawner
         and
         last_send_char == 'q'
     ):
         expect_patts += [
-            # expect the pdb-quit exc.
+            # expect the pdb-quit exc relayed from the leaf's
+            # bp-loop child.
             "bdb.BdbQuit",
-            # BUT WHY these dude!?
+            "src_uid=('breakpoint_forever'",
-            "src_uid=('spawn_until_0'",
-            "relay_uid=('spawn_until_1'",
         ]
 
     assert_before(

tests/test_advanced_streaming.py

@@ -3,6 +3,7 @@ Advanced streaming patterns using bidirectional streams and contexts.
 
 '''
 from collections import Counter
+from functools import partial
 import itertools
 import platform
 from typing import Type
@@ -173,8 +174,8 @@ def test_dynamic_pub_sub(
     # test. Picked backend-aware: under `trio` backend spawn is
     # cheap (~1s for `cpus` actors) but fork-based backends pay
     # a per-spawn cost (forkserver round-trip + IPC peer-handshake)
-    # that can stack up over `cpus - 1` sequential `n.run_in_actor()`
+    # that can stack up over the `cpus - 1` one-shot
-    # calls — especially on UDS under cross-pytest contention
+    # (`to_actor.run()`) spawns — especially on UDS under cross-pytest contention
     # (#451 / #452). 4s was flaking right at the edge under fork
     # backends — bumped to 8s with diag-snapshot-on-timeout via
     # `fail_after_w_trace` so a borderline run still fails loud
@@ -214,33 +215,55 @@ def test_dynamic_pub_sub(
                     f'enter `fail_after_w_trace({fail_after_s})` scope'
                 )
                 try:
-                    async with tractor.open_nursery(
+                    async with (
-                        registry_addrs=[reg_addr],
+                        tractor.open_nursery(
-                        debug_mode=debug_mode,
+                            registry_addrs=[reg_addr],
-                    ) as n:
+                            debug_mode=debug_mode,
+                        ) as n,
+                        # bg-schedules the forever-streaming
+                        # one-shots below; the user-cancel raise
+                        # cancels them all, each reaping its
+                        # subactor via `to_actor.run()`'s
+                        # (shielded) `Portal.cancel_actor()`.
+                        trio.open_nursery() as tn,
+                    ):
                         test_log.cancel(
                             'test_dynamic_pub_sub: '
                             'actor nursery opened'
                         )
 
                         # name of this actor will be same as target func
-                        await n.run_in_actor(publisher)
+                        tn.start_soon(
+                            partial(
+                                tractor.to_actor.run,
+                                publisher,
+                                an=n,
+                            )
+                        )
 
                         for i, sub in zip(
                             range(cpus - 2),
                             itertools.cycle(_registry.keys())
                         ):
-                            await n.run_in_actor(
+                            tn.start_soon(
-                                consumer,
+                                partial(
-                                name=f'consumer_{sub}',
+                                    tractor.to_actor.run,
-                                subs=[sub],
+                                    consumer,
+                                    an=n,
+                                    name=f'consumer_{sub}',
+                                    subs=[sub],
+                                )
                             )
 
                         # make one dynamic subscriber
-                        await n.run_in_actor(
+                        tn.start_soon(
-                            consumer,
+                            partial(
-                            name='consumer_dynamic',
+                                tractor.to_actor.run,
-                            subs=list(_registry.keys()),
+                                consumer,
+                                an=n,
+                                name='consumer_dynamic',
+                                subs=list(_registry.keys()),
+                            )
                         )
 
                         # block until "cancelled by user"

tests/test_cancellation.py

@@ -2,6 +2,7 @@
 Cancellation and error propagation
 
 """
+from functools import partial
 import os
 import signal
 import platform
@@ -16,7 +17,10 @@ from tractor._testing import (
     tractor_test,
 )
 from tractor._testing.trace import FailAfterWTraceFactory
-from tractor.trionics import gather_contexts
+from tractor.trionics import (
+    collapse_eg,
+    gather_contexts,
+)
 from .conftest import no_windows
 
 
@@ -305,30 +309,30 @@ async def test_cancel_infinite_streamer(
 @pytest.mark.parametrize(
     'num_actors_and_errs',
     [
-        # daemon actors sit idle while single task actors error out
+        # daemon actors sit idle while one-shot task actors error out
         (1, tractor.RemoteActorError, AssertionError, (assert_err, {}), None),
         (2, BaseExceptionGroup, AssertionError, (assert_err, {}), None),
         (3, BaseExceptionGroup, AssertionError, (assert_err, {}), None),
 
-        # 1 daemon actor errors out while single task actors sleep forever
+        # 1 daemon actor errors out while one-shot task actors sleep forever
         (3, tractor.RemoteActorError, AssertionError, (sleep_forever, {}),
          (assert_err, {}, True)),
-        # daemon actors error out after brief delay while single task
+        # daemon actors error out after brief delay while one-shot task
         # actors complete quickly
         (3, tractor.RemoteActorError, AssertionError,
          (do_nuthin, {}), (assert_err, {'delay': 1}, True)),
-        # daemon complete quickly delay while single task
+        # daemon complete quickly delay while one-shot task
         # actors error after brief delay
         (3, BaseExceptionGroup, AssertionError,
          (assert_err, {'delay': 1}), (do_nuthin, {}, False)),
     ],
     ids=[
-        '1_run_in_actor_fails',
+        '1_one_shot_fails',
-        '2_run_in_actors_fail',
+        '2_one_shots_fail',
-        '3_run_in_actors_fail',
+        '3_one_shots_fail',
         '1_daemon_actors_fail',
-        '1_daemon_actors_fail_all_run_in_actors_dun_quick',
+        '1_daemon_actors_fail_all_one_shots_dun_quick',
-        'no_daemon_actors_fail_all_run_in_actors_sleep_then_fail',
+        'no_daemon_actors_fail_all_one_shots_sleep_then_fail',
     ],
 )
 @tractor_test(
@@ -347,12 +351,22 @@ async def test_some_cancels_all(
 
     This is the first and only supervisory strategy at the moment.
 
+    One-shot subactors run as concurrent `to_actor.run()` tasks
+    in a local task-nursery so their errors raise WHILE the
+    actor-nursery block is still open (vs the legacy
+    `run_in_actor()` teardown-reap); the first error cancels the
+    sibling one-shots (whose `trio.Cancelled`s the task-nursery
+    absorbs) so the group shape is 1..num_actors
+    `RemoteActorError`s depending on relay-vs-cancel timing —
+    with `collapse_eg()` unwrapping the deterministic
+    single-error cases to a bare `RemoteActorError`.
+
     '''
     (
         num_actors,
         first_err,
         err_type,
-        ria_func,
+        one_shot_func,
         da_func,
     ) = num_actors_and_errs
     try:
@@ -366,51 +380,64 @@ async def test_some_cancels_all(
                     enable_modules=[__name__],
                 ))
 
-            func, kwargs = ria_func
+            func, kwargs = one_shot_func
-            riactor_portals = []
+            async with (
-            for i in range(num_actors):
+                collapse_eg(),
-                # start actor(s) that will fail immediately
+                trio.open_nursery() as tn,
-                riactor_portals.append(
+            ):
-                    await an.run_in_actor(
+                for i in range(num_actors):
-                        func,
+                    # schedule one-shot task actor(s); errors
-                        name=f'actor_{i}',
+                    # raise into this task-nursery scope.
-                        **kwargs
+                    tn.start_soon(
+                        partial(
+                            tractor.to_actor.run,
+                            func,
+                            an=an,
+                            name=f'actor_{i}',
+                            **kwargs,
+                        )
                     )
-                )
 
-            if da_func:
+                if da_func:
-                func, kwargs, expect_error = da_func
+                    func, kwargs, expect_error = da_func
-                for portal in dactor_portals:
+                    for portal in dactor_portals:
-                    # if this function fails then we should error here
+                        # if this function fails then we should error
-                    # and the nursery should teardown all other actors
+                        # here and the nursery should teardown all
-                    try:
+                        # other actors
-                        await portal.run(func, **kwargs)
+                        try:
+                            await portal.run(func, **kwargs)
 
-                    except tractor.RemoteActorError as err:
+                        except tractor.RemoteActorError as err:
-                        assert err.boxed_type == err_type
+                            assert err.boxed_type == err_type
-                        # we only expect this first error to propogate
+                            # we only expect this first error to propogate
-                        # (all other daemons are cancelled before they
+                            # (all other daemons are cancelled before they
-                        # can be scheduled)
+                            # can be scheduled)
-                        num_actors = 1
+                            num_actors = 1
-                        # reraise so nursery teardown is triggered
+                            # reraise so nursery teardown is triggered
-                        raise
+                            raise
-                    else:
+                        else:
-                        if expect_error:
+                            if expect_error:
-                            pytest.fail(
+                                pytest.fail(
-                                "Deamon call should fail at checkpoint?")
+                                    "Deamon call should fail at checkpoint?")
 
-        # should error here with a ``RemoteActorError`` or ``MultiError``
+        # should error here with a `RemoteActorError` or a beg of them
 
-    except first_err as _err:
+    except (
+        BaseExceptionGroup,
+        tractor.RemoteActorError,
+    ) as _err:
         err = _err
         if isinstance(err, BaseExceptionGroup):
-            assert len(err.exceptions) == num_actors
+            # only the concurrent multi-error cases can group; the
+            # relay-vs-cancel race means anywhere from 1 (all
+            # siblings cancelled before relaying) up to all
+            # `num_actors` errors may populate the group.
+            assert first_err is BaseExceptionGroup
+            assert 1 <= len(err.exceptions) <= num_actors
             for exc in err.exceptions:
-                if isinstance(exc, tractor.RemoteActorError):
+                assert isinstance(exc, tractor.RemoteActorError)
-                    assert exc.boxed_type == err_type
+                assert exc.boxed_type == err_type
-                else:
+        else:
-                    assert isinstance(exc, trio.Cancelled)
-        elif isinstance(err, tractor.RemoteActorError):
             assert err.boxed_type == err_type
 
         assert an.cancel_called is True
@@ -423,8 +450,20 @@ async def spawn_and_error(
     breadth: int,
     depth: int,
 ) -> None:
+    '''
+    Recursively spawn a breadth-wide level of erroring one-shot
+    subactors as concurrent `to_actor.run()` tasks; the leaf level
+    errors ~simultaneously and each level's task-nursery groups
+    whatever `RemoteActorError`s relay before the first one's
+    cancel wins, boxing the (`ExceptionGroup`-shaped) group into
+    this actor's own relayed error.
+
+    '''
     name = tractor.current_actor().name
-    async with tractor.open_nursery() as nursery:
+    async with (
+        tractor.open_nursery() as an,
+        trio.open_nursery() as tn,
+    ):
         for i in range(breadth):
 
             if depth > 0:
@@ -444,7 +483,14 @@ async def spawn_and_error(
                 kwargs = {
                     'name': f'{name}_errorer_{i}',
                 }
-            await nursery.run_in_actor(*args, **kwargs)
+            tn.start_soon(
+                partial(
+                    tractor.to_actor.run,
+                    *args,
+                    an=an,
+                    **kwargs,
+                )
+            )
 
 
 # NOTE: `main_thread_forkserver` capture-fd hang class is no
@@ -486,7 +532,11 @@ async def test_nested_multierrors(
     depth: int,
 ):
     '''
-    Test that failed actor sets are wrapped in `BaseExceptionGroup`s.
+    Test that a nested tree of concurrently failing one-shot
+    subactors tears down cleanly, relaying (whatever subset of)
+    the leaf `AssertionError`s (that win the per-level
+    relay-vs-cancel race) re-boxed/grouped at each actor
+    boundary.
 
     Parametrized over recursion `depth ∈ {1, 3}`:
 
@@ -536,6 +586,13 @@ async def test_nested_multierrors(
     # fork-spawn jitter + UDS-contention widens both `t1` and
     # `t2` further.
     #
+    # NB post-#477 (`to_actor.run()` fan-out in a local
+    # task-nursery) a race-tripped sibling's `Cancelled` is
+    # ABSORBED by the task-nursery instead of landing in the
+    # group — the raced case now shows as a *smaller* BEG, so
+    # this marker should consistently `xpass`; drop it once CI
+    # confirms.
+    #
     # With `strict=False` the clean-cascade cases (most
     # depth=1 runs, rare depth=3 runs) report as `xpassed`
     # while the race-tripped cases report as `xfailed` —
@@ -620,6 +677,14 @@ async def test_nested_multierrors(
             timeout = 16
         case ('main_thread_forkserver', 3):
             timeout = 30
+        # any other fork-based backend (`mp_spawn` et al) pays
+        # the same per-spawn round-trip costs as MTF so rides
+        # its budgets; without a default arm `timeout` is left
+        # unbound -> `UnboundLocalError` at the scaling below.
+        case (_, 1):
+            timeout = 16
+        case (_, 3):
+            timeout = 30
 
     # inflate the budget by the throttle headroom probed above so
     # a slow box doesn't masquerade as a deadline regression.
@@ -632,67 +697,82 @@ async def test_nested_multierrors(
 
     async with fail_after_w_trace(timeout):
         try:
-            async with tractor.open_nursery() as nursery:
+            async with (
+                tractor.open_nursery() as nursery,
+                trio.open_nursery() as tn,
+            ):
                 for i in range(subactor_breadth):
-                    await nursery.run_in_actor(
+                    tn.start_soon(
-                        spawn_and_error,
+                        partial(
-                        name=f'spawner_{i}',
+                            tractor.to_actor.run,
-                        breadth=subactor_breadth,
+                            spawn_and_error,
-                        depth=depth,
+                            an=nursery,
+                            name=f'spawner_{i}',
+                            breadth=subactor_breadth,
+                            depth=depth,
+                        )
                     )
-        except BaseExceptionGroup as err:
+        except (
-            assert len(err.exceptions) == subactor_breadth
+            BaseExceptionGroup,
-            for subexc in err.exceptions:
+            tractor.RemoteActorError,
-
+        ) as err:
-                # verify first level actor errors are wrapped as remote
+            # group membership is bounded by the relay-vs-cancel
-                if _friggin_windows:
+            # race: the first spawner-tree's error cancels its
-
+            # siblings, whose own errors only group when relayed
+            # first; a fully-raced tree even collapses (via the
+            # runtime's own `collapse_eg()` unwrapping each level's
+            # single-member group) to a bare `RemoteActorError`
+            # re-boxing the leaf `AssertionError` at every actor
+            # boundary. The deterministic exact-breadth nested-BEG
+            # was the legacy `run_in_actor()` reap-all-at-teardown.
+            subexcs: list[BaseException] = (
+                err.exceptions
+                if isinstance(err, BaseExceptionGroup)
+                else [err]
+            )
+            assert 1 <= len(subexcs) <= subactor_breadth
+            for subexc in subexcs:
+                if (
+                    _friggin_windows
+                    and
+                    isinstance(subexc, trio.Cancelled)
+                ):
                     # windows is often too slow and cancellation seems
                     # to happen before an actor is spawned
-                    if isinstance(subexc, trio.Cancelled):
+                    continue
-                        continue
 
-                    elif isinstance(subexc, tractor.RemoteActorError):
+                assert isinstance(subexc, tractor.RemoteActorError)
-                        # on windows it seems we can't exactly be sure wtf
-                        # will happen..
-                        assert subexc.boxed_type in (
-                            tractor.RemoteActorError,
-                            trio.Cancelled,
-                            BaseExceptionGroup,
-                        )
 
-                    elif isinstance(subexc, BaseExceptionGroup):
+                accepted: tuple[Type[BaseException], ...] = (
-                        for subsub in subexc.exceptions:
+                    # ≥2 sub-tree errors relayed before the
-
+                    # cancel-cascade won → grouped per-level.
-                            if subsub in (tractor.RemoteActorError,):
+                    ExceptionGroup,
-                                subsub = subsub.boxed_type
+                    # every level collapsed down to its lone
-
+                    # relayed (leaf) error.
-                            assert type(subsub) in (
+                    AssertionError,
-                                trio.Cancelled,
+                    # a mid-level spawner relays an
-                                BaseExceptionGroup,
+                    # already-boxed (collapsed) leaf chain,
-                            )
+                    # re-boxing the `RemoteActorError` itself.
-                else:
+                    tractor.RemoteActorError,
-                    assert isinstance(subexc, tractor.RemoteActorError)
+                    # under heavy load a runtime-internal reap
-
+                    # deadline can inject a `trio.Cancelled`
-                if depth > 0 and subactor_breadth > 1:
+                    # into a child's group before relay (the
-                    # XXX not sure what's up with this..
+                    # same class the depth=3 throttle-xfail
-                    # on windows sometimes spawning is just too slow and
+                    # covers) upgrading it from an
-                    # we get back the (sent) cancel signal instead
+                    # `ExceptionGroup`.
-                    if _friggin_windows:
+                    BaseExceptionGroup,
-                        if isinstance(subexc, tractor.RemoteActorError):
+                )
-                            assert subexc.boxed_type in (
+                if _friggin_windows:
-                                BaseExceptionGroup,
+                    # on windows it seems we can't exactly be
-                                tractor.RemoteActorError
+                    # sure wtf will happen..
-                            )
+                    accepted += (
-                        else:
+                        trio.Cancelled,
-                            assert isinstance(subexc, BaseExceptionGroup)
-                    else:
-                        assert subexc.boxed_type is ExceptionGroup
-                else:
-                    assert subexc.boxed_type in (
-                        tractor.RemoteActorError,
-                        trio.Cancelled
                     )
+                assert subexc.boxed_type in accepted
+        else:
+            pytest.fail(
+                'Should have raised a (grouped) `RemoteActorError`?'
+            )
 
 
 @no_windows
@@ -757,11 +837,13 @@ def test_cancel_via_SIGINT_other_task(
     ):
         async with tractor.open_nursery(
             registry_addrs=[reg_addr],
-        ) as tn:
+        ) as an:
+            # just keep a set of (daemon) subactors alive for the
+            # SIGINT to cancel (was 3 `run_in_actor(sleep_forever)`
+            # one-shots — a daemon needs no "main" task to idle).
             for i in range(3):
-                await tn.run_in_actor(
+                await an.start_actor(
-                    sleep_forever,
+                    f'namesucka_{i}',
-                    name='namesucka',
                 )
             task_status.started()
             await trio.sleep_forever()
@@ -802,8 +884,11 @@ async def spin_for(period=3):
 async def spawn_sub_with_sync_blocking_task():
     async with tractor.open_nursery() as an:
         print('starting sync blocking subactor..\n')
-        await an.run_in_actor(
+        # one-shot: parks HERE awaiting the sync-sleeping
+        # grandchild's result until cancelled from above.
+        await tractor.to_actor.run(
             spin_for,
+            an=an,
             name='sleeper',
         )
         print('exiting first subactor layer..\n')
@@ -909,10 +994,18 @@ def test_cancel_while_childs_child_in_sync_sleep(
                     debug_mode=debug_mode,
                     registry_addrs=[reg_addr],
                 ) as an,
+                trio.open_nursery() as tn,
             ):
-                await an.run_in_actor(
+                # bg one-shot: parks on the middle actor's result
-                    spawn_sub_with_sync_blocking_task,
+                # (itself parked on the sync-sleeping grandchild)
-                    name='sync_blocking_sub',
+                # until the `assert 0` below cancels this scope.
+                tn.start_soon(
+                    partial(
+                        tractor.to_actor.run,
+                        spawn_sub_with_sync_blocking_task,
+                        an=an,
+                        name='sync_blocking_sub',
+                    )
                 )
                 await trio.sleep(1)
 

tests/test_ringbuf.py

@@ -131,9 +131,12 @@ def test_ringbuf(
                         child_read_shm,
                         **common_kwargs,
                         total_bytes=total_bytes,
-                    ) as (sctx, _sent),
+                    ) as (rctx, _sent),
                 ):
-                    await recv_p.result()
+                    # ctx-acm exits await each child task's
+                    # `Return` (the prior `recv_p.result()` here
+                    # was a daemon-portal no-op).
+                    pass
 
                 await send_p.cancel_actor()
                 await recv_p.cancel_actor()

tests/test_to_actor.py

@@ -1,8 +1,8 @@
 '''
 `tractor.to_actor`: one-shot single-remote-task API suite.
 
-Verifies the "spiritual successor" to (and eventual
+Verifies the "spiritual successor" to (and replacement of)
-replacement of) `ActorNursery.run_in_actor()`; see
+the removed legacy `ActorNursery.run_in_actor()`; see
 https://github.com/goodboy/tractor/issues/477
 
 '''
@@ -82,7 +82,7 @@ async def test_remote_error_relayed_to_caller_task(
     A remote task error is raised directly in the
     caller's task as a boxed `RemoteActorError` instead
     of surfacing at actor-nursery teardown as with the
-    legacy `.run_in_actor()` API.
+    removed legacy `.run_in_actor()` API.
 
     '''
     with pytest.raises(RemoteActorError) as excinfo:

tractor/_context.py

@@ -780,7 +780,7 @@ class Context:
         # `Portal.open_context()` has been opened since it's
         # assumed that other portal APIs like,
         #  - `Portal.run()`,
-        #  - `ActorNursery.run_in_actor()`
+        #  - `to_actor.run()`
         # do their own error checking at their own call points and
         # result processing.
 

tractor/_exceptions.py

@@ -1161,10 +1161,6 @@ class TransportClosed(Exception):
         )
 
 
-class NoResult(RuntimeError):
-    "No final result is expected for this actor"
-
-
 class ModuleNotExposed(ModuleNotFoundError):
     "The requested module is not exposed for RPC"
 

tractor/experimental/_pubsub.py

@@ -221,16 +221,19 @@ def pub(
         import tractor
 
         async with tractor.open_nursery() as n:
-            portal = n.run_in_actor(
+            portal = await n.start_actor(
                 'publisher',  # actor name
-                partial(      # func to execute in it
+                enable_modules=[__name__],
+            )
+            async with portal.open_stream_from(
+                partial(  # func to execute in it
                     pub_service,
                     topics=('clicks', 'users'),
                     task_name='source1',
                 )
-            )
+            ) as stream:
-            async for value in await portal.result():
+                async for value in stream:
-                print(f"Subscriber received {value}")
+                    print(f"Subscriber received {value}")
 
 
     Here, you don't need to provide the ``ctx`` argument since the

tractor/msg/types.py

@@ -304,12 +304,11 @@ class Start(
 
     It is called by all the following public APIs:
 
-    - `ActorNursery.run_in_actor()`
+    - `to_actor.run()`
 
     - `Portal.run()`
           `|_.run_from_ns()`
           `|_.open_stream_from()`
-          `|_._submit_for_result()`
 
     - `Context.open_context()`
 

tractor/runtime/_portal.py

@@ -50,13 +50,11 @@ from ..ipc import Channel
 from ..log import get_logger
 from ..msg import (
     # Error,
-    PayloadMsg,
     NamespacePath,
     Return,
 )
 from .._exceptions import (
     ActorTooSlowError,
-    NoResult,
     TransportClosed,
 )
 from .._context import (
@@ -102,14 +100,6 @@ class Portal:
     ) -> None:
 
         self._chan: Channel = channel
-        # during the portal's lifetime
-        self._final_result_pld: Any|None = None
-        self._final_result_msg: PayloadMsg|None = None
-
-        # When set to a ``Context`` (when _submit_for_result is called)
-        # it is expected that ``result()`` will be awaited at some
-        # point.
-        self._expect_result_ctx: Context|None = None
         self._streams: set[MsgStream] = set()
 
         # TODO, this should be PRIVATE (and never used publicly)! since it's just
@@ -137,102 +127,6 @@ class Portal:
         )
         return self.chan
 
-    # TODO: factor this out into a `.highlevel` API-wrapper that uses
-    # a single `.open_context()` call underneath.
-    async def _submit_for_result(
-        self,
-        ns: str,
-        func: str,
-        **kwargs
-    ) -> None:
-
-        if self._expect_result_ctx is not None:
-            raise RuntimeError(
-                'A pending main result has already been submitted'
-            )
-
-        self._expect_result_ctx: Context = await self.actor.start_remote_task(
-            self.channel,
-            nsf=NamespacePath(f'{ns}:{func}'),
-            kwargs=kwargs,
-            portal=self,
-        )
-
-    # TODO: we should deprecate this API right? since if we remove
-    # `.run_in_actor()` (and instead move it to a `.highlevel`
-    # wrapper api (around a single `.open_context()` call) we don't
-    # really have any notion of a "main" remote task any more?
-    #
-    # @api_frame
-    async def wait_for_result(
-        self,
-        hide_tb: bool = True,
-    ) -> Any:
-        '''
-        Return the final result delivered by a `Return`-msg from the
-        remote peer actor's "main" task's `return` statement.
-
-        '''
-        __tracebackhide__: bool = hide_tb
-        # Check for non-rpc errors slapped on the
-        # channel for which we always raise
-        exc = self.channel._exc
-        if exc:
-            raise exc
-
-        # not expecting a "main" result
-        if self._expect_result_ctx is None:
-            peer_id: str = f'{self.channel.aid.reprol()!r}'
-            log.warning(
-                f'Portal to peer {peer_id} will not deliver a final result?\n'
-                f'\n'
-                f'Context.result() can only be called by the parent of '
-                f'a sub-actor when it was spawned with '
-                f'`ActorNursery.run_in_actor()`'
-                f'\n'
-                f'Further this `ActorNursery`-method-API will deprecated in the'
-                f'near fututre!\n'
-            )
-            return NoResult
-
-        # expecting a "main" result
-        assert self._expect_result_ctx
-
-        if self._final_result_msg is None:
-            try:
-                (
-                    self._final_result_msg,
-                    self._final_result_pld,
-                ) = await self._expect_result_ctx._pld_rx.recv_msg(
-                    ipc=self._expect_result_ctx,
-                    expect_msg=Return,
-                )
-            except BaseException as err:
-                # TODO: wrap this into `@api_frame` optionally with
-                # some kinda filtering mechanism like log levels?
-                __tracebackhide__: bool = False
-                raise err
-
-        return self._final_result_pld
-
-    # TODO: factor this out into a `.highlevel` API-wrapper that uses
-    # a single `.open_context()` call underneath.
-    async def result(
-        self,
-        *args,
-        **kwargs,
-    ) -> Any|Exception:
-        typname: str = type(self).__name__
-        log.warning(
-            f'`{typname}.result()` is DEPRECATED!\n'
-            f'\n'
-            f'Use `{typname}.wait_for_result()` instead!\n'
-        )
-        return await self.wait_for_result(
-            *args,
-            **kwargs,
-        )
-
     async def _cancel_streams(self):
         # terminate all locally running async generator
         # IPC calls

tractor/runtime/_supervise.py

@@ -20,7 +20,6 @@
 """
 from contextlib import asynccontextmanager as acm
 from functools import partial
-import inspect
 from typing import (
     TYPE_CHECKING,
 )
@@ -232,14 +231,6 @@ class ActorNursery:
         # and syncing purposes to any actor opened nurseries.
         self._implicit_runtime_started: bool = False
 
-        # TODO, factor this into a .hilevel api!
-        #
-        # portals spawned with ``run_in_actor()`` are
-        # cancelled when their "main" result arrives. Reaped by
-        # `_reap_ria_portals()` at nursery-block exit now that
-        # the 2ndary `._ria_nursery` is gone (see issue #477).
-        self._cancel_after_result_on_exit: set = set()
-
         # trio.Nursery-like cancel (request) statuses
         self._cancelled_caught: bool = False
         self._cancel_called: bool = False
@@ -372,84 +363,6 @@ class ActorNursery:
             )
         )
 
-    # TODO: DEPRECATE THIS:
-    # -[x] impl instead as a hilevel wrapper on top of
-    #   the lower level daemon-spawn + portal APIs
-    #  |_ see `.to_actor.run()` (issue #477) which does
-    #    `.start_actor()` + `Portal.run()` + a one-shot
-    #    reap via `Portal.cancel_actor()`.
-    # -[ ] emit a `DeprecationWarning` here (requires
-    #   migrating all in-repo usage first!)
-    # -[ ] use @api_frame on the wrapper
-    async def run_in_actor(
-        self,
-
-        fn: typing.Callable,
-        *,
-
-        name: str | None = None,
-        bind_addrs: UnwrappedAddress|None = None,
-        rpc_module_paths: list[str] | None = None,
-        enable_modules: list[str] | None = None,
-        loglevel: str | None = None,  # set log level per subactor
-        infect_asyncio: bool = False,
-        inherit_parent_main: bool = True,
-        proc_kwargs: dict[str, typing.Any] | None = None,
-
-        **kwargs,  # explicit args to ``fn``
-
-    ) -> Portal:
-        '''
-        Spawn a new actor, run a lone task, then terminate the actor and
-        return its result.
-
-        Actors spawned using this method are kept alive at nursery teardown
-        until the task spawned by executing ``fn`` completes at which point
-        the actor is terminated.
-
-        NOTE: prefer the (eventual) replacement API
-        `tractor.to_actor.run()` which delivers the same
-        one-shot semantics decoupled from this nursery's
-        internal spawn machinery; see issue #477.
-
-        '''
-        __runtimeframe__: int = 1  # noqa
-        mod_path: str = fn.__module__
-
-        if name is None:
-            # use the explicit function name if not provided
-            name = fn.__name__
-
-        proc_kwargs = dict(proc_kwargs or {})
-        portal: Portal = await self.start_actor(
-            name,
-            enable_modules=[mod_path] + (
-                enable_modules or rpc_module_paths or []
-            ),
-            bind_addrs=bind_addrs,
-            loglevel=loglevel,
-            infect_asyncio=infect_asyncio,
-            inherit_parent_main=inherit_parent_main,
-            proc_kwargs=proc_kwargs
-        )
-
-        # XXX: don't allow stream funcs
-        if not (
-            inspect.iscoroutinefunction(fn) and
-            not getattr(fn, '_tractor_stream_function', False)
-        ):
-            raise TypeError(f'{fn} must be an async function!')
-
-        # this marks the actor to be cancelled after its portal result
-        # is retreived, see logic in `open_nursery()` below.
-        self._cancel_after_result_on_exit.add(portal)
-        await portal._submit_for_result(
-            mod_path,
-            fn.__name__,
-            **kwargs
-        )
-        return portal
-
     # @api_frame
     async def cancel(
         self,
@@ -568,51 +481,6 @@ class ActorNursery:
         self._join_procs.set()
 
 
-async def _reap_ria_portals(
-    an: ActorNursery,
-    errors: dict[tuple[str, str], BaseException],
-    ria_children: list[tuple[Portal, Actor]]|None = None,
-) -> None:
-    '''
-    Wait on and stash the final result/error from every
-    `.run_in_actor()`-spawned child then cancel its actor
-    runtime, one `_spawn.cancel_on_completion()` task per
-    child.
-
-    Replaces the per-child reaper task formerly spawned by
-    the spawn backends (keyed off
-    `._cancel_after_result_on_exit` membership) which
-    required routing such children into the (now removable)
-    `._ria_nursery`. Only call AFTER `._join_procs` is set
-    so user code inside the nursery block retains exclusive
-    result-await access; see the "manually await results"
-    note in `spawn._mp.mp_proc()`.
-
-    '''
-    if ria_children is None:
-        ria_children: list[tuple[Portal, Actor]] = [
-            (portal, subactor)
-            for subactor, _, portal in an._children.values()
-            if portal in an._cancel_after_result_on_exit
-        ]
-    if not ria_children:
-        return
-
-    async with (
-        collapse_eg(),
-        trio.open_nursery() as tn,
-    ):
-        portal: Portal
-        subactor: Actor
-        for portal, subactor in ria_children:
-            tn.start_soon(
-                _spawn.cancel_on_completion,
-                portal,
-                subactor,
-                errors,
-            )
-
-
 @acm
 async def _open_and_supervise_one_cancels_all_nursery(
     actor: Actor,
@@ -627,11 +495,10 @@ async def _open_and_supervise_one_cancels_all_nursery(
     errors: dict[tuple[str, str], BaseException] = {}
 
     # The single "daemon actor" nursery into which ALL subactors
-    # are spawned — both `.start_actor()` daemons AND
+    # are spawned; one-shot (`to_actor.run()`) subactors are
-    # `.run_in_actor()` one-shots. The latter's result-reaping now
+    # result-waited and reaped in their caller's own task-scope
-    # runs via `_reap_ria_portals()` at block-exit rather than a
+    # (see the #477 `.run_in_actor()`/`._ria_nursery` removal);
-    # 2ndary `._ria_nursery` (see the #477 removal); errors from
+    # errors from this nursery bubble up to the caller.
-    # this nursery bubble up to the caller.
     async with (
         collapse_eg(),
         trio.open_nursery() as da_nursery,
@@ -655,11 +522,6 @@ async def _open_and_supervise_one_cancels_all_nursery(
             )
             an._join_procs.set()
 
-            # collect results (and errors) from all
-            # `.run_in_actor()` children then cancel
-            # each, one reaper task per child.
-            await _reap_ria_portals(an, errors)
-
         # Single one-cancels-all handler for the (now single)
         # daemon nursery. Pre-#477 a 2ndary `._ria_nursery`
         # required a separate *outer* handler to catch errors
@@ -733,46 +595,14 @@ async def _open_and_supervise_one_cancels_all_nursery(
                         # '------ - ------'
                     )
 
-                # snapshot `.run_in_actor()` children
-                # BEFORE cancelling: each backend
-                # spawn-task pops its `._children`
-                # entry as the proc gets reaped.
-                ria_children: list = [
-                    (portal, subactor)
-                    for subactor, _, portal
-                    in an._children.values()
-                    if portal in
-                    an._cancel_after_result_on_exit
-                ]
                 # cancel all subactors
                 await an.cancel()
 
-                # then collect any already-relayed
-                # results/errors from ria children.
-                # Tightly bounded: anything
-                # collectable is already queued in
-                # the local ctx (relayed BEFORE the
-                # cancel above); a child hard-killed
-                # without relaying just parks its
-                # reaper which then self-cleans (a
-                # `trio.Cancelled` result is never
-                # stashed), mirroring the old
-                # backend-side reaper-vs-`soft_kill`
-                # cancel race.
-                with trio.move_on_after(0.5):
-                    await _reap_ria_portals(
-                        an,
-                        errors,
-                        ria_children=ria_children,
-                    )
-
         finally:
-            # No errors were raised while awaiting ".run_in_actor()"
+            # an error was stashed by the handler above (or by
-            # actors but those actors may have returned remote errors as
+            # a spawn task via the shared `errors` dict) so
-            # results (meaning they errored remotely and have relayed
+            # cancel any remaining subactors, summarize and
-            # those errors back to this parent actor). The errors are
+            # re-raise.
-            # collected in ``errors`` so cancel all actors, summarize
-            # all errors and re-raise.
             if errors:
                 if an._children:
                     with trio.CancelScope(shield=True):

tractor/spawn/_mp.py

@@ -188,9 +188,7 @@ async def mp_proc(
 
         # This is a "soft" (cancellable) join/reap which
         # will remote cancel the actor on a ``trio.Cancelled``
-        # condition. Any `.run_in_actor()` result-reaping
+        # condition.
-        # happens up in the `ActorNursery` machinery (see
-        # `_supervise._reap_ria_portals()`), NOT here.
         await soft_kill(
             proc,
             proc_waiter,

tractor/spawn/_spawn.py

@@ -126,98 +126,6 @@ def try_set_start_method(
     return _ctx
 
 
-async def exhaust_portal(
-
-    portal: Portal,
-    actor: Actor
-
-) -> Any:
-    '''
-    Pull final result from portal (assuming it has one).
-
-    If the main task is an async generator do our best to consume
-    what's left of it.
-    '''
-    __tracebackhide__ = True
-    try:
-        log.debug(
-            f'Waiting on final result from {actor.aid.uid}'
-        )
-
-        # XXX: streams should never be reaped here since they should
-        # always be established and shutdown using a context manager api
-        final: Any = await portal.wait_for_result()
-
-    except (
-        Exception,
-        BaseExceptionGroup,
-    ) as err:
-        # we reraise in the parent task via a ``BaseExceptionGroup``
-        return err
-
-    except trio.Cancelled as err:
-        # lol, of course we need this too ;P
-        # TODO: merge with above?
-        log.warning(
-            'Cancelled portal result waiter task:\n'
-            f'uid: {portal.channel.aid}\n'
-            f'error: {err}\n'
-        )
-        return err
-
-    else:
-        log.debug(
-            f'Returning final result from portal:\n'
-            f'uid: {portal.channel.aid}\n'
-            f'result: {final}\n'
-        )
-        return final
-
-
-async def cancel_on_completion(
-
-    portal: Portal,
-    actor: Actor,
-    errors: dict[tuple[str, str], Exception],
-
-) -> None:
-    '''
-    Cancel actor gracefully once its "main" portal's
-    result arrives.
-
-    Should only be called for actors spawned via the
-    `Portal.run_in_actor()` API.
-
-    => and really this API will be deprecated and should be
-    re-implemented as a `.hilevel.one_shot_task_nursery()`..)
-
-    '''
-    # if this call errors we store the exception for later
-    # in ``errors`` which will be reraised inside
-    # an exception group and we still send out a cancel request
-    result: Any|Exception = await exhaust_portal(
-        portal,
-        actor,
-    )
-    if isinstance(result, Exception):
-        errors[actor.aid.uid]: Exception = result
-        log.cancel(
-            'Cancelling subactor runtime due to error:\n\n'
-            f'Portal.cancel_actor() => {portal.channel.aid}\n\n'
-            f'error: {result}\n'
-        )
-
-    else:
-        log.runtime(
-            'Cancelling subactor gracefully:\n\n'
-            f'Portal.cancel_actor() => {portal.channel.aid}\n\n'
-            f'result: {result}\n'
-        )
-
-    # cancel the process now that we have a final result
-    await portal.cancel_actor()
-
-
 async def hard_kill(
     proc: trio.Process,
 
@@ -461,8 +369,8 @@ async def new_proc(
 
 
 # NOTE: bottom-of-module to avoid a circular import since the
-# backend submodules pull `cancel_on_completion`/`soft_kill`/
+# backend submodules pull `soft_kill`/`hard_kill`/`proc_waiter`
-# `hard_kill`/`proc_waiter` from this module.
+# from this module.
 from ._trio import trio_proc
 from ._mp import mp_proc
 

tractor/spawn/_trio.py

@@ -196,9 +196,7 @@ async def trio_proc(
 
         # This is a "soft" (cancellable) join/reap which
         # will remote cancel the actor on a ``trio.Cancelled``
-        # condition. Any `.run_in_actor()` result-reaping
+        # condition.
-        # happens up in the `ActorNursery` machinery (see
-        # `_supervise._reap_ria_portals()`), NOT here.
         await soft_kill(
             proc,
             trio.Process.wait,  # XXX, uses `pidfd_open()` below.

tractor/to_actor/__init__.py

@@ -23,8 +23,8 @@ Adopts the "run it over there" parlance from analogous
 reuse) a subactor, schedule a single remote task, wait on
 its result and (when the call owns the subactor) reap it.
 
-The "spiritual successor" to (and eventual replacement of)
+The "spiritual successor" to (and replacement of) the removed
-the `ActorNursery.run_in_actor()` API; see
+legacy `ActorNursery.run_in_actor()` API; see
 https://github.com/goodboy/tractor/issues/477
 
 '''

tractor/to_actor/_api.py

@@ -31,7 +31,7 @@ the lower level daemon-actor spawn + portal APIs,
 such that error collection and propagation happens in the
 *caller's task* (and thus whatever `trio` nursery/scope
 encloses it) instead of inside the actor-nursery's
-spawn-machinery nurseries as with the (to be deprecated)
+spawn-machinery nurseries as with the (now removed) legacy
 `ActorNursery.run_in_actor()` API.
 
 '''
@@ -151,9 +151,9 @@ async def run(
     the distributed-parallelism equivalent of
     `trio.to_thread.run_sync()`.
 
-    Unlike `ActorNursery.run_in_actor()` (which returns
+    Unlike the removed legacy `.run_in_actor()` (which
-    a `Portal` whose result is only collected at
+    returned a `Portal` whose result was only collected
-    actor-nursery teardown) this is a plain "call and
+    at actor-nursery teardown) this is a plain "call and
     wait" primitive: any remote error is raised HERE, in
     the caller's task. Concurrency is composed the usual
     `trio` way by scheduling multiple `run()` calls in