Factor `ActorNursery.run_in_actor()` (and possibly `Portal.run()`) into a new `tractor.to_actor` wrapper API

[goodboy]

Originally from the discussion in #287,

• Nursery does not re-raise error from .run_in_actor() remote task #287 (comment)
• Nursery does not re-raise error from .run_in_actor() remote task #287 (comment)
• Nursery does not re-raise error from .run_in_actor() remote task #287 (comment)

Yeah, after spelunking the original design a bit yesterday I think I'm of the opinion that we should at the least decouple .run_in_actor() from the nursery internals and at most possibly deprecate it from the nursery API.

Argument:

• .run_in_actor() calls can be implemented using .start_actor() + a Portal.run() call spawned from a local trio nursery task

further, a Portal.run() call can be implemented using Portal.open_context() with special handling on child side in the RPC ._invoke() impl; it might actually already be done that way?

-> we can offer a "wrapper" high level API that provides .run_in_actor() as part of a small worker pool API?

I like adopting the parlance from other projects such as .to_thread, to_process, and think we should instead offer a tractor.to_actor. subpkg of APIs which deliver these "higher level one shot" style apis for doing single remote task invocation.

The benefits include:

• massively simplifying our actor nursery cancellation/spawn machinery

• moving error collection and propagation up to some local trio task nursery which is not the same nursery responsible for creating subproc management / spawn tasks

yes! this allows us to drop the iface from ActorNursery (and/or possibly Portal? though not sure on this yet) as needed - which would reduce surface area and the current complexity of .run_in_actor() being couple to multiple runtime layers.

• a simpler API where we can demonstrate how to build the higher level constructs like a worker pool from primitives and there is less ways to do the same thing.

Also linking #172 as maybe another tidbit to consider as sugar level API.

---

Also see nods in the doc regarding this,
https://goodboy.github.io/tractor/api/core.html#tractor.ActorNursery.run_in_actor

and the original deprecation PR,
#290

[goodboy]

A first cut of the tractor.to_actor subpkg sketched above is now
implemented (on the wkt/to_actor_subpkg branch, landing on main
shortly), delivering the "higher level one shot" single-remote-task
API,

• to_actor.run(fn, **fn_kwargs) -> Any: spawn a subactor, schedule
  fn as its lone remote task, block waiting on and return its
  result, ALWAYS reaping the subactor via a finally-scoped
  Portal.cancel_actor(). Composed purely from the lower level
  ActorNursery.start_actor() + Portal.run() primitives exactly as
  prescribed above — zero coupling to the nursery-internal
  ._ria_nursery machinery.
• remote errors raise directly in the caller's task as boxed
  RemoteActorErrors, i.e. error collection/propagation "moves up"
  into whatever local trio scope encloses the call.
• "placement" opts: portal= re-uses an already-running actor (no
  spawn/reap), an= spawns from a caller-managed actor-nursery, and
  passing neither opens a private call-scoped open_nursery()
  (implicitly booting the runtime when needed, tunable via
  pass-through runtime_kwargs).
• concurrency composes the plain trio way: a local task nursery
  scheduling multiple one-shots against a shared an — see the new
  examples/parallelism/to_actor_one_shots.py for the
  worker-pool-ish pattern (a mini version of the neighboring
  concurrent_actors_primes.py referenced in the OP).
• 11-test suite in tests/test_to_actor.py covering all placement
  variants, error relay and pre-spawn arg validation.

Remaining follow-up work to fully resolve this issue,

• migrate in-repo ActorNursery.run_in_actor() usage (test
  suite, experimental/_pubsub.py, examples/docs) over to
  to_actor.run()
• emit a DeprecationWarning from .run_in_actor() (blocked on
  ^ migration)
• drop the ._ria_nursery + ._cancel_after_result_on_exit
  machinery from the nursery/spawn internals — the "massively
  simplifying our actor nursery cancellation/spawn machinery" payoff
  argued in the OP
• docs nod from the ActorNursery.run_in_actor() autodoc entry
  to the successor API
• maybe: the small worker-pool "sugar" API layer (Do we need a streaming equivalent (sugar) for .run_in_actor()? #172)

(this comment was generated in some part by claude-code)