From 80ce54aeb15523da8906c677ae01725400876d56 Mon Sep 17 00:00:00 2001 From: goodboy Date: Tue, 25 Aug 2026 15:20:34 -0400 Subject: [PATCH] Polish `to_actor` examples and references Remaining review threads requested clearer scheduling intent, result ownership and Portal RPC usage across the migrated examples, plus a more descriptive concurrent-primes filename. Explain the relevant example boundaries, fix the transport typo, expand the local helper signature and rename the live primes example and guide reference while preserving historical Prompt-IO paths. Review: PR #481 (goodboy) https://github.com/goodboy/tractor/pull/481#pullrequestreview-5012942328 (this patch was generated in some part by `opencode` using `gpt-5.6-sol` (`openai`)) --- docs/guide/rpc.rst | 4 ++-- examples/a_trynamic_first_scene.py | 6 +++++- .../multi_nested_subactors_error_up_through_nurseries.py | 2 ++ .../debugging/root_cancelled_but_child_is_in_tty_lock.py | 2 +- .../{to_actor_one_shots.py => concurrent_toactor_primes.py} | 2 +- examples/parallelism/single_func.py | 2 +- 6 files changed, 12 insertions(+), 6 deletions(-) rename examples/parallelism/{to_actor_one_shots.py => concurrent_toactor_primes.py} (96%) diff --git a/docs/guide/rpc.rst b/docs/guide/rpc.rst index fbb4fd97..3a830d3c 100644 --- a/docs/guide/rpc.rst +++ b/docs/guide/rpc.rst @@ -100,7 +100,7 @@ Semantics worth knowing: - it blocks until the remote task returns, re-raising any remote error in the usual boxed form right in the calling task. -- placement also determines process ownership: ``an=`` spawns and +- lifetime mode also determines process ownership: ``an=`` spawns and reaps a fresh child in an existing actor nursery, while passing neither does the same in a private call-scoped nursery (booting the runtime if needed). ``portal=`` instead runs one linked task @@ -108,7 +108,7 @@ Semantics worth knowing: the portal's owner remains responsible for its lifetime. - concurrency composes the plain ``trio`` way: schedule multiple ``run()`` calls into a local task nursery (see - ``examples/parallelism/to_actor_one_shots.py``). + ``examples/parallelism/concurrent_toactor_primes.py``). A reused actor must expose both the target module and the ``to_actor`` context trampoline: diff --git a/examples/a_trynamic_first_scene.py b/examples/a_trynamic_first_scene.py index 27d01ff0..85eb23e7 100644 --- a/examples/a_trynamic_first_scene.py +++ b/examples/a_trynamic_first_scene.py @@ -35,8 +35,12 @@ async def main(): for name in ('donny', 'gretchen') } - async def run_and_print(name: str, other_actor: str): + async def run_and_print( + name: str, + other_actor: str, + ) -> None: print( + # RPC through an existing actor's `Portal`. await portals[name].run( say_hello, other_actor=other_actor, diff --git a/examples/debugging/multi_nested_subactors_error_up_through_nurseries.py b/examples/debugging/multi_nested_subactors_error_up_through_nurseries.py index a18587dc..9929b498 100644 --- a/examples/debugging/multi_nested_subactors_error_up_through_nurseries.py +++ b/examples/debugging/multi_nested_subactors_error_up_through_nurseries.py @@ -37,6 +37,8 @@ async def spawn_until(depth=0): ) ) + # Let the background one-shot enter `breakpoint_forever()` + # before its sibling raises and cancellation propagates. await trio.sleep(0.5) # rx and propagate error from child await tractor.to_actor.run( diff --git a/examples/debugging/root_cancelled_but_child_is_in_tty_lock.py b/examples/debugging/root_cancelled_but_child_is_in_tty_lock.py index 7b2e4d5a..75e1c9a4 100644 --- a/examples/debugging/root_cancelled_but_child_is_in_tty_lock.py +++ b/examples/debugging/root_cancelled_but_child_is_in_tty_lock.py @@ -44,7 +44,7 @@ async def main(): async with ( tractor.open_nursery( debug_mode=True, - enable_transports=['uds'], # TODO, apss this via osenv? + enable_transports=['uds'], # TODO, pass this via osenv? loglevel='devx', # XXX, required for test! ) as an, trio.open_nursery() as tn, diff --git a/examples/parallelism/to_actor_one_shots.py b/examples/parallelism/concurrent_toactor_primes.py similarity index 96% rename from examples/parallelism/to_actor_one_shots.py rename to examples/parallelism/concurrent_toactor_primes.py index e9297547..66cc2020 100644 --- a/examples/parallelism/to_actor_one_shots.py +++ b/examples/parallelism/concurrent_toactor_primes.py @@ -1,5 +1,5 @@ ''' -`tractor.to_actor.run()`: one-shot single-task subactor +`tractor.to_actor.run()`: concurrent one-shot prime checks invocation, the SC-parallelism sibling of `trio.to_thread.run_sync()` (and `anyio.to_process`). diff --git a/examples/parallelism/single_func.py b/examples/parallelism/single_func.py index 3d8409bb..46fc4837 100644 --- a/examples/parallelism/single_func.py +++ b/examples/parallelism/single_func.py @@ -31,7 +31,7 @@ async def main(): tn.start_soon(burn_cpu) # run the same func as the lone task in a subactor, - # block on (and collect) its result + # block on and collect its PID as the caller-side result pid = await tractor.to_actor.run(burn_cpu) print(f"Collected subproc {pid}")