First draft `d2` sequence diagrams for `.msg.types`

Documenting nearly all possible `MsgType` flows so they can eventually
be paired with matching code snippets in our (hopefully) soon to be
reworked docs.

.github/workflows/ci.yml

@@ -8,70 +8,46 @@ on:
   workflow_dispatch:
 
 jobs:
-  # ------ sdist ------
+
+  mypy:
+    name: 'MyPy'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Setup python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: pip install -U . --upgrade-strategy eager -r requirements-test.txt
+
+      - name: Run MyPy check
+        run: mypy tractor/ --ignore-missing-imports --show-traceback
+
   # test that we can generate a software distribution and install it
   # thus avoid missing file issues after packaging.
-  #
-  # -[x] produce sdist with uv
-  # ------ - ------
   sdist-linux:
     name: 'sdist'
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v2
 
-      - name: Install latest uv
-        uses: astral-sh/setup-uv@v6
+      - name: Setup python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.11'
 
-      - name: Build sdist as tar.gz
-        run: uv build --sdist --python=3.13
+      - name: Build sdist
+        run: python setup.py sdist --formats=zip
 
-      - name: Install sdist from .tar.gz
-        run: python -m pip install dist/*.tar.gz
-
-  # ------ type-check ------
-  # mypy:
-  #   name: 'MyPy'
-  #   runs-on: ubuntu-latest
-
-  #   steps:
-  #     - name: Checkout
-  #       uses: actions/checkout@v4
-
-  #     - name: Install latest uv
-  #       uses: astral-sh/setup-uv@v6
-
-  #     # faster due to server caching?
-  #     # https://docs.astral.sh/uv/guides/integration/github/#setting-up-python
-  #     - name: "Set up Python"
-  #       uses: actions/setup-python@v6
-  #       with:
-  #         python-version-file: "pyproject.toml"
-
-  #     # w uv
-  #     # - name: Set up Python
-  #     #   run: uv python install
-
-  #     - name: Setup uv venv
-  #       run: uv venv .venv --python=3.13
-
-  #     - name: Install
-  #       run: uv sync --dev
-
-  #     # TODO, ty cmd over repo
-  #     # - name: type check with ty
-  #     #   run: ty ./tractor/
-
-  #     # - uses: actions/cache@v3
-  #     #     name: Cache uv virtenv as default .venv
-  #     #     with:
-  #     #       path: ./.venv
-  #     #       key: venv-${{ hashFiles('uv.lock') }}
-
-  #     - name: Run MyPy check
-  #       run: mypy tractor/ --ignore-missing-imports --show-traceback
+      - name: Install sdist from .zips
+        run: python -m pip install dist/*.zip
 
 
   testing-linux:
@@ -83,45 +59,32 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ['3.13']
+        python: ['3.11']
         spawn_backend: [
           'trio',
-          # 'mp_spawn',
-          # 'mp_forkserver',
+          'mp_spawn',
+          'mp_forkserver',
         ]
 
     steps:
 
-      - uses: actions/checkout@v4
+      - name: Checkout
+        uses: actions/checkout@v2
 
-      - name: 'Install uv + py-${{ matrix.python-version }}'
-        uses: astral-sh/setup-uv@v6
+      - name: Setup python
+        uses: actions/setup-python@v2
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: '${{ matrix.python }}'
 
-      # GH way.. faster?
-      # - name: setup-python@v6
-      #   uses: actions/setup-python@v6
-      #   with:
-      #     python-version: '${{ matrix.python-version }}'
+      - name: Install dependencies
+        run: pip install -U . -r requirements-test.txt -r requirements-docs.txt --upgrade-strategy eager
 
-      # consider caching for speedups?
-      # https://docs.astral.sh/uv/guides/integration/github/#caching
-
-      - name: Install the project w uv
-        run: uv sync --all-extras --dev
-
-      # - name: Install dependencies
-      #   run: pip install -U . -r requirements-test.txt -r requirements-docs.txt --upgrade-strategy eager
-
-      - name: List deps tree
-        run: uv tree
+      - name: List dependencies
+        run: pip list
 
       - name: Run tests
-        run: uv run pytest tests/ --spawn-backend=${{ matrix.spawn_backend }} -rsx
+        run: pytest tests/ --spawn-backend=${{ matrix.spawn_backend }} -rsx
 
-  # XXX legacy NOTE XXX
-  #
   # We skip 3.10 on windows for now due to not having any collabs to
   # debug the CI failures. Anyone wanting to hack and solve them is very
   # welcome, but our primary user base is not using that OS.

default.nix

@@ -1,19 +0,0 @@
-{ pkgs ? import <nixpkgs> {} }:
-let
-  nativeBuildInputs = with pkgs; [
-    stdenv.cc.cc.lib
-    uv
-  ];
-
-in
-pkgs.mkShell {
-  inherit nativeBuildInputs;
-
-  LD_LIBRARY_PATH = pkgs.lib.makeLibraryPath nativeBuildInputs;
-  TMPDIR = "/tmp";
-
-  shellHook = ''
-    set -e
-    uv venv .venv --python=3.12
-  '';
-}

docs/README.rst

@@ -1,5 +1,8 @@
 |logo| ``tractor``: distributed structurred concurrency
 
+|gh_actions|
+|docs|
+
 ``tractor`` is a `structured concurrency`_ (SC), multi-processing_ runtime built on trio_.
 
 Fundamentally, ``tractor`` provides parallelism via
@@ -63,13 +66,6 @@ Features
   - (WIP) a ``TaskMngr``: one-cancels-one style nursery supervisor.
 
 
-Status of `main` / infra
-------------------------
-
-- |gh_actions|
-- |docs|
-
-
 Install
 -------
 ``tractor`` is still in a *alpha-near-beta-stage* for many
@@ -693,11 +689,9 @@ channel`_!
 .. _msgspec: https://jcristharif.com/msgspec/
 .. _guest: https://trio.readthedocs.io/en/stable/reference-lowlevel.html?highlight=guest%20mode#using-guest-mode-to-run-trio-on-top-of-other-event-loops
 
-..
-   NOTE, on generating badge links from the UI
-   https://docs.github.com/en/actions/how-tos/monitoring-and-troubleshooting-workflows/monitoring-workflows/adding-a-workflow-status-badge?ref=gitguardian-blog-automated-secrets-detection#using-the-ui
-.. |gh_actions| image:: https://github.com/goodboy/tractor/actions/workflows/ci.yml/badge.svg?branch=main
-    :target: https://github.com/goodboy/tractor/actions/workflows/ci.yml
+
+.. |gh_actions| image:: https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fgoodboy%2Ftractor%2Fbadge&style=popout-square
+    :target: https://actions-badge.atrox.dev/goodboy/tractor/goto
 
 .. |docs| image:: https://readthedocs.org/projects/tractor/badge/?version=latest
     :target: https://tractor.readthedocs.io/en/latest/?badge=latest

docs/dgrams/sc_supervision_dialog_proto.d2

@@ -0,0 +1,124 @@
+direction: down
+
+vars: {
+  d2-config: {
+    layout-engine: elk
+    # terminal theme code
+
+    # https://d2lang.com/tour/themes
+    # theme-id: 300  # "terminal" they call it ?? XD
+    theme-id: 200  # purple-n-dark?
+    sketch: true
+  }
+}
+
+sc_supervision_protocol_msgspec: 'all `MsgType`s' {
+    shape: sequence_diagram
+
+    parent: 'parent: Task'
+    child: 'child: Task'
+
+    # ------ supervision txns ------
+    # RPC start (aka fn call) of IPC context
+    parent -> child: 'Start[CallSpec]'
+    child -> parent: 'StartAck[CallSpec]'
+    # sync parent-child SC tasks
+    child -> parent: 'Started[pld: PayloadT]'
+    # ...
+    # maybe-stream phase
+    # parent -> child: 'Proto[pld: TransportT]'
+    parent <-> child: 'Yield[pld: Any]'
+    # stream termination
+    parent <-> child: "Stop[pld: str]"
+    # ...
+    # termination(s) of IPC context
+    parent -> child: 'Cancel'
+    child -> parent: 'CancelAck'
+    # ... OR
+    child -> parent: 'Error[pld: TracebackType]'
+    # ... OR
+    child -> parent: 'Return[pld: PayloadT]'
+}
+
+
+std_rpc: 'classic fn call with final result' {
+    shape: sequence_diagram
+
+    parent: 'parent: Task'
+    child: 'child: Task'
+
+    parent -> child: 'Start[CallSpec]'
+    child -> parent: 'StartAck[CallSpec]'
+    child -> parent: 'Started[pld: PayloadT]'
+    child -> parent: 'Return[pld: PayloadT]'
+}
+
+
+std_rpc_w_streaming: 'fn call, streaming phase, then final result' {
+    shape: sequence_diagram
+
+    parent: 'parent: Task'
+    child: 'child: Task'
+
+    parent -> child: 'Start[CallSpec]'
+    child -> parent: 'StartAck[CallSpec]'
+    child -> parent: 'Started[pld: PayloadT]'
+    parent <-> child: 'Yield[pld: Any]'
+    parent <-> child: "Stop[pld: str]"
+    child -> parent: 'Return[pld: PayloadT]'
+}
+
+
+rpc_w_chld_err: 'child errors mid streaming-phase' {
+    shape: sequence_diagram
+
+    parent: 'parent: Task'
+    child: 'child: Task'
+
+    parent -> child: 'Start[CallSpec]'
+    child -> parent: 'StartAck[CallSpec]'
+    child -> parent: 'Started[pld: PayloadT]'
+    parent <-> child: 'Yield[pld: PayloadT]'
+    child -> parent: 'Error[pld: TracebackType]'
+}
+
+
+rpc_w_rent_err_before_started: 'parent errors then cancels child before `Context.started()`' {
+    shape: sequence_diagram
+
+    parent: 'parent: Task'
+    child: 'child: Task'
+
+    parent -> child: 'Start[CallSpec]'
+    child -> parent: 'StartAck[CallSpec]'
+    parent -> child: 'Cancel'
+    child -> parent: 'CancelAck'
+}
+
+
+graceful_ctxc_rent_to_child: 'parent cancels child mid stream' {
+    shape: sequence_diagram
+
+    parent: 'parent: Task'
+    child: 'child: Task'
+
+    parent -> child: 'Start[CallSpec]'
+    child -> parent: 'StartAck[CallSpec]'
+    child -> parent: 'Started[pld: PayloadT]'
+    parent <-> child: 'Yield[pld: PayloadT]'
+    parent -> child: 'Cancel'
+    child -> parent: 'CancelAck'
+}
+
+graceful_ctxc_child: 'child self-cancels before started' {
+    shape: sequence_diagram
+
+    parent: 'parent: Task'
+    child: 'child: Task'
+
+    parent -> child: 'Start[CallSpec]'
+    child -> parent: 'StartAck[CallSpec]'
+
+    child -> parent: 'Cancel'
+    parent -> child: 'CancelAck'
+}

examples/advanced_faults/ipc_failure_during_stream.py

@@ -21,12 +21,75 @@ import trio
 import pytest
 
 
+async def break_ipc(
+    stream: MsgStream,
+    method: str|None = None,
+    pre_close: bool = False,
+
+    def_method: str = 'eof',
+
+) -> None:
+    '''
+    XXX: close the channel right after an error is raised
+    purposely breaking the IPC transport to make sure the parent
+    doesn't get stuck in debug or hang on the connection join.
+    this more or less simulates an infinite msg-receive hang on
+    the other end.
+
+    '''
+    # close channel via IPC prot msging before
+    # any transport breakage
+    if pre_close:
+        await stream.aclose()
+
+    method: str = method or def_method
+    print(
+        '#################################\n'
+        'Simulating CHILD-side IPC BREAK!\n'
+        f'method: {method}\n'
+        f'pre `.aclose()`: {pre_close}\n'
+        '#################################\n'
+    )
+
+    match method:
+        case 'trans_aclose':
+            await stream._ctx.chan.transport.stream.aclose()
+
+        case 'eof':
+            await stream._ctx.chan.transport.stream.send_eof()
+
+        case 'msg':
+            await stream._ctx.chan.send(None)
+
+        # TODO: the actual real-world simulated cases like
+        # transport layer hangs and/or lower layer 2-gens type
+        # scenarios..
+        #
+        # -[ ] already have some issues for this general testing
+        # area:
+        #  - https://github.com/goodboy/tractor/issues/97
+        #  - https://github.com/goodboy/tractor/issues/124
+        #   - PR from @guille:
+        #     https://github.com/goodboy/tractor/pull/149
+        # case 'hang':
+        # TODO: framework research:
+        #
+        # - https://github.com/GuoTengda1993/pynetem
+        # - https://github.com/shopify/toxiproxy
+        # - https://manpages.ubuntu.com/manpages/trusty/man1/wirefilter.1.html
+
+        case _:
+            raise RuntimeError(
+                f'IPC break method unsupported: {method}'
+            )
+
+
 async def break_ipc_then_error(
     stream: MsgStream,
     break_ipc_with: str|None = None,
     pre_close: bool = False,
 ):
-    await _testing.break_ipc(
+    await break_ipc(
         stream=stream,
         method=break_ipc_with,
         pre_close=pre_close,
@@ -58,32 +121,25 @@ async def recv_and_spawn_net_killers(
     Receive stream msgs and spawn some IPC killers mid-stream.
 
     '''
-    broke_ipc: bool = False
     await ctx.started()
     async with (
         ctx.open_stream() as stream,
-        trio.open_nursery(
-            strict_exception_groups=False,
-        ) as tn,
+        trio.open_nursery() as n,
     ):
         async for i in stream:
             print(f'child echoing {i}')
-            if not broke_ipc:
-                await stream.send(i)
-            else:
-                await trio.sleep(0.01)
+            await stream.send(i)
 
             if (
                 break_ipc_after
                 and
                 i >= break_ipc_after
             ):
-                broke_ipc = True
-                tn.start_soon(
+                n.start_soon(
                     iter_ipc_stream,
                     stream,
                 )
-                tn.start_soon(
+                n.start_soon(
                     partial(
                         break_ipc_then_error,
                         stream=stream,
@@ -120,7 +176,6 @@ async def main(
     break_parent_ipc_after: int|bool = False,
     break_child_ipc_after: int|bool = False,
     pre_close: bool = False,
-    tpt_proto: str = 'tcp',
 
 ) -> None:
 
@@ -132,7 +187,6 @@ async def main(
             # a hang since it never engages due to broken IPC
             debug_mode=debug_mode,
             loglevel=loglevel,
-            enable_transports=[tpt_proto],
 
         ) as an,
     ):
@@ -147,8 +201,7 @@ async def main(
             _testing.expect_ctxc(
                 yay=(
                     break_parent_ipc_after
-                    or
-                    break_child_ipc_after
+                    or break_child_ipc_after
                 ),
                 # TODO: we CAN'T remove this right?
                 # since we need the ctxc to bubble up from either
@@ -189,13 +242,14 @@ async def main(
                         # await stream._ctx.chan.send(None)
                         # await stream._ctx.chan.transport.stream.send_eof()
                         await stream._ctx.chan.transport.stream.aclose()
+
                         ipc_break_sent = True
 
                     # it actually breaks right here in the
-                    # mp_spawn/forkserver backends and thus the
-                    # zombie reaper never even kicks in?
+                    # mp_spawn/forkserver backends and thus the zombie
+                    # reaper never even kicks in?
+                    print(f'parent sending {i}')
                     try:
-                        print(f'parent sending {i}')
                         await stream.send(i)
                     except ContextCancelled as ctxc:
                         print(
@@ -208,13 +262,6 @@ async def main(
                         # TODO: is this needed or no?
                         raise
 
-                    except trio.ClosedResourceError:
-                        # NOTE: don't send if we already broke the
-                        # connection to avoid raising a closed-error
-                        # such that we drop through to the ctl-c
-                        # mashing by user.
-                        await trio.sleep(0.01)
-
                     # timeout: int = 1
                     # with trio.move_on_after(timeout) as cs:
                     async with stuff_hangin_ctlc() as timeout:

examples/debugging/asyncio_bp.py

@@ -1,16 +1,8 @@
-'''
-Examples of using the builtin `breakpoint()` from an `asyncio.Task`
-running in a subactor spawned with `infect_asyncio=True`.
-
-'''
 import asyncio
 
 import trio
 import tractor
-from tractor import (
-    to_asyncio,
-    Portal,
-)
+from tractor import to_asyncio
 
 
 async def aio_sleep_forever():
@@ -25,21 +17,21 @@ async def bp_then_error(
 
 ) -> None:
 
-    # sync with `trio`-side (caller) task
+    # sync with ``trio``-side (caller) task
     to_trio.send_nowait('start')
 
     # NOTE: what happens here inside the hook needs some refinement..
-    # => seems like it's still `.debug._set_trace()` but
+    # => seems like it's still `._debug._set_trace()` but
     #    we set `Lock.local_task_in_debug = 'sync'`, we probably want
-    #    some further, at least, meta-data about the task/actor in debug
-    #    in terms of making it clear it's `asyncio` mucking about.
-    breakpoint()  # asyncio-side
+    #    some further, at least, meta-data about the task/actoq in debug
+    #    in terms of making it clear it's asyncio mucking about.
+    breakpoint()
 
     # short checkpoint / delay
-    await asyncio.sleep(0.5)  # asyncio-side
+    await asyncio.sleep(0.5)
 
     if raise_after_bp:
-        raise ValueError('asyncio side error!')
+        raise ValueError('blah')
 
     # TODO: test case with this so that it gets cancelled?
     else:
@@ -57,21 +49,23 @@ async def trio_ctx(
     # this will block until the ``asyncio`` task sends a "first"
     # message, see first line in above func.
     async with (
+
         to_asyncio.open_channel_from(
             bp_then_error,
-            # raise_after_bp=not bp_before_started,
+            raise_after_bp=not bp_before_started,
         ) as (first, chan),
 
-        trio.open_nursery() as tn,
+        trio.open_nursery() as n,
     ):
+
         assert first == 'start'
 
         if bp_before_started:
-            await tractor.pause()  # trio-side
+            await tractor.breakpoint()
 
-        await ctx.started(first)  # trio-side
+        await ctx.started(first)
 
-        tn.start_soon(
+        n.start_soon(
             to_asyncio.run_task,
             aio_sleep_forever,
         )
@@ -79,50 +73,39 @@ async def trio_ctx(
 
 
 async def main(
-    bps_all_over: bool = True,
-
-    # TODO, WHICH OF THESE HAZ BUGZ?
-    cancel_from_root: bool = False,
-    err_from_root: bool = False,
+    bps_all_over: bool = False,
 
 ) -> None:
 
     async with tractor.open_nursery(
-        debug_mode=True,
-        maybe_enable_greenback=True,
-        # loglevel='devx',
-    ) as an:
-        ptl: Portal = await an.start_actor(
+        # debug_mode=True,
+    ) as n:
+
+        p = await n.start_actor(
             'aio_daemon',
             enable_modules=[__name__],
             infect_asyncio=True,
             debug_mode=True,
-            # loglevel='cancel',
+            loglevel='cancel',
         )
 
-        async with ptl.open_context(
+        async with p.open_context(
             trio_ctx,
             bp_before_started=bps_all_over,
         ) as (ctx, first):
 
             assert first == 'start'
 
-            # pause in parent to ensure no cross-actor
-            # locking problems exist!
-            await tractor.pause()  # trio-root
-
-            if cancel_from_root:
-                await ctx.cancel()
-
-            if err_from_root:
-                assert 0
-            else:
-                await trio.sleep_forever()
+            if bps_all_over:
+                await tractor.breakpoint()
 
+            # await trio.sleep_forever()
+            await ctx.cancel()
+            assert 0
 
         # TODO: case where we cancel from trio-side while asyncio task
         # has debugger lock?
-        # await ptl.cancel_actor()
+        # await p.cancel_actor()
 
 
 if __name__ == '__main__':

examples/debugging/fast_error_in_root_after_spawn.py

@@ -1,5 +1,5 @@
 '''
-Fast fail test with a `Context`.
+Fast fail test with a context.
 
 Ensure the partially initialized sub-actor process
 doesn't cause a hang on error/cancel of the parent

examples/debugging/multi_daemon_subactors.py

@@ -7,7 +7,7 @@ async def breakpoint_forever():
     try:
         while True:
             yield 'yo'
-            await tractor.pause()
+            await tractor.breakpoint()
     except BaseException:
         tractor.log.get_console_log().exception(
             'Cancelled while trying to enter pause point!'
@@ -21,14 +21,11 @@ async def name_error():
 
 
 async def main():
-    '''
-    Test breakpoint in a streaming actor.
-
-    '''
+    """Test breakpoint in a streaming actor.
+    """
     async with tractor.open_nursery(
         debug_mode=True,
         loglevel='cancel',
-        # loglevel='devx',
     ) as n:
 
         p0 = await n.start_actor('bp_forever', enable_modules=[__name__])

examples/debugging/multi_nested_subactors_error_up_through_nurseries.py

@@ -10,7 +10,7 @@ async def name_error():
 async def breakpoint_forever():
     "Indefinitely re-enter debugger in child actor."
     while True:
-        await tractor.pause()
+        await tractor.breakpoint()
 
         # NOTE: if the test never sent 'q'/'quit' commands
         # on the pdb repl, without this checkpoint line the

examples/debugging/multi_subactor_root_errors.py

@@ -40,7 +40,7 @@ async def main():
     """
     async with tractor.open_nursery(
         debug_mode=True,
-        loglevel='devx',
+        # loglevel='cancel',
     ) as n:
 
         # spawn both actors

examples/debugging/multi_subactors.py

@@ -6,7 +6,7 @@ async def breakpoint_forever():
     "Indefinitely re-enter debugger in child actor."
     while True:
         await trio.sleep(0.1)
-        await tractor.pause()
+        await tractor.breakpoint()
 
 
 async def name_error():

examples/debugging/pm_in_subactor.py

@@ -1,56 +0,0 @@
-import trio
-import tractor
-
-
-@tractor.context
-async def name_error(
-    ctx: tractor.Context,
-):
-    '''
-    Raise a `NameError`, catch it and enter `.post_mortem()`, then
-    expect the `._rpc._invoke()` crash handler to also engage.
-
-    '''
-    try:
-        getattr(doggypants)  # noqa (on purpose)
-    except NameError:
-        await tractor.post_mortem()
-        raise
-
-
-async def main():
-    '''
-    Test 3 `PdbREPL` entries:
-      - one in the child due to manual `.post_mortem()`,
-      - another in the child due to runtime RPC crash handling.
-      - final one here in parent from the RAE.
-
-    '''
-    # XXX NOTE: ideally the REPL arrives at this frame in the parent
-    # ONE UP FROM the inner ctx block below!
-    async with tractor.open_nursery(
-        debug_mode=True,
-        # loglevel='cancel',
-    ) as an:
-        p: tractor.Portal = await an.start_actor(
-            'child',
-            enable_modules=[__name__],
-        )
-
-        # XXX should raise `RemoteActorError[NameError]`
-        # AND be the active frame when REPL enters!
-        try:
-            async with p.open_context(name_error) as (ctx, first):
-                assert first
-        except tractor.RemoteActorError as rae:
-            assert rae.boxed_type is NameError
-
-            # manually handle in root's parent task
-            await tractor.post_mortem()
-            raise
-        else:
-            raise RuntimeError('IPC ctx should have remote errored!?')
-
-
-if __name__ == '__main__':
-    trio.run(main)

examples/debugging/restore_builtin_breakpoint.py

@@ -4,55 +4,21 @@ import sys
 import trio
 import tractor
 
-# ensure mod-path is correct!
-from tractor.devx.debug import (
-    _sync_pause_from_builtin as _sync_pause_from_builtin,
-)
-
 
 async def main() -> None:
+    async with tractor.open_nursery(debug_mode=True) as an:
 
-    # intially unset, no entry.
-    orig_pybp_var: int = os.environ.get('PYTHONBREAKPOINT')
-    assert orig_pybp_var in {None, "0"}
-
-    async with tractor.open_nursery(
-        debug_mode=True,
-        loglevel='devx',
-        maybe_enable_greenback=True,
-        # ^XXX REQUIRED to enable `breakpoint()` support (from sync
-        # fns) and thus required here to avoid an assertion err
-        # on the next line
-    ):
-        assert (
-            (pybp_var := os.environ['PYTHONBREAKPOINT'])
-            ==
-            'tractor.devx.debug._sync_pause_from_builtin'
-        )
+        assert os.environ['PYTHONBREAKPOINT'] == 'tractor._debug._set_trace'
 
         # TODO: an assert that verifies the hook has indeed been, hooked
         # XD
-        assert (
-            (pybp_hook := sys.breakpointhook)
-            is not tractor.devx.debug._set_trace
-        )
+        assert sys.breakpointhook is not tractor._debug._set_trace
 
-        print(
-            f'$PYTHONOBREAKPOINT: {pybp_var!r}\n'
-            f'`sys.breakpointhook`: {pybp_hook!r}\n'
-        )
-        breakpoint()  # first bp, tractor hook set.
+        breakpoint()
 
-    # XXX AFTER EXIT (of actor-runtime) verify the hook is unset..
-    #
-    # YES, this is weird but it's how stdlib docs say to do it..
-    # https://docs.python.org/3/library/sys.html#sys.breakpointhook
-    assert os.environ.get('PYTHONBREAKPOINT') is orig_pybp_var
+    # TODO: an assert that verifies the hook is unhooked..
     assert sys.breakpointhook
-
-    # now ensure a regular builtin pause still works
-    breakpoint()  # last bp, stdlib hook restored
-
+    breakpoint()
 
 if __name__ == '__main__':
     trio.run(main)

examples/debugging/root_actor_breakpoint.py

@@ -10,7 +10,7 @@ async def main():
 
         await trio.sleep(0.1)
 
-        await tractor.pause()
+        await tractor.breakpoint()
 
         await trio.sleep(0.1)
 

examples/debugging/root_actor_breakpoint_forever.py

@@ -11,7 +11,7 @@ async def main(
         # loglevel='runtime',
     ):
         while True:
-            await tractor.pause()
+            await tractor.breakpoint()
 
 
 if __name__ == '__main__':

examples/debugging/root_cancelled_but_child_is_in_tty_lock.py

@@ -24,9 +24,10 @@ async def spawn_until(depth=0):
 
 
 async def main():
-    '''
-    The process tree should look as approximately as follows when the
-    debugger first engages:
+    """The main ``tractor`` routine.
+
+    The process tree should look as approximately as follows when the debugger
+    first engages:
 
     python examples/debugging/multi_nested_subactors_bp_forever.py
     ├─ python -m tractor._child --uid ('spawner1', '7eab8462 ...)
@@ -36,11 +37,10 @@ async def main():
     └─ python -m tractor._child --uid ('spawner0', '1d42012b ...)
        └─ python -m tractor._child --uid ('name_error', '6c2733b8 ...)
 
-    '''
+    """
     async with tractor.open_nursery(
         debug_mode=True,
-        loglevel='devx',
-        enable_transports=['uds'],
+        loglevel='warning'
     ) as n:
 
         # spawn both actors

examples/debugging/shield_hang_in_sub.py

@@ -1,84 +0,0 @@
-'''
-Verify we can dump a `stackscope` tree on a hang.
-
-'''
-import os
-import signal
-
-import trio
-import tractor
-
-@tractor.context
-async def start_n_shield_hang(
-    ctx: tractor.Context,
-):
-    # actor: tractor.Actor = tractor.current_actor()
-
-    # sync to parent-side task
-    await ctx.started(os.getpid())
-
-    print('Entering shield sleep..')
-    with trio.CancelScope(shield=True):
-        await trio.sleep_forever()  # in subactor
-
-    # XXX NOTE ^^^ since this shields, we expect
-    # the zombie reaper (aka T800) to engage on
-    # SIGINT from the user and eventually hard-kill
-    # this subprocess!
-
-
-async def main(
-    from_test: bool = False,
-) -> None:
-
-    async with (
-        tractor.open_nursery(
-            debug_mode=True,
-            enable_stack_on_sig=True,
-            # maybe_enable_greenback=False,
-            loglevel='devx',
-            enable_transports=['uds'],
-        ) as an,
-    ):
-        ptl: tractor.Portal  = await an.start_actor(
-            'hanger',
-            enable_modules=[__name__],
-            debug_mode=True,
-        )
-        async with ptl.open_context(
-            start_n_shield_hang,
-        ) as (ctx, cpid):
-
-            _, proc, _ = an._children[ptl.chan.uid]
-            assert cpid == proc.pid
-
-            print(
-                'Yo my child hanging..?\n'
-                # "i'm a user who wants to see a `stackscope` tree!\n"
-            )
-
-            # XXX simulate the wrapping test's "user actions"
-            # (i.e. if a human didn't run this manually but wants to
-            # know what they should do to reproduce test behaviour)
-            if from_test:
-                print(
-                    f'Sending SIGUSR1 to {cpid!r}!\n'
-                )
-                os.kill(
-                    cpid,
-                    signal.SIGUSR1,
-                )
-
-                # simulate user cancelling program
-                await trio.sleep(0.5)
-                os.kill(
-                    os.getpid(),
-                    signal.SIGINT,
-                )
-            else:
-                # actually let user send the ctl-c
-                await trio.sleep_forever()  # in root
-
-
-if __name__ == '__main__':
-    trio.run(main)

examples/debugging/shielded_pause.py

@@ -1,88 +0,0 @@
-import trio
-import tractor
-
-
-async def cancellable_pause_loop(
-    task_status: trio.TaskStatus[trio.CancelScope] = trio.TASK_STATUS_IGNORED
-):
-    with trio.CancelScope() as cs:
-        task_status.started(cs)
-        for _ in range(3):
-            try:
-                # ON first entry, there is no level triggered
-                # cancellation yet, so this cp does a parent task
-                # ctx-switch so that this scope raises for the NEXT
-                # checkpoint we hit.
-                await trio.lowlevel.checkpoint()
-                await tractor.pause()
-
-                cs.cancel()
-
-                # parent should have called `cs.cancel()` by now
-                await trio.lowlevel.checkpoint()
-
-            except trio.Cancelled:
-                print('INSIDE SHIELDED PAUSE')
-                await tractor.pause(shield=True)
-        else:
-            # should raise it again, bubbling up to parent
-            print('BUBBLING trio.Cancelled to parent task-nursery')
-            await trio.lowlevel.checkpoint()
-
-
-async def pm_on_cancelled():
-    async with trio.open_nursery() as tn:
-        tn.cancel_scope.cancel()
-        try:
-            await trio.sleep_forever()
-        except trio.Cancelled:
-            # should also raise `Cancelled` since
-            # we didn't pass `shield=True`.
-            try:
-                await tractor.post_mortem(hide_tb=False)
-            except trio.Cancelled as taskc:
-
-                # should enter just fine, in fact it should
-                # be debugging the internals of the previous
-                # sin-shield call above Bo
-                await tractor.post_mortem(
-                    hide_tb=False,
-                    shield=True,
-                )
-                raise taskc
-
-        else:
-            raise RuntimeError('Dint cancel as expected!?')
-
-
-async def cancelled_before_pause(
-):
-    '''
-    Verify that using a shielded pause works despite surrounding
-    cancellation called state in the calling task.
-
-    '''
-    async with trio.open_nursery() as tn:
-        cs: trio.CancelScope = await tn.start(cancellable_pause_loop)
-        await trio.sleep(0.1)
-
-    assert cs.cancelled_caught
-
-    await pm_on_cancelled()
-
-
-async def main():
-    async with tractor.open_nursery(
-        debug_mode=True,
-    ) as n:
-        portal: tractor.Portal = await n.run_in_actor(
-            cancelled_before_pause,
-        )
-        await portal.result()
-
-        # ensure the same works in the root actor!
-        await pm_on_cancelled()
-
-
-if __name__ == '__main__':
-    trio.run(main)

examples/debugging/subactor_bp_in_ctx.py

@@ -4,9 +4,9 @@ import trio
 
 async def gen():
     yield 'yo'
-    await tractor.pause()
+    await tractor.breakpoint()
     yield 'yo'
-    await tractor.pause()
+    await tractor.breakpoint()
 
 
 @tractor.context
@@ -15,7 +15,7 @@ async def just_bp(
 ) -> None:
 
     await ctx.started()
-    await tractor.pause()
+    await tractor.breakpoint()
 
     # TODO: bps and errors in this call..
     async for val in gen():
@@ -33,11 +33,8 @@ async def just_bp(
 
 
 async def main():
-
     async with tractor.open_nursery(
         debug_mode=True,
-        enable_transports=['uds'],
-        loglevel='devx',
     ) as n:
         p = await n.start_actor(
             'bp_boi',

examples/debugging/sync_bp.py

@@ -1,37 +1,16 @@
-from functools import partial
-import time
-
 import trio
 import tractor
 
-# TODO: only import these when not running from test harness?
-# can we detect `pexpect` usage maybe?
-# from tractor.devx.debug import (
-#     get_lock,
-#     get_debug_req,
-# )
-
 
 def sync_pause(
-    use_builtin: bool = False,
+    use_builtin: bool = True,
     error: bool = False,
-    hide_tb: bool = True,
-    pre_sleep: float|None = None,
 ):
-    if pre_sleep:
-        time.sleep(pre_sleep)
-
     if use_builtin:
-        breakpoint(hide_tb=hide_tb)
+        breakpoint(hide_tb=False)
 
     else:
-        # TODO: maybe for testing some kind of cm style interface
-        # where the `._set_trace()` call doesn't happen until block
-        # exit?
-        # assert get_lock().ctx_in_debug is None
-        # assert get_debug_req().repl is None
         tractor.pause_from_sync()
-        # assert get_debug_req().repl is None
 
     if error:
         raise RuntimeError('yoyo sync code error')
@@ -46,117 +25,44 @@ async def start_n_sync_pause(
     # sync to parent-side task
     await ctx.started()
 
-    print(f'Entering `sync_pause()` in subactor: {actor.uid}\n')
+    print(f'entering SYNC PAUSE in {actor.uid}')
     sync_pause()
-    print(f'Exited `sync_pause()` in subactor: {actor.uid}\n')
+    print(f'back from SYNC PAUSE in {actor.uid}')
 
 
 async def main() -> None:
-    async with (
-        tractor.open_nursery(
-            debug_mode=True,
-            maybe_enable_greenback=True,
-            enable_stack_on_sig=True,
-            # loglevel='warning',
-            # loglevel='devx',
-        ) as an,
-        trio.open_nursery() as tn,
-    ):
-        # just from root task
-        sync_pause()
+    async with tractor.open_nursery(
+        # NOTE: required for pausing from sync funcs
+        maybe_enable_greenback=True,
+        debug_mode=True,
+    ) as an:
 
         p: tractor.Portal  = await an.start_actor(
             'subactor',
             enable_modules=[__name__],
             # infect_asyncio=True,
             debug_mode=True,
+            loglevel='cancel',
         )
 
         # TODO: 3 sub-actor usage cases:
-        # -[x] via a `.open_context()`
         # -[ ] via a `.run_in_actor()` call
         # -[ ] via a `.run()`
-        # -[ ] via a `.to_thread.run_sync()` in subactor
+        # -[ ] via a `.open_context()`
+        #
         async with p.open_context(
             start_n_sync_pause,
         ) as (ctx, first):
             assert first is None
 
-            # TODO: handle bg-thread-in-root-actor special cases!
-            #
-            # there are a couple very subtle situations possible here
-            # and they are likely to become more important as cpython
-            # moves to support no-GIL.
-            #
-            # Cases:
-            # 1. root-actor bg-threads that call `.pause_from_sync()`
-            #   whilst an in-tree subactor also is using ` .pause()`.
-            # |_ since the root-actor bg thread can not
-            #   `Lock._debug_lock.acquire_nowait()` without running
-            #   a `trio.Task`, AND because the
-            #   `PdbREPL.set_continue()` is called from that
-            #   bg-thread, we can not `._debug_lock.release()`
-            #   either!
-            #  |_ this results in no actor-tree `Lock` being used
-            #    on behalf of the bg-thread and thus the subactor's
-            #    task and the thread trying to to use stdio
-            #    simultaneously which results in the classic TTY
-            #    clobbering!
-            #
-            # 2. mutiple sync-bg-threads that call
-            #   `.pause_from_sync()` where one is scheduled via
-            #   `Nursery.start_soon(to_thread.run_sync)` in a bg
-            #   task.
-            #
-            #   Due to the GIL, the threads never truly try to step
-            #   through the REPL simultaneously, BUT their `logging`
-            #   and traceback outputs are interleaved since the GIL
-            #   (seemingly) on every REPL-input from the user
-            #   switches threads..
-            #
-            #   Soo, the context switching semantics of the GIL
-            #   result in a very confusing and messy interaction UX
-            #   since eval and (tb) print output is NOT synced to
-            #   each REPL-cycle (like we normally make it via
-            #   a `.set_continue()` callback triggering the
-            #   `Lock.release()`). Ideally we can solve this
-            #   usability issue NOW because this will of course be
-            #   that much more important when eventually there is no
-            #   GIL!
-
-            # XXX should cause double REPL entry and thus TTY
-            # clobbering due to case 1. above!
-            tn.start_soon(
-                partial(
-                    trio.to_thread.run_sync,
-                    partial(
-                        sync_pause,
-                        use_builtin=False,
-                        # pre_sleep=0.5,
-                    ),
-                    abandon_on_cancel=True,
-                    thread_name='start_soon_root_bg_thread',
-                )
-            )
-
             await tractor.pause()
+            sync_pause()
 
-            # XXX should cause double REPL entry and thus TTY
-            # clobbering due to case 2. above!
-            await trio.to_thread.run_sync(
-                partial(
-                    sync_pause,
-                    # NOTE this already works fine since in the new
-                    # thread the `breakpoint()` built-in is never
-                    # overloaded, thus NO locking is used, HOWEVER
-                    # the case 2. from above still exists!
-                    use_builtin=True,
-                ),
-                # TODO: with this `False` we can hang!??!
-                # abandon_on_cancel=False,
-                abandon_on_cancel=True,
-                thread_name='inline_root_bg_thread',
-            )
+        # TODO: make this work!!
+        await trio.to_thread.run_sync(
+            sync_pause,
+            abandon_on_cancel=False,
+        )
 
         await ctx.cancel()
 

examples/full_fledged_streaming_service.py

@@ -1,11 +1,6 @@
 import time
 import trio
 import tractor
-from tractor import (
-    ActorNursery,
-    MsgStream,
-    Portal,
-)
 
 
 # this is the first 2 actors, streamer_1 and streamer_2
@@ -17,18 +12,14 @@ async def stream_data(seed):
 
 # this is the third actor; the aggregator
 async def aggregate(seed):
-    '''
-    Ensure that the two streams we receive match but only stream
+    """Ensure that the two streams we receive match but only stream
     a single set of values to the parent.
-
-    '''
-    an: ActorNursery
-    async with tractor.open_nursery() as an:
-        portals: list[Portal] = []
+    """
+    async with tractor.open_nursery() as nursery:
+        portals = []
         for i in range(1, 3):
-
-            # fork/spawn call
-            portal = await an.start_actor(
+            # fork point
+            portal = await nursery.start_actor(
                 name=f'streamer_{i}',
                 enable_modules=[__name__],
             )
@@ -52,11 +43,7 @@ async def aggregate(seed):
         async with trio.open_nursery() as n:
 
             for portal in portals:
-                n.start_soon(
-                    push_to_chan,
-                    portal,
-                    send_chan.clone(),
-                )
+                n.start_soon(push_to_chan, portal, send_chan.clone())
 
             # close this local task's reference to send side
             await send_chan.aclose()
@@ -73,7 +60,7 @@ async def aggregate(seed):
 
             print("FINISHED ITERATING in aggregator")
 
-        await an.cancel()
+        await nursery.cancel()
         print("WAITING on `ActorNursery` to finish")
     print("AGGREGATOR COMPLETE!")
 
@@ -88,21 +75,18 @@ async def main() -> list[int]:
 
     '''
     # yes, a nursery which spawns `trio`-"actors" B)
-    an: ActorNursery
-    async with tractor.open_nursery(
-        loglevel='cancel',
-        # debug_mode=True,
-    ) as an:
+    nursery: tractor.ActorNursery
+    async with tractor.open_nursery() as nursery:
 
         seed = int(1e3)
         pre_start = time.time()
 
-        portal: Portal = await an.start_actor(
+        portal: tractor.Portal = await nursery.start_actor(
             name='aggregator',
             enable_modules=[__name__],
         )
 
-        stream: MsgStream
+        stream: tractor.MsgStream
         async with portal.open_stream_from(
             aggregate,
             seed=seed,
@@ -111,12 +95,11 @@ async def main() -> list[int]:
             start = time.time()
             # the portal call returns exactly what you'd expect
             # as if the remote "aggregate" function was called locally
-            result_stream: list[int] = []
+            result_stream = []
             async for value in stream:
                 result_stream.append(value)
 
-        cancelled: bool = await portal.cancel_actor()
-        assert cancelled
+        await portal.cancel_actor()
 
         print(f"STREAM TIME = {time.time() - start}")
         print(f"STREAM + SPAWN TIME = {time.time() - pre_start}")

examples/quick_cluster.py

@@ -3,18 +3,20 @@ import trio
 import tractor
 
 
-async def sleepy_jane() -> None:
-    uid: tuple = tractor.current_actor().uid
+async def sleepy_jane():
+    uid = tractor.current_actor().uid
     print(f'Yo i am actor {uid}')
     await trio.sleep_forever()
 
 
 async def main():
     '''
-    Spawn a flat actor cluster, with one process per detected core.
+    Spawn a flat actor cluster, with one process per
+    detected core.
 
     '''
     portal_map: dict[str, tractor.Portal]
+    results: dict[str, str]
 
     # look at this hip new syntax!
     async with (
@@ -23,16 +25,11 @@ async def main():
             modules=[__name__]
         ) as portal_map,
 
-        trio.open_nursery(
-            strict_exception_groups=False,
-        ) as tn,
+        trio.open_nursery() as n,
     ):
 
         for (name, portal) in portal_map.items():
-            tn.start_soon(
-                portal.run,
-                sleepy_jane,
-            )
+            n.start_soon(portal.run, sleepy_jane)
 
         await trio.sleep(0.5)
 
@@ -44,4 +41,4 @@ if __name__ == '__main__':
     try:
         trio.run(main)
     except KeyboardInterrupt:
-        print('trio cancelled by KBI')
+        pass

examples/service_discovery.py

@@ -9,7 +9,7 @@ async def main(service_name):
     async with tractor.open_nursery() as an:
         await an.start_actor(service_name)
 
-        async with tractor.get_registry() as portal:
+        async with tractor.get_arbiter('127.0.0.1', 1616) as portal:
             print(f"Arbiter is listening on {portal.channel}")
 
         async with tractor.wait_for_actor(service_name) as sockaddr:

notes_to_self/howtorelease.md

@@ -1,18 +0,0 @@
-First generate a built disti:
-
-```
-python -m pip install --upgrade build
-python -m build --sdist --outdir dist/alpha5/
-```
-
-Then try a test ``pypi`` upload:
-
-```
-python -m twine upload --repository testpypi dist/alpha5/*
-```
-
-The push to `pypi` for realz.
-
-```
-python -m twine upload --repository testpypi dist/alpha5/*
-```

pyproject.toml

@@ -37,16 +37,16 @@ dependencies = [
   # https://packaging.python.org/en/latest/discussions/install-requires-vs-requirements/#id5
   # TODO, for 3.13 we must go go `0.27` which means we have to
   # disable strict egs or port to handling them internally!
-  "trio>0.27",
+  # trio='^0.27'
+  "trio>=0.24,<0.25",
   "tricycle>=0.4.1,<0.5",
   "wrapt>=1.16.0,<2",
   "colorlog>=6.8.2,<7",
   # built-in multi-actor `pdb` REPL
-  "pdbp>=1.6,<2", # windows only (from `pdbp`)
+  "pdbp>=1.5.0,<2",
   # typed IPC msging
-  "msgspec>=0.19.0",
-  "cffi>=1.17.1",
-  "bidict>=0.23.1",
+  # TODO, get back on release once 3.13 support is out!
+  "msgspec",
 ]
 
 # ------ project ------
@@ -56,18 +56,18 @@ dev = [
   # test suite
   # TODO: maybe some of these layout choices?
   # https://docs.pytest.org/en/8.0.x/explanation/goodpractices.html#choosing-a-test-layout-import-rules
-  "pytest>=8.3.5",
+  "pytest>=8.2.0,<9",
   "pexpect>=4.9.0,<5",
   # `tractor.devx` tooling
   "greenback>=1.2.1,<2",
   "stackscope>=0.2.2,<0.3",
-  # ^ requires this?
-  "typing-extensions>=4.14.1",
 
+  # xonsh usage/integration (namely as @goodboy's sh of choice Bp)
+  "xonsh>=0.19.1",
+  "xontrib-vox>=0.0.1,<0.0.2",
+  "prompt-toolkit>=3.0.43,<4",
+  "xonsh-vox-tabcomplete>=0.5,<0.6",
   "pyperclip>=1.9.0",
-  "prompt-toolkit>=3.0.50",
-  "xonsh>=0.19.2",
-  "psutil>=7.0.0",
 ]
 # TODO, add these with sane versions; were originally in
 # `requirements-docs.txt`..
@@ -78,39 +78,21 @@ dev = [
 
 # ------ dependency-groups ------
 
-# ------ dependency-groups ------
-
 [tool.uv.sources]
-# XXX NOTE, only for @goodboy's hacking on `pprint(sort_dicts=False)`
-# for the `pp` alias..
-# pdbp = { path = "../pdbp", editable = true }
+msgspec = { git = "https://github.com/jcrist/msgspec.git" }
 
 # ------ tool.uv.sources ------
 # TODO, distributed (multi-host) extensions
 # linux kernel networking
 # 'pyroute2
 
-# ------ tool.uv.sources ------
-
-[tool.uv]
-# XXX NOTE, prefer the sys python bc apparently the distis from
-# `astral` are built in a way that breaks `pdbp`+`tabcompleter`'s
-# likely due to linking against `libedit` over `readline`..
-# |_https://docs.astral.sh/uv/concepts/python-versions/#managed-python-distributions
-# |_https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html#use-of-libedit-on-linux
-#
-# https://docs.astral.sh/uv/reference/settings/#python-preference
-python-preference = 'system'
-
-# ------ tool.uv ------
-
 [tool.hatch.build.targets.sdist]
 include = ["tractor"]
 
 [tool.hatch.build.targets.wheel]
 include = ["tractor"]
 
-# ------ tool.hatch ------
+# ------ dependency-groups ------
 
 [tool.towncrier]
 package = "tractor"
@@ -160,5 +142,3 @@ log_cli = false
 # TODO: maybe some of these layout choices?
 # https://docs.pytest.org/en/8.0.x/explanation/goodpractices.html#choosing-a-test-layout-import-rules
 # pythonpath = "src"
-
-# ------ tool.pytest ------

tests/conftest.py

@@ -1,27 +1,24 @@
 """
-Top level of the testing suites!
-
+``tractor`` testing!!
 """
-from __future__ import annotations
 import sys
 import subprocess
 import os
+import random
 import signal
 import platform
 import time
 
 import pytest
+import tractor
 from tractor._testing import (
     examples_dir as examples_dir,
     tractor_test as tractor_test,
     expect_ctxc as expect_ctxc,
 )
 
-pytest_plugins: list[str] = [
-    'pytester',
-    'tractor._testing.pytest',
-]
-
+# TODO: include wtv plugin(s) we build in `._testing.pytest`?
+pytest_plugins = ['pytester']
 
 # Sending signal.SIGINT on subprocess fails on windows. Use CTRL_* alternatives
 if platform.system() == 'Windows':
@@ -33,11 +30,7 @@ else:
     _KILL_SIGNAL = signal.SIGKILL
     _INT_SIGNAL = signal.SIGINT
     _INT_RETURN_CODE = 1 if sys.version_info < (3, 8) else -signal.SIGINT.value
-    _PROC_SPAWN_WAIT = (
-        0.6
-        if sys.version_info < (3, 7)
-        else 0.4
-    )
+    _PROC_SPAWN_WAIT = 0.6 if sys.version_info < (3, 7) else 0.4
 
 
 no_windows = pytest.mark.skipif(
@@ -46,12 +39,7 @@ no_windows = pytest.mark.skipif(
 )
 
 
-def pytest_addoption(
-    parser: pytest.Parser,
-):
-    # ?TODO? should this be exposed from our `._testing.pytest`
-    # plugin or should we make it more explicit with `--tl` for
-    # tractor logging like we do in other client projects?
+def pytest_addoption(parser):
     parser.addoption(
         "--ll",
         action="store",
@@ -59,10 +47,39 @@ def pytest_addoption(
         default='ERROR', help="logging level to set when testing"
     )
 
+    parser.addoption(
+        "--spawn-backend",
+        action="store",
+        dest='spawn_backend',
+        default='trio',
+        help="Processing spawning backend to use for test run",
+    )
+
+    parser.addoption(
+        "--tpdb", "--debug-mode",
+        action="store_true",
+        dest='tractor_debug_mode',
+        # default=False,
+        help=(
+            'Enable a flag that can be used by tests to to set the '
+            '`debug_mode: bool` for engaging the internal '
+            'multi-proc debugger sys.'
+        ),
+    )
+
+
+def pytest_configure(config):
+    backend = config.option.spawn_backend
+    tractor._spawn.try_set_start_method(backend)
+
+
+@pytest.fixture(scope='session')
+def debug_mode(request):
+    return request.config.option.tractor_debug_mode
+
 
 @pytest.fixture(scope='session', autouse=True)
 def loglevel(request):
-    import tractor
     orig = tractor.log._default_loglevel
     level = tractor.log._default_loglevel = request.config.option.loglevel
     tractor.log.get_console_log(level)
@@ -70,44 +87,88 @@ def loglevel(request):
     tractor.log._default_loglevel = orig
 
 
+@pytest.fixture(scope='session')
+def spawn_backend(request) -> str:
+    return request.config.option.spawn_backend
+
+
 _ci_env: bool = os.environ.get('CI', False)
 
 
 @pytest.fixture(scope='session')
 def ci_env() -> bool:
     '''
-    Detect CI environment.
+    Detect CI envoirment.
 
     '''
     return _ci_env
 
 
-def sig_prog(
-    proc: subprocess.Popen,
-    sig: int,
-    canc_timeout: float = 0.1,
-) -> int:
+# TODO: also move this to `._testing` for now?
+# -[ ] possibly generalize and re-use for multi-tree spawning
+#    along with the new stuff for multi-addrs in distribute_dis
+#    branch?
+#
+# choose randomly at import time
+_reg_addr: tuple[str, int] = (
+    '127.0.0.1',
+    random.randint(1000, 9999),
+)
+
+
+@pytest.fixture(scope='session')
+def reg_addr() -> tuple[str, int]:
+
+    # globally override the runtime to the per-test-session-dynamic
+    # addr so that all tests never conflict with any other actor
+    # tree using the default.
+    from tractor import _root
+    _root._default_lo_addrs = [_reg_addr]
+
+    return _reg_addr
+
+
+def pytest_generate_tests(metafunc):
+    spawn_backend = metafunc.config.option.spawn_backend
+
+    if not spawn_backend:
+        # XXX some weird windows bug with `pytest`?
+        spawn_backend = 'trio'
+
+    # TODO: maybe just use the literal `._spawn.SpawnMethodKey`?
+    assert spawn_backend in (
+        'mp_spawn',
+        'mp_forkserver',
+        'trio',
+    )
+
+    # NOTE: used to be used to dyanmically parametrize tests for when
+    # you just passed --spawn-backend=`mp` on the cli, but now we expect
+    # that cli input to be manually specified, BUT, maybe we'll do
+    # something like this again in the future?
+    if 'start_method' in metafunc.fixturenames:
+        metafunc.parametrize("start_method", [spawn_backend], scope='module')
+
+
+def sig_prog(proc, sig):
     "Kill the actor-process with ``sig``."
     proc.send_signal(sig)
-    time.sleep(canc_timeout)
+    time.sleep(0.1)
     if not proc.poll():
         # TODO: why sometimes does SIGINT not work on teardown?
         # seems to happen only when trace logging enabled?
         proc.send_signal(_KILL_SIGNAL)
-    ret: int = proc.wait()
+    ret = proc.wait()
     assert ret
 
 
 # TODO: factor into @cm and move to `._testing`?
 @pytest.fixture
 def daemon(
-    debug_mode: bool,
     loglevel: str,
-    testdir: pytest.Pytester,
+    testdir,
     reg_addr: tuple[str, int],
-    tpt_proto: str,
-
-) -> subprocess.Popen:
+):
     '''
     Run a daemon root actor as a separate actor-process tree and
     "remote registrar" for discovery-protocol related tests.
@@ -118,100 +179,28 @@ def daemon(
         loglevel: str = 'info'
 
     code: str = (
-        "import tractor; "
-        "tractor.run_daemon([], "
-        "registry_addrs={reg_addrs}, "
-        "debug_mode={debug_mode}, "
-        "loglevel={ll})"
+            "import tractor; "
+            "tractor.run_daemon([], registry_addrs={reg_addrs}, loglevel={ll})"
     ).format(
         reg_addrs=str([reg_addr]),
         ll="'{}'".format(loglevel) if loglevel else None,
-        debug_mode=debug_mode,
     )
     cmd: list[str] = [
         sys.executable,
         '-c', code,
     ]
-    # breakpoint()
     kwargs = {}
     if platform.system() == 'Windows':
         # without this, tests hang on windows forever
         kwargs['creationflags'] = subprocess.CREATE_NEW_PROCESS_GROUP
 
-    proc: subprocess.Popen = testdir.popen(
+    proc = testdir.popen(
         cmd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
         **kwargs,
     )
-
-    # UDS sockets are **really** fast to bind()/listen()/connect()
-    # so it's often required that we delay a bit more starting
-    # the first actor-tree..
-    if tpt_proto == 'uds':
-        global _PROC_SPAWN_WAIT
-        _PROC_SPAWN_WAIT = 0.6
-
-    time.sleep(_PROC_SPAWN_WAIT)
-
     assert not proc.returncode
+    time.sleep(_PROC_SPAWN_WAIT)
     yield proc
     sig_prog(proc, _INT_SIGNAL)
-
-    # XXX! yeah.. just be reaaal careful with this bc sometimes it
-    # can lock up on the `_io.BufferedReader` and hang..
-    stderr: str = proc.stderr.read().decode()
-    if stderr:
-        print(
-            f'Daemon actor tree produced STDERR:\n'
-            f'{proc.args}\n'
-            f'\n'
-            f'{stderr}\n'
-        )
-    if proc.returncode != -2:
-        raise RuntimeError(
-            'Daemon actor tree failed !?\n'
-            f'{proc.args}\n'
-        )
-
-
-# @pytest.fixture(autouse=True)
-# def shared_last_failed(pytestconfig):
-#     val = pytestconfig.cache.get("example/value", None)
-#     breakpoint()
-#     if val is None:
-#         pytestconfig.cache.set("example/value", val)
-#     return val
-
-
-# TODO: a way to let test scripts (like from `examples/`)
-# guarantee they won't `registry_addrs` collide!
-# -[ ] maybe use some kinda standard `def main()` arg-spec that
-#     we can introspect from a fixture that is called from the test
-#     body?
-# -[ ] test and figure out typing for below prototype! Bp
-#
-# @pytest.fixture
-# def set_script_runtime_args(
-#     reg_addr: tuple,
-# ) -> Callable[[...], None]:
-
-#     def import_n_partial_in_args_n_triorun(
-#         script: Path,  # under examples?
-#         **runtime_args,
-#     ) -> Callable[[], Any]:  # a `partial`-ed equiv of `trio.run()`
-
-#         # NOTE, below is taken from
-#         # `.test_advanced_faults.test_ipc_channel_break_during_stream`
-#         mod: ModuleType = import_path(
-#             examples_dir() / 'advanced_faults'
-#             / 'ipc_failure_during_stream.py',
-#             root=examples_dir(),
-#             consider_namespace_packages=False,
-#         )
-#         return partial(
-#             trio.run,
-#             partial(
-#                 mod.main,
-#                 **runtime_args,
-#             )
-#         )
-#     return import_n_partial_in_args_n_triorun

tests/devx/conftest.py

@@ -1,253 +0,0 @@
-'''
-`tractor.devx.*` tooling sub-pkg test space.
-
-'''
-from __future__ import annotations
-import time
-from typing import (
-    Callable,
-    TYPE_CHECKING,
-)
-
-import pytest
-from pexpect.exceptions import (
-    TIMEOUT,
-)
-from pexpect.spawnbase import SpawnBase
-
-from tractor._testing import (
-    mk_cmd,
-)
-from tractor.devx.debug import (
-    _pause_msg as _pause_msg,
-    _crash_msg as _crash_msg,
-    _repl_fail_msg as _repl_fail_msg,
-    _ctlc_ignore_header as _ctlc_ignore_header,
-)
-from ..conftest import (
-    _ci_env,
-)
-
-if TYPE_CHECKING:
-    from pexpect import pty_spawn
-
-
-# a fn that sub-instantiates a `pexpect.spawn()`
-# and returns it.
-type PexpectSpawner = Callable[[str], pty_spawn.spawn]
-
-
-@pytest.fixture
-def spawn(
-    start_method: str,
-    testdir: pytest.Pytester,
-    reg_addr: tuple[str, int],
-
-) -> PexpectSpawner:
-    '''
-    Use the `pexpect` module shipped via `testdir.spawn()` to
-    run an `./examples/..` script by name.
-
-    '''
-    if start_method != 'trio':
-        pytest.skip(
-            '`pexpect` based tests only supported on `trio` backend'
-        )
-
-    def unset_colors():
-        '''
-        Python 3.13 introduced colored tracebacks that break patt
-        matching,
-
-        https://docs.python.org/3/using/cmdline.html#envvar-PYTHON_COLORS
-        https://docs.python.org/3/using/cmdline.html#using-on-controlling-color
-
-        '''
-        import os
-        os.environ['PYTHON_COLORS'] = '0'
-
-    def _spawn(
-        cmd: str,
-        **mkcmd_kwargs,
-    ) -> pty_spawn.spawn:
-        unset_colors()
-        return testdir.spawn(
-            cmd=mk_cmd(
-                cmd,
-                **mkcmd_kwargs,
-            ),
-            expect_timeout=3,
-            # preexec_fn=unset_colors,
-            # ^TODO? get `pytest` core to expose underlying
-            # `pexpect.spawn()` stuff?
-        )
-
-    # such that test-dep can pass input script name.
-    return _spawn  # the `PexpectSpawner`, type alias.
-
-
-@pytest.fixture(
-    params=[False, True],
-    ids='ctl-c={}'.format,
-)
-def ctlc(
-    request,
-    ci_env: bool,
-
-) -> bool:
-
-    use_ctlc = request.param
-
-    node = request.node
-    markers = node.own_markers
-    for mark in markers:
-        if mark.name == 'has_nested_actors':
-            pytest.skip(
-                f'Test {node} has nested actors and fails with Ctrl-C.\n'
-                f'The test can sometimes run fine locally but until'
-                ' we solve' 'this issue this CI test will be xfail:\n'
-                'https://github.com/goodboy/tractor/issues/320'
-            )
-
-        if mark.name == 'ctlcs_bish':
-            pytest.skip(
-                f'Test {node} prolly uses something from the stdlib (namely `asyncio`..)\n'
-                f'The test and/or underlying example script can *sometimes* run fine '
-                f'locally but more then likely until the cpython peeps get their sh#$ together, '
-                f'this test will definitely not behave like `trio` under SIGINT..\n'
-            )
-
-    if use_ctlc:
-        # XXX: disable pygments highlighting for auto-tests
-        # since some envs (like actions CI) will struggle
-        # the the added color-char encoding..
-        from tractor.devx.debug import TractorConfig
-        TractorConfig.use_pygements = False
-
-    yield use_ctlc
-
-
-def expect(
-    child,
-
-    # normally a `pdb` prompt by default
-    patt: str,
-
-    **kwargs,
-
-) -> None:
-    '''
-    Expect wrapper that prints last seen console
-    data before failing.
-
-    '''
-    try:
-        child.expect(
-            patt,
-            **kwargs,
-        )
-    except TIMEOUT:
-        before = str(child.before.decode())
-        print(before)
-        raise
-
-
-PROMPT = r"\(Pdb\+\)"
-
-
-def in_prompt_msg(
-    child: SpawnBase,
-    parts: list[str],
-
-    pause_on_false: bool = False,
-    err_on_false: bool = False,
-    print_prompt_on_false: bool = True,
-
-) -> bool:
-    '''
-    Predicate check if (the prompt's) std-streams output has all
-    `str`-parts in it.
-
-    Can be used in test asserts for bulk matching expected
-    log/REPL output for a given `pdb` interact point.
-
-    '''
-    __tracebackhide__: bool = False
-
-    before: str = str(child.before.decode())
-    for part in parts:
-        if part not in before:
-            if pause_on_false:
-                import pdbp
-                pdbp.set_trace()
-
-            if print_prompt_on_false:
-                print(before)
-
-            if err_on_false:
-                raise ValueError(
-                    f'Could not find pattern in `before` output?\n'
-                    f'part: {part!r}\n'
-                )
-            return False
-
-    return True
-
-
-# TODO: todo support terminal color-chars stripping so we can match
-# against call stack frame output from the the 'll' command the like!
-# -[ ] SO answer for stipping ANSI codes: https://stackoverflow.com/a/14693789
-def assert_before(
-    child: SpawnBase,
-    patts: list[str],
-
-    **kwargs,
-
-) -> None:
-    __tracebackhide__: bool = False
-
-    assert in_prompt_msg(
-        child=child,
-        parts=patts,
-
-        # since this is an "assert" helper ;)
-        err_on_false=True,
-        **kwargs
-    )
-
-
-def do_ctlc(
-    child,
-    count: int = 3,
-    delay: float = 0.1,
-    patt: str|None = None,
-
-    # expect repl UX to reprint the prompt after every
-    # ctrl-c send.
-    # XXX: no idea but, in CI this never seems to work even on 3.10 so
-    # needs some further investigation potentially...
-    expect_prompt: bool = not _ci_env,
-
-) -> str|None:
-
-    before: str|None = None
-
-    # make sure ctl-c sends don't do anything but repeat output
-    for _ in range(count):
-        time.sleep(delay)
-        child.sendcontrol('c')
-
-        # TODO: figure out why this makes CI fail..
-        # if you run this test manually it works just fine..
-        if expect_prompt:
-            time.sleep(delay)
-            child.expect(PROMPT)
-            before = str(child.before.decode())
-            time.sleep(delay)
-
-            if patt:
-                # should see the last line on console
-                assert patt in before
-
-    # return the console content up to the final prompt
-    return before

tests/devx/test_pause_from_non_trio.py

@@ -1,381 +0,0 @@
-'''
-That "foreign loop/thread" debug REPL support better ALSO WORK!
-
-Same as `test_native_pause.py`.
-All these tests can be understood (somewhat) by running the
-equivalent `examples/debugging/` scripts manually.
-
-'''
-from contextlib import (
-    contextmanager as cm,
-)
-# from functools import partial
-# import itertools
-import time
-# from typing import (
-#     Iterator,
-# )
-
-import pytest
-from pexpect.exceptions import (
-    TIMEOUT,
-    EOF,
-)
-
-from .conftest import (
-    # _ci_env,
-    do_ctlc,
-    PROMPT,
-    # expect,
-    in_prompt_msg,
-    assert_before,
-    _pause_msg,
-    _crash_msg,
-    _ctlc_ignore_header,
-    # _repl_fail_msg,
-)
-
-@cm
-def maybe_expect_timeout(
-    ctlc: bool = False,
-) -> None:
-    try:
-        yield
-    except TIMEOUT:
-        # breakpoint()
-        if ctlc:
-            pytest.xfail(
-                'Some kinda redic threading SIGINT bug i think?\n'
-                'See the notes in `examples/debugging/sync_bp.py`..\n'
-            )
-        raise
-
-
-@pytest.mark.ctlcs_bish
-def test_pause_from_sync(
-    spawn,
-    ctlc: bool,
-):
-    '''
-    Verify we can use the `pdbp` REPL from sync functions AND from
-    any thread spawned with `trio.to_thread.run_sync()`.
-
-    `examples/debugging/sync_bp.py`
-
-    '''
-    child = spawn('sync_bp')
-
-    # first `sync_pause()` after nurseries open
-    child.expect(PROMPT)
-    assert_before(
-        child,
-        [
-            # pre-prompt line
-            _pause_msg,
-            "<Task '__main__.main'",
-            "('root'",
-        ]
-    )
-    if ctlc:
-        do_ctlc(child)
-        # ^NOTE^ subactor not spawned yet; don't need extra delay.
-
-    child.sendline('c')
-
-    # first `await tractor.pause()` inside `p.open_context()` body
-    child.expect(PROMPT)
-
-    # XXX shouldn't see gb loaded message with PDB loglevel!
-    # assert not in_prompt_msg(
-    #     child,
-    #     ['`greenback` portal opened!'],
-    # )
-    # should be same root task
-    assert_before(
-        child,
-        [
-            _pause_msg,
-            "<Task '__main__.main'",
-            "('root'",
-        ]
-    )
-
-    if ctlc:
-        do_ctlc(
-            child,
-            # NOTE: setting this to 0 (or some other sufficient
-            # small val) can cause the test to fail since the
-            # `subactor` suffers a race where the root/parent
-            # sends an actor-cancel prior to it hitting its pause
-            # point; by def the value is 0.1
-            delay=0.4,
-        )
-
-    # XXX, fwiw without a brief sleep here the SIGINT might actually
-    # trigger "subactor" cancellation by its parent  before the
-    # shield-handler is engaged.
-    #
-    # => similar to the `delay` input to `do_ctlc()` below, setting
-    # this too low can cause the test to fail since the `subactor`
-    # suffers a race where the root/parent sends an actor-cancel
-    # prior to the context task hitting its pause point (and thus
-    # engaging the `sigint_shield()` handler in time); this value
-    # seems be good enuf?
-    time.sleep(0.6)
-
-    # one of the bg thread or subactor should have
-    # `Lock.acquire()`-ed
-    # (NOT both, which will result in REPL clobbering!)
-    attach_patts: dict[str, list[str]] = {
-        'subactor': [
-            "'start_n_sync_pause'",
-            "('subactor'",
-        ],
-        'inline_root_bg_thread': [
-            "<Thread(inline_root_bg_thread",
-            "('root'",
-        ],
-        'start_soon_root_bg_thread': [
-            "<Thread(start_soon_root_bg_thread",
-            "('root'",
-        ],
-    }
-    conts: int = 0  # for debugging below matching logic on failure
-    while attach_patts:
-        child.sendline('c')
-        conts += 1
-        child.expect(PROMPT)
-        before = str(child.before.decode())
-        for key in attach_patts:
-            if key in before:
-                attach_key: str = key
-                expected_patts: str = attach_patts.pop(key)
-                assert_before(
-                    child,
-                    [_pause_msg]
-                    +
-                    expected_patts
-                )
-                break
-        else:
-            pytest.fail(
-                f'No keys found?\n\n'
-                f'{attach_patts.keys()}\n\n'
-                f'{before}\n'
-            )
-
-        # ensure no other task/threads engaged a REPL
-        # at the same time as the one that was detected above.
-        for key, other_patts in attach_patts.copy().items():
-            assert not in_prompt_msg(
-                child,
-                other_patts,
-            )
-
-        if ctlc:
-            do_ctlc(
-                child,
-                patt=attach_key,
-                # NOTE same as comment above
-                delay=0.4,
-            )
-
-    child.sendline('c')
-
-    # XXX TODO, weird threading bug it seems despite the
-    # `abandon_on_cancel: bool` setting to
-    # `trio.to_thread.run_sync()`..
-    with maybe_expect_timeout(
-        ctlc=ctlc,
-    ):
-        child.expect(EOF)
-
-
-def expect_any_of(
-    attach_patts: dict[str, list[str]],
-    child,   # what type?
-    ctlc: bool = False,
-    prompt: str = _ctlc_ignore_header,
-    ctlc_delay: float = .4,
-
-) -> list[str]:
-    '''
-    Receive any of a `list[str]` of patterns provided in
-    `attach_patts`.
-
-    Used to test racing prompts from multiple actors and/or
-    tasks using a common root process' `pdbp` REPL.
-
-    '''
-    assert attach_patts
-
-    child.expect(PROMPT)
-    before = str(child.before.decode())
-
-    for attach_key in attach_patts:
-        if attach_key in before:
-            expected_patts: str = attach_patts.pop(attach_key)
-            assert_before(
-                child,
-                expected_patts
-            )
-            break  # from for
-    else:
-        pytest.fail(
-            f'No keys found?\n\n'
-            f'{attach_patts.keys()}\n\n'
-            f'{before}\n'
-        )
-
-    # ensure no other task/threads engaged a REPL
-    # at the same time as the one that was detected above.
-    for key, other_patts in attach_patts.copy().items():
-        assert not in_prompt_msg(
-            child,
-            other_patts,
-        )
-
-    if ctlc:
-        do_ctlc(
-            child,
-            patt=prompt,
-            # NOTE same as comment above
-            delay=ctlc_delay,
-        )
-
-    return expected_patts
-
-
-@pytest.mark.ctlcs_bish
-def test_sync_pause_from_aio_task(
-    spawn,
-
-    ctlc: bool
-    # ^TODO, fix for `asyncio`!!
-):
-    '''
-    Verify we can use the `pdbp` REPL from an `asyncio.Task` spawned using
-    APIs in `.to_asyncio`.
-
-    `examples/debugging/asycio_bp.py`
-
-    '''
-    child = spawn('asyncio_bp')
-
-    # RACE on whether trio/asyncio task bps first
-    attach_patts: dict[str, list[str]] = {
-
-        # first pause in guest-mode (aka "infecting")
-        # `trio.Task`.
-        'trio-side': [
-            _pause_msg,
-            "<Task 'trio_ctx'",
-            "('aio_daemon'",
-        ],
-
-        # `breakpoint()` from `asyncio.Task`.
-        'asyncio-side': [
-            _pause_msg,
-            "<Task pending name='Task-2' coro=<greenback_shim()",
-            "('aio_daemon'",
-        ],
-    }
-
-    while attach_patts:
-        expect_any_of(
-            attach_patts=attach_patts,
-            child=child,
-            ctlc=ctlc,
-        )
-        child.sendline('c')
-
-    # NOW in race order,
-    # - the asyncio-task will error
-    # - the root-actor parent task will pause
-    #
-    attach_patts: dict[str, list[str]] = {
-
-        # error raised in `asyncio.Task`
-        "raise ValueError('asyncio side error!')": [
-            _crash_msg,
-            "<Task 'trio_ctx'",
-            "@ ('aio_daemon'",
-            "ValueError: asyncio side error!",
-
-            # XXX, we no longer show this frame by default!
-            # 'return await chan.receive()',  # `.to_asyncio` impl internals in tb
-        ],
-
-        # parent-side propagation via actor-nursery/portal
-        # "tractor._exceptions.RemoteActorError: remote task raised a 'ValueError'": [
-        "remote task raised a 'ValueError'": [
-            _crash_msg,
-            "src_uid=('aio_daemon'",
-            "('aio_daemon'",
-        ],
-
-        # a final pause in root-actor
-        "<Task '__main__.main'": [
-            _pause_msg,
-            "<Task '__main__.main'",
-            "('root'",
-        ],
-    }
-    while attach_patts:
-        expect_any_of(
-            attach_patts=attach_patts,
-            child=child,
-            ctlc=ctlc,
-        )
-        child.sendline('c')
-
-    assert not attach_patts
-
-    # final boxed error propagates to root
-    assert_before(
-        child,
-        [
-            _crash_msg,
-            "<Task '__main__.main'",
-            "('root'",
-            "remote task raised a 'ValueError'",
-            "ValueError: asyncio side error!",
-        ]
-    )
-
-    if ctlc:
-        do_ctlc(
-            child,
-            # NOTE: setting this to 0 (or some other sufficient
-            # small val) can cause the test to fail since the
-            # `subactor` suffers a race where the root/parent
-            # sends an actor-cancel prior to it hitting its pause
-            # point; by def the value is 0.1
-            delay=0.4,
-        )
-
-    child.sendline('c')
-    # with maybe_expect_timeout():
-    child.expect(EOF)
-
-
-def test_sync_pause_from_non_greenbacked_aio_task():
-    '''
-    Where the `breakpoint()` caller task is NOT spawned by
-    `tractor.to_asyncio` and thus never activates
-    a `greenback.ensure_portal()` beforehand, presumably bc the task
-    was started by some lib/dep as in often seen in the field.
-
-    Ensure sync pausing works when the pause is in,
-
-    - the root actor running in infected-mode?
-      |_ since we don't need any IPC to acquire the debug lock?
-      |_ is there some way to handle this like the non-main-thread case?
-
-    All other cases need to error out appropriately right?
-
-    - for any subactor we can't avoid needing the repl lock..
-      |_ is there a way to hook into `asyncio.ensure_future(obj)`?
-
-    '''
-    pass

tests/devx/test_tooling.py

@@ -1,304 +0,0 @@
-'''
-That "native" runtime-hackin toolset better be dang useful!
-
-Verify the funtion of a variety of "developer-experience" tools we
-offer from the `.devx` sub-pkg:
-
-- use of the lovely `stackscope` for dumping actor `trio`-task trees
-  during operation and hangs.
-
-TODO:
-- demonstration of `CallerInfo` call stack frame filtering such that
-  for logging and REPL purposes a user sees exactly the layers needed
-  when debugging a problem inside the stack vs. in their app.
-
-'''
-from __future__ import annotations
-from contextlib import (
-    contextmanager as cm,
-)
-import os
-import signal
-import time
-from typing import (
-    TYPE_CHECKING,
-)
-
-from .conftest import (
-    expect,
-    assert_before,
-    in_prompt_msg,
-    PROMPT,
-    _pause_msg,
-)
-
-import pytest
-from pexpect.exceptions import (
-    # TIMEOUT,
-    EOF,
-)
-
-if TYPE_CHECKING:
-    from ..conftest import PexpectSpawner
-
-
-def test_shield_pause(
-    spawn: PexpectSpawner,
-):
-    '''
-    Verify the `tractor.pause()/.post_mortem()` API works inside an
-    already cancelled `trio.CancelScope` and that you can step to the
-    next checkpoint wherein the cancelled will get raised.
-
-    '''
-    child = spawn(
-        'shield_hang_in_sub'
-    )
-    expect(
-        child,
-        'Yo my child hanging..?',
-    )
-    assert_before(
-        child,
-        [
-            'Entering shield sleep..',
-            'Enabling trace-trees on `SIGUSR1` since `stackscope` is installed @',
-        ]
-    )
-
-    script_pid: int = child.pid
-    print(
-        f'Sending SIGUSR1 to {script_pid}\n'
-        f'(kill -s SIGUSR1 {script_pid})\n'
-    )
-    os.kill(
-        script_pid,
-        signal.SIGUSR1,
-    )
-    time.sleep(0.2)
-    expect(
-        child,
-        # end-of-tree delimiter
-        "end-of-\('root'",
-    )
-    assert_before(
-        child,
-        [
-            # 'Srying to dump `stackscope` tree..',
-            # 'Dumping `stackscope` tree for actor',
-            "('root'",  # uid line
-
-            # TODO!? this used to show?
-            # -[ ] mk reproducable for @oremanj?
-            #
-            # parent block point (non-shielded)
-            # 'await trio.sleep_forever()  # in root',
-        ]
-    )
-    expect(
-        child,
-        # end-of-tree delimiter
-        "end-of-\('hanger'",
-    )
-    assert_before(
-        child,
-        [
-            # relay to the sub should be reported
-            'Relaying `SIGUSR1`[10] to sub-actor',
-
-            "('hanger'",  # uid line
-
-            # TODO!? SEE ABOVE
-            # hanger LOC where it's shield-halted
-            # 'await trio.sleep_forever()  # in subactor',
-        ]
-    )
-
-    # simulate the user sending a ctl-c to the hanging program.
-    # this should result in the terminator kicking in since
-    # the sub is shield blocking and can't respond to SIGINT.
-    os.kill(
-        child.pid,
-        signal.SIGINT,
-    )
-    expect(
-        child,
-        'Shutting down actor runtime',
-        timeout=6,
-    )
-    assert_before(
-        child,
-        [
-            'raise KeyboardInterrupt',
-            # 'Shutting down actor runtime',
-            '#T-800 deployed to collect zombie B0',
-            "'--uid', \"('hanger',",
-        ]
-    )
-
-
-def test_breakpoint_hook_restored(
-    spawn: PexpectSpawner,
-):
-    '''
-    Ensures our actor runtime sets a custom `breakpoint()` hook
-    on open then restores the stdlib's default on close.
-
-    The hook state validation is done via `assert`s inside the
-    invoked script with only `breakpoint()` (not `tractor.pause()`)
-    calls used.
-
-    '''
-    child = spawn('restore_builtin_breakpoint')
-
-    child.expect(PROMPT)
-    try:
-        assert_before(
-            child,
-            [
-                _pause_msg,
-                "<Task '__main__.main'",
-                "('root'",
-                "first bp, tractor hook set",
-            ]
-        )
-    # XXX if the above raises `AssertionError`, without sending
-    # the final 'continue' cmd to the REPL-active sub-process,
-    # we'll hang waiting for that pexpect instance to terminate..
-    finally:
-        child.sendline('c')
-
-    child.expect(PROMPT)
-    assert_before(
-        child,
-        [
-            "last bp, stdlib hook restored",
-        ]
-    )
-
-    # since the stdlib hook was already restored there should be NO
-    # `tractor` `log.pdb()` content from console!
-    assert not in_prompt_msg(
-        child,
-        [
-            _pause_msg,
-            "<Task '__main__.main'",
-            "('root'",
-        ],
-    )
-    child.sendline('c')
-    child.expect(EOF)
-
-
-
-_to_raise = Exception('Triggering a crash')
-
-
-@pytest.mark.parametrize(
-    'to_raise',
-    [
-        None,
-        _to_raise,
-        RuntimeError('Never crash handle this!'),
-    ],
-)
-@pytest.mark.parametrize(
-    'raise_on_exit',
-    [
-        True,
-        [type(_to_raise)],
-        False,
-    ]
-)
-def test_crash_handler_cms(
-    debug_mode: bool,
-    to_raise: Exception,
-    raise_on_exit: bool|list[Exception],
-):
-    '''
-    Verify the `.devx.open_crash_handler()` API(s) by also
-    (conveniently enough) tesing its `repl_fixture: ContextManager`
-    param support which for this suite allows use to avoid use of
-    a `pexpect`-style-test since we use the fixture to avoid actually
-    entering `PdbpREPL.iteract()` :smirk:
-
-    '''
-    import tractor
-    # import trio
-
-    # state flags
-    repl_acquired: bool = False
-    repl_released: bool = False
-
-    @cm
-    def block_repl_ux(
-        repl: tractor.devx.debug.PdbREPL,
-        maybe_bxerr: (
-            tractor.devx._debug.BoxedMaybeException
-            |None
-        ) = None,
-        enter_repl: bool = True,
-
-    ) -> bool:
-        '''
-        Set pre/post-REPL state vars and bypass actual conole
-        interaction.
-
-        '''
-        nonlocal repl_acquired, repl_released
-
-        # task: trio.Task = trio.lowlevel.current_task()
-        # print(f'pre-REPL active_task={task.name}')
-
-        print('pre-REPL')
-        repl_acquired = True
-        yield False  # never actually .interact()
-        print('post-REPL')
-        repl_released = True
-
-    try:
-        # TODO, with runtime's `debug_mode` setting
-        # -[ ] need to open runtime tho obvi..
-        #
-        # with tractor.devx.maybe_open_crash_handler(
-        #     pdb=True,
-
-        with tractor.devx.open_crash_handler(
-            raise_on_exit=raise_on_exit,
-            repl_fixture=block_repl_ux
-        ) as bxerr:
-            if to_raise is not None:
-                raise to_raise
-
-    except Exception as _exc:
-        exc = _exc
-        if (
-            raise_on_exit is True
-            or
-            type(to_raise) in raise_on_exit
-        ):
-            assert (
-                exc
-                is
-                to_raise
-                is
-                bxerr.value
-            )
-
-        else:
-            raise
-    else:
-        assert (
-            to_raise is None
-            or
-            not raise_on_exit
-            or
-            type(to_raise) not in raise_on_exit
-        )
-        assert bxerr.value is to_raise
-
-    assert bxerr.raise_on_exit == raise_on_exit
-
-    if to_raise is not None:
-        assert repl_acquired
-        assert repl_released

tests/ipc/__init__.py

@@ -1,4 +0,0 @@
-'''
-`tractor.ipc` subsystem(s)/unit testing suites.
-
-'''

tests/ipc/test_multi_tpt.py

@@ -1,95 +0,0 @@
-'''
-Verify the `enable_transports` param drives various
-per-root/sub-actor IPC endpoint/server settings.
-
-'''
-from __future__ import annotations
-
-import pytest
-import trio
-import tractor
-from tractor import (
-    Actor,
-    Portal,
-    ipc,
-    msg,
-    _state,
-    _addr,
-)
-
-@tractor.context
-async def chk_tpts(
-    ctx: tractor.Context,
-    tpt_proto_key: str,
-):
-    rtvars = _state._runtime_vars
-    assert (
-        tpt_proto_key
-        in
-        rtvars['_enable_tpts']
-    )
-    actor: Actor = tractor.current_actor()
-    spec: msg.types.SpawnSpec = actor._spawn_spec
-    assert spec._runtime_vars == rtvars
-
-    # ensure individual IPC ep-addr types
-    serv: ipc._server.Server = actor.ipc_server
-    addr: ipc._types.Address
-    for addr in serv.addrs:
-        assert addr.proto_key == tpt_proto_key
-
-    # Actor delegate-props enforcement
-    assert (
-        actor.accept_addrs
-        ==
-        serv.accept_addrs
-    )
-
-    await ctx.started(serv.accept_addrs)
-
-
-# TODO, parametrize over mis-matched-proto-typed `registry_addrs`
-# since i seems to work in `piker` but not exactly sure if both tcp
-# & uds are being deployed then?
-#
-@pytest.mark.parametrize(
-    'tpt_proto_key',
-    ['tcp', 'uds'],
-    ids=lambda item: f'ipc_tpt={item!r}'
-)
-def test_root_passes_tpt_to_sub(
-    tpt_proto_key: str,
-    reg_addr: tuple,
-    debug_mode: bool,
-):
-    async def main():
-        async with tractor.open_nursery(
-            enable_transports=[tpt_proto_key],
-            registry_addrs=[reg_addr],
-            debug_mode=debug_mode,
-        ) as an:
-
-            assert (
-                tpt_proto_key
-                in
-                _state._runtime_vars['_enable_tpts']
-            )
-
-            ptl: Portal = await an.start_actor(
-                name='sub',
-                enable_modules=[__name__],
-            )
-            async with ptl.open_context(
-                chk_tpts,
-                tpt_proto_key=tpt_proto_key,
-            ) as (ctx, accept_addrs):
-
-                uw_addr: tuple
-                for uw_addr in accept_addrs:
-                    addr = _addr.wrap_address(uw_addr)
-                    assert addr.is_valid
-
-            # shudown sub-actor(s)
-            await an.cancel()
-
-    trio.run(main)

tests/ipc/test_server.py

@@ -1,72 +0,0 @@
-'''
-High-level `.ipc._server` unit tests.
-
-'''
-from __future__ import annotations
-
-import pytest
-import trio
-from tractor import (
-    devx,
-    ipc,
-    log,
-)
-from tractor._testing.addr import (
-    get_rando_addr,
-)
-# TODO, use/check-roundtripping with some of these wrapper types?
-#
-# from .._addr import Address
-# from ._chan import Channel
-# from ._transport import MsgTransport
-# from ._uds import UDSAddress
-# from ._tcp import TCPAddress
-
-
-@pytest.mark.parametrize(
-    '_tpt_proto',
-    ['uds', 'tcp']
-)
-def test_basic_ipc_server(
-    _tpt_proto: str,
-    debug_mode: bool,
-    loglevel: str,
-):
-
-    # so we see the socket-listener reporting on console
-    log.get_console_log("INFO")
-
-    rando_addr: tuple = get_rando_addr(
-        tpt_proto=_tpt_proto,
-    )
-    async def main():
-        async with ipc._server.open_ipc_server() as server:
-
-            assert (
-                server._parent_tn
-                and
-                server._parent_tn is server._stream_handler_tn
-            )
-            assert server._no_more_peers.is_set()
-
-            eps: list[ipc._server.Endpoint] = await server.listen_on(
-                accept_addrs=[rando_addr],
-                stream_handler_nursery=None,
-            )
-            assert (
-                len(eps) == 1
-                and
-                (ep := eps[0])._listener
-                and
-                not ep.peer_tpts
-            )
-
-            server._parent_tn.cancel_scope.cancel()
-
-        # !TODO! actually make a bg-task connection from a client
-        # using `ipc._chan._connect_chan()`
-
-    with devx.maybe_open_crash_handler(
-        pdb=debug_mode,
-    ):
-        trio.run(main)

tests/test_advanced_faults.py

@@ -3,6 +3,7 @@ Sketchy network blackoutz, ugly byzantine gens, puedes eschuchar la
 cancelacion?..
 
 '''
+import itertools
 from functools import partial
 from types import ModuleType
 
@@ -10,12 +11,8 @@ import pytest
 from _pytest.pathlib import import_path
 import trio
 import tractor
-from tractor import (
-    TransportClosed,
-)
 from tractor._testing import (
     examples_dir,
-    break_ipc,
 )
 
 
@@ -77,7 +74,6 @@ def test_ipc_channel_break_during_stream(
     spawn_backend: str,
     ipc_break: dict|None,
     pre_aclose_msgstream: bool,
-    tpt_proto: str,
 ):
     '''
     Ensure we can have an IPC channel break its connection during
@@ -94,12 +90,10 @@ def test_ipc_channel_break_during_stream(
 
         # non-`trio` spawners should never hit the hang condition that
         # requires the user to do ctl-c to cancel the actor tree.
-        # expect_final_exc = trio.ClosedResourceError
-        expect_final_exc = TransportClosed
+        expect_final_exc = trio.ClosedResourceError
 
     mod: ModuleType = import_path(
-        examples_dir() / 'advanced_faults'
-        / 'ipc_failure_during_stream.py',
+        examples_dir() / 'advanced_faults' / 'ipc_failure_during_stream.py',
         root=examples_dir(),
         consider_namespace_packages=False,
     )
@@ -108,8 +102,6 @@ def test_ipc_channel_break_during_stream(
     # period" wherein the user eventually hits ctl-c to kill the
     # root-actor tree.
     expect_final_exc: BaseException = KeyboardInterrupt
-    expect_final_cause: BaseException|None = None
-
     if (
         # only expect EoC if trans is broken on the child side,
         ipc_break['break_child_ipc_after'] is not False
@@ -144,9 +136,6 @@ def test_ipc_channel_break_during_stream(
         # a user sending ctl-c by raising a KBI.
         if pre_aclose_msgstream:
             expect_final_exc = KeyboardInterrupt
-            if tpt_proto == 'uds':
-                expect_final_exc = TransportClosed
-                expect_final_cause = trio.BrokenResourceError
 
             # XXX OLD XXX
             # if child calls `MsgStream.aclose()` then expect EoC.
@@ -166,11 +155,7 @@ def test_ipc_channel_break_during_stream(
         if pre_aclose_msgstream:
             expect_final_exc = KeyboardInterrupt
 
-            if tpt_proto == 'uds':
-                expect_final_exc = TransportClosed
-                expect_final_cause = trio.BrokenResourceError
-
-    # NOTE when the parent IPC side dies (even if the child does as well
+    # NOTE when the parent IPC side dies (even if the child's does as well
     # but the child fails BEFORE the parent) we always expect the
     # IPC layer to raise a closed-resource, NEVER do we expect
     # a stop msg since the parent-side ctx apis will error out
@@ -182,8 +167,7 @@ def test_ipc_channel_break_during_stream(
         and
         ipc_break['break_child_ipc_after'] is False
     ):
-        expect_final_exc = tractor.TransportClosed
-        expect_final_cause = trio.ClosedResourceError
+        expect_final_exc = trio.ClosedResourceError
 
     # BOTH but, PARENT breaks FIRST
     elif (
@@ -194,8 +178,7 @@ def test_ipc_channel_break_during_stream(
             ipc_break['break_parent_ipc_after']
         )
     ):
-        expect_final_exc = tractor.TransportClosed
-        expect_final_cause = trio.ClosedResourceError
+        expect_final_exc = trio.ClosedResourceError
 
     with pytest.raises(
         expected_exception=(
@@ -211,12 +194,11 @@ def test_ipc_channel_break_during_stream(
                     start_method=spawn_backend,
                     loglevel=loglevel,
                     pre_close=pre_aclose_msgstream,
-                    tpt_proto=tpt_proto,
                     **ipc_break,
                 )
             )
-        except KeyboardInterrupt as _kbi:
-            kbi = _kbi
+        except KeyboardInterrupt as kbi:
+            _err = kbi
             if expect_final_exc is not KeyboardInterrupt:
                 pytest.fail(
                     'Rxed unexpected KBI !?\n'
@@ -225,33 +207,16 @@ def test_ipc_channel_break_during_stream(
 
             raise
 
-        except tractor.TransportClosed as _tc:
-            tc = _tc
-            if expect_final_exc is KeyboardInterrupt:
-                pytest.fail(
-                    'Unexpected transport failure !?\n'
-                    f'{repr(tc)}'
-                )
-            cause: Exception = tc.__cause__
-            assert (
-                # type(cause) is trio.ClosedResourceError
-                type(cause) is expect_final_cause
-
-                # TODO, should we expect a certain exc-message (per
-                # tpt) as well??
-                # and
-                # cause.args[0] == 'another task closed this fd'
-            )
-
-            raise
-
     # get raw instance from pytest wrapper
     value = excinfo.value
     if isinstance(value, ExceptionGroup):
-        excs = value.exceptions
-        assert len(excs) == 1
-        final_exc = excs[0]
-        assert isinstance(final_exc, expect_final_exc)
+        value = next(
+            itertools.dropwhile(
+                lambda exc: not isinstance(exc, expect_final_exc),
+                value.exceptions,
+            )
+        )
+        assert value
 
 
 @tractor.context
@@ -260,30 +225,23 @@ async def break_ipc_after_started(
 ) -> None:
     await ctx.started()
     async with ctx.open_stream() as stream:
-
-        # TODO: make a test which verifies the error
-        # for this, i.e. raises a `MsgTypeError`
-        # await ctx.chan.send(None)
-
-        await break_ipc(
-            stream=stream,
-            pre_close=True,
-        )
+        await stream.aclose()
+        await trio.sleep(0.2)
+        await ctx.chan.send(None)
         print('child broke IPC and terminating')
 
 
 def test_stream_closed_right_after_ipc_break_and_zombie_lord_engages():
     '''
-    Verify that is a subactor's IPC goes down just after bringing up
-    a stream the parent can trigger a SIGINT and the child will be
-    reaped out-of-IPC by the localhost process supervision machinery:
-    aka "zombie lord".
+    Verify that is a subactor's IPC goes down just after bringing up a stream
+    the parent can trigger a SIGINT and the child will be reaped out-of-IPC by
+    the localhost process supervision machinery: aka "zombie lord".
 
     '''
     async def main():
         with trio.fail_after(3):
-            async with tractor.open_nursery() as an:
-                portal = await an.start_actor(
+            async with tractor.open_nursery() as n:
+                portal = await n.start_actor(
                     'ipc_breaker',
                     enable_modules=[__name__],
                 )

tests/test_advanced_streaming.py

@@ -307,15 +307,7 @@ async def inf_streamer(
 
     async with (
         ctx.open_stream() as stream,
-
-        # XXX TODO, INTERESTING CASE!!
-        # - if we don't collapse the eg then the embedded
-        # `trio.EndOfChannel` doesn't propagate directly to the above
-        # .open_stream() parent, resulting in it also raising instead
-        # of gracefully absorbing as normal.. so how to handle?
-        trio.open_nursery(
-            strict_exception_groups=False,
-        ) as tn,
+        trio.open_nursery() as tn,
     ):
         async def close_stream_on_sentinel():
             async for msg in stream:

tests/test_cancellation.py

@@ -89,30 +89,17 @@ def test_remote_error(reg_addr, args_err):
         assert excinfo.value.boxed_type == errtype
 
     else:
-        # the root task will also error on the `Portal.result()`
-        # call so we expect an error from there AND the child.
-        # |_ tho seems like on new `trio` this doesn't always
-        #    happen?
-        with pytest.raises((
-            BaseExceptionGroup,
-            tractor.RemoteActorError,
-        )) as excinfo:
+        # the root task will also error on the `.result()` call
+        # so we expect an error from there AND the child.
+        with pytest.raises(BaseExceptionGroup) as excinfo:
             trio.run(main)
 
-        # ensure boxed errors are `errtype`
-        err: BaseException = excinfo.value
-        if isinstance(err, BaseExceptionGroup):
-            suberrs: list[BaseException] = err.exceptions
-        else:
-            suberrs: list[BaseException] = [err]
-
-        for exc in suberrs:
+        # ensure boxed errors
+        for exc in excinfo.value.exceptions:
             assert exc.boxed_type == errtype
 
 
-def test_multierror(
-    reg_addr: tuple[str, int],
-):
+def test_multierror(reg_addr):
     '''
     Verify we raise a ``BaseExceptionGroup`` out of a nursery where
     more then one actor errors.
@@ -130,7 +117,7 @@ def test_multierror(
             try:
                 await portal2.result()
             except tractor.RemoteActorError as err:
-                assert err.boxed_type is AssertionError
+                assert err.boxed_type == AssertionError
                 print("Look Maa that first actor failed hard, hehh")
                 raise
 
@@ -182,7 +169,7 @@ def test_multierror_fast_nursery(reg_addr, start_method, num_subactors, delay):
 
     for exc in exceptions:
         assert isinstance(exc, tractor.RemoteActorError)
-        assert exc.boxed_type is AssertionError
+        assert exc.boxed_type == AssertionError
 
 
 async def do_nothing():
@@ -504,9 +491,7 @@ def test_cancel_via_SIGINT_other_task(
     if is_win():  # smh
         timeout += 1
 
-    async def spawn_and_sleep_forever(
-        task_status=trio.TASK_STATUS_IGNORED
-    ):
+    async def spawn_and_sleep_forever(task_status=trio.TASK_STATUS_IGNORED):
         async with tractor.open_nursery() as tn:
             for i in range(3):
                 await tn.run_in_actor(
@@ -519,9 +504,7 @@ def test_cancel_via_SIGINT_other_task(
     async def main():
         # should never timeout since SIGINT should cancel the current program
         with trio.fail_after(timeout):
-            async with trio.open_nursery(
-                strict_exception_groups=False,
-            ) as n:
+            async with trio.open_nursery() as n:
                 await n.start(spawn_and_sleep_forever)
                 if 'mp' in spawn_backend:
                     time.sleep(0.1)
@@ -614,12 +597,6 @@ def test_fast_graceful_cancel_when_spawn_task_in_soft_proc_wait_for_daemon(
                     nurse.start_soon(delayed_kbi)
 
                     await p.run(do_nuthin)
-
-        # need to explicitly re-raise the lone kbi..now
-        except* KeyboardInterrupt as kbi_eg:
-            assert (len(excs := kbi_eg.exceptions) == 1)
-            raise excs[0]
-
         finally:
             duration = time.time() - start
             if duration > timeout:

tests/test_child_manages_service_nursery.py

@@ -95,8 +95,8 @@ async def trio_main(
 
     # stash a "service nursery" as "actor local" (aka a Python global)
     global _nursery
-    tn = _nursery
-    assert tn
+    n = _nursery
+    assert n
 
     async def consume_stream():
         async with wrapper_mngr() as stream:
@@ -104,10 +104,10 @@ async def trio_main(
                 print(msg)
 
     # run 2 tasks to ensure broadcaster chan use
-    tn.start_soon(consume_stream)
-    tn.start_soon(consume_stream)
+    n.start_soon(consume_stream)
+    n.start_soon(consume_stream)
 
-    tn.start_soon(trio_sleep_and_err)
+    n.start_soon(trio_sleep_and_err)
 
     await trio.sleep_forever()
 
@@ -117,10 +117,8 @@ async def open_actor_local_nursery(
     ctx: tractor.Context,
 ):
     global _nursery
-    async with trio.open_nursery(
-        strict_exception_groups=False,
-    ) as tn:
-        _nursery = tn
+    async with trio.open_nursery() as n:
+        _nursery = n
         await ctx.started()
         await trio.sleep(10)
         # await trio.sleep(1)
@@ -134,7 +132,7 @@ async def open_actor_local_nursery(
         # never yields back.. aka a scenario where the
         # ``tractor.context`` task IS NOT in the service n's cancel
         # scope.
-        tn.cancel_scope.cancel()
+        n.cancel_scope.cancel()
 
 
 @pytest.mark.parametrize(
@@ -159,7 +157,7 @@ def test_actor_managed_trio_nursery_task_error_cancels_aio(
         async with tractor.open_nursery() as n:
             p = await n.start_actor(
                 'nursery_mngr',
-                infect_asyncio=asyncio_mode,  # TODO, is this enabling debug mode?
+                infect_asyncio=asyncio_mode,
                 enable_modules=[__name__],
             )
             async with (

tests/test_context_stream_semantics.py

@@ -6,7 +6,6 @@ sync-opening a ``tractor.Context`` beforehand.
 
 '''
 from itertools import count
-import math
 import platform
 from pprint import pformat
 from typing import (
@@ -25,7 +24,6 @@ from tractor._exceptions import (
     StreamOverrun,
     ContextCancelled,
 )
-from tractor._state import current_ipc_ctx
 
 from tractor._testing import (
     tractor_test,
@@ -38,9 +36,9 @@ from tractor._testing import (
 # - standard setup/teardown:
 #   ``Portal.open_context()`` starts a new
 #   remote task context in another actor. The target actor's task must
-#   call ``Context.started()`` to unblock this entry on the parent side.
-#   the child task executes until complete and returns a final value
-#   which is delivered to the parent side and retreived via
+#   call ``Context.started()`` to unblock this entry on the caller side.
+#   the callee task executes until complete and returns a final value
+#   which is delivered to the caller side and retreived via
 #   ``Context.result()``.
 
 # - cancel termination:
@@ -145,8 +143,6 @@ async def simple_setup_teardown(
     global _state
     _state = True
 
-    assert current_ipc_ctx() is ctx
-
     # signal to parent that we're up
     await ctx.started(data + 1)
 
@@ -170,9 +166,9 @@ async def assert_state(value: bool):
     [False, ValueError, KeyboardInterrupt],
 )
 @pytest.mark.parametrize(
-    'child_blocks_forever',
+    'callee_blocks_forever',
     [False, True],
-    ids=lambda item: f'child_blocks_forever={item}'
+    ids=lambda item: f'callee_blocks_forever={item}'
 )
 @pytest.mark.parametrize(
     'pointlessly_open_stream',
@@ -181,7 +177,7 @@ async def assert_state(value: bool):
 )
 def test_simple_context(
     error_parent,
-    child_blocks_forever,
+    callee_blocks_forever,
     pointlessly_open_stream,
     debug_mode: bool,
 ):
@@ -204,13 +200,12 @@ def test_simple_context(
                         portal.open_context(
                             simple_setup_teardown,
                             data=10,
-                            block_forever=child_blocks_forever,
+                            block_forever=callee_blocks_forever,
                         ) as (ctx, sent),
                     ):
-                        assert current_ipc_ctx() is ctx
                         assert sent == 11
 
-                        if child_blocks_forever:
+                        if callee_blocks_forever:
                             await portal.run(assert_state, value=True)
                         else:
                             assert await ctx.result() == 'yo'
@@ -220,7 +215,7 @@ def test_simple_context(
                                 if error_parent:
                                     raise error_parent
 
-                                if child_blocks_forever:
+                                if callee_blocks_forever:
                                     await ctx.cancel()
                                 else:
                                     # in this case the stream will send a
@@ -259,9 +254,9 @@ def test_simple_context(
 
 
 @pytest.mark.parametrize(
-    'child_returns_early',
+    'callee_returns_early',
     [True, False],
-    ids=lambda item: f'child_returns_early={item}'
+    ids=lambda item: f'callee_returns_early={item}'
 )
 @pytest.mark.parametrize(
     'cancel_method',
@@ -273,14 +268,14 @@ def test_simple_context(
     [True, False],
     ids=lambda item: f'chk_ctx_result_before_exit={item}'
 )
-def test_parent_cancels(
+def test_caller_cancels(
     cancel_method: str,
     chk_ctx_result_before_exit: bool,
-    child_returns_early: bool,
+    callee_returns_early: bool,
     debug_mode: bool,
 ):
     '''
-    Verify that when the opening side of a context (aka the parent)
+    Verify that when the opening side of a context (aka the caller)
     cancels that context, the ctx does not raise a cancelled when
     either calling `.result()` or on context exit.
 
@@ -294,7 +289,7 @@ def test_parent_cancels(
 
         if (
             cancel_method == 'portal'
-            and not child_returns_early
+            and not callee_returns_early
         ):
             try:
                 res = await ctx.result()
@@ -318,7 +313,7 @@ def test_parent_cancels(
                 pytest.fail(f'should not have raised ctxc\n{ctxc}')
 
         # we actually get a result
-        if child_returns_early:
+        if callee_returns_early:
             assert res == 'yo'
             assert ctx.outcome is res
             assert ctx.maybe_error is None
@@ -362,14 +357,14 @@ def test_parent_cancels(
             )
             timeout: float = (
                 0.5
-                if not child_returns_early
+                if not callee_returns_early
                 else 2
             )
             with trio.fail_after(timeout):
                 async with (
                     expect_ctxc(
                         yay=(
-                            not child_returns_early
+                            not callee_returns_early
                             and cancel_method == 'portal'
                         )
                     ),
@@ -377,13 +372,13 @@ def test_parent_cancels(
                     portal.open_context(
                         simple_setup_teardown,
                         data=10,
-                        block_forever=not child_returns_early,
+                        block_forever=not callee_returns_early,
                     ) as (ctx, sent),
                 ):
 
-                    if child_returns_early:
+                    if callee_returns_early:
                         # ensure we block long enough before sending
-                        # a cancel such that the child has already
+                        # a cancel such that the callee has already
                         # returned it's result.
                         await trio.sleep(0.5)
 
@@ -421,7 +416,7 @@ def test_parent_cancels(
             #   which should in turn cause `ctx._scope` to
             # catch any cancellation?
             if (
-                not child_returns_early
+                not callee_returns_early
                 and cancel_method != 'portal'
             ):
                 assert not ctx._scope.cancelled_caught
@@ -430,11 +425,11 @@ def test_parent_cancels(
 
 
 # basic stream terminations:
-# - child context closes without using stream
-# - parent context closes without using stream
-# - parent context calls `Context.cancel()` while streaming
-#   is ongoing resulting in child being cancelled
-# - child calls `Context.cancel()` while streaming and parent
+# - callee context closes without using stream
+# - caller context closes without using stream
+# - caller context calls `Context.cancel()` while streaming
+#   is ongoing resulting in callee being cancelled
+# - callee calls `Context.cancel()` while streaming and caller
 #   sees stream terminated in `RemoteActorError`
 
 # TODO: future possible features
@@ -443,6 +438,7 @@ def test_parent_cancels(
 
 @tractor.context
 async def close_ctx_immediately(
+
     ctx: Context,
 
 ) -> None:
@@ -453,24 +449,13 @@ async def close_ctx_immediately(
     async with ctx.open_stream():
         pass
 
-    print('child returning!')
 
-
-@pytest.mark.parametrize(
-    'parent_send_before_receive',
-    [
-        False,
-        True,
-    ],
-    ids=lambda item: f'child_send_before_receive={item}'
-)
 @tractor_test
-async def test_child_exits_ctx_after_stream_open(
+async def test_callee_closes_ctx_after_stream_open(
     debug_mode: bool,
-    parent_send_before_receive: bool,
 ):
     '''
-    child context closes without using stream.
+    callee context closes without using stream.
 
     This should result in a msg sequence
     |_<root>_
@@ -484,9 +469,6 @@ async def test_child_exits_ctx_after_stream_open(
     => {'stop': True, 'cid': <str>}
 
     '''
-    timeout: float = (
-        0.5 if not debug_mode else 999
-    )
     async with tractor.open_nursery(
         debug_mode=debug_mode,
     ) as an:
@@ -495,7 +477,7 @@ async def test_child_exits_ctx_after_stream_open(
             enable_modules=[__name__],
         )
 
-        with trio.fail_after(timeout):
+        with trio.fail_after(0.5):
             async with portal.open_context(
                 close_ctx_immediately,
 
@@ -507,56 +489,41 @@ async def test_child_exits_ctx_after_stream_open(
 
                 with trio.fail_after(0.4):
                     async with ctx.open_stream() as stream:
-                        if parent_send_before_receive:
-                            print('sending first msg from parent!')
-                            await stream.send('yo')
 
                         # should fall through since ``StopAsyncIteration``
                         # should be raised through translation of
                         # a ``trio.EndOfChannel`` by
                         # ``trio.abc.ReceiveChannel.__anext__()``
-                        msg = 10
-                        async for msg in stream:
+                        async for _ in stream:
                             # trigger failure if we DO NOT
                             # get an EOC!
                             assert 0
                         else:
-                            # never should get anythinig new from
-                            # the underlying stream
-                            assert msg == 10
 
                             # verify stream is now closed
                             try:
                                 with trio.fail_after(0.3):
-                                    print('parent trying to `.receive()` on EoC stream!')
                                     await stream.receive()
-                                    assert 0, 'should have raised eoc!?'
                             except trio.EndOfChannel:
-                                print('parent got EoC as expected!')
                                 pass
-                                # raise
 
                 # TODO: should be just raise the closed resource err
                 # directly here to enforce not allowing a re-open
                 # of a stream to the context (at least until a time of
                 # if/when we decide that's a good idea?)
                 try:
-                    with trio.fail_after(timeout):
+                    with trio.fail_after(0.5):
                         async with ctx.open_stream() as stream:
                             pass
                 except trio.ClosedResourceError:
                     pass
 
-                # if ctx._rx_chan._state.data:
-                #     await tractor.pause()
-
         await portal.cancel_actor()
 
 
 @tractor.context
 async def expect_cancelled(
     ctx: Context,
-    send_before_receive: bool = False,
 
 ) -> None:
     global _state
@@ -566,10 +533,6 @@ async def expect_cancelled(
 
     try:
         async with ctx.open_stream() as stream:
-
-            if send_before_receive:
-                await stream.send('yo')
-
             async for msg in stream:
                 await stream.send(msg)  # echo server
 
@@ -596,49 +559,26 @@ async def expect_cancelled(
         raise
 
     else:
-        assert 0, "child wasn't cancelled !?"
+        assert 0, "callee wasn't cancelled !?"
 
 
-@pytest.mark.parametrize(
-    'child_send_before_receive',
-    [
-        False,
-        True,
-    ],
-    ids=lambda item: f'child_send_before_receive={item}'
-)
-@pytest.mark.parametrize(
-    'rent_wait_for_msg',
-    [
-        False,
-        True,
-    ],
-    ids=lambda item: f'rent_wait_for_msg={item}'
-)
 @pytest.mark.parametrize(
     'use_ctx_cancel_method',
-    [
-        False,
-        'pre_stream',
-        'post_stream_open',
-        'post_stream_close',
-    ],
-    ids=lambda item: f'use_ctx_cancel_method={item}'
+    [False, True],
 )
 @tractor_test
-async def test_parent_exits_ctx_after_child_enters_stream(
-    use_ctx_cancel_method: bool|str,
+async def test_caller_closes_ctx_after_callee_opens_stream(
+    use_ctx_cancel_method: bool,
     debug_mode: bool,
-    rent_wait_for_msg: bool,
-    child_send_before_receive: bool,
 ):
     '''
-    Parent-side of IPC context closes without sending on `MsgStream`.
+    caller context closes without using/opening stream
 
     '''
     async with tractor.open_nursery(
         debug_mode=debug_mode,
     ) as an:
+
         root: Actor = current_actor()
         portal = await an.start_actor(
             'ctx_cancelled',
@@ -647,52 +587,41 @@ async def test_parent_exits_ctx_after_child_enters_stream(
 
         async with portal.open_context(
             expect_cancelled,
-            send_before_receive=child_send_before_receive,
         ) as (ctx, sent):
             assert sent is None
 
             await portal.run(assert_state, value=True)
 
             # call `ctx.cancel()` explicitly
-            if use_ctx_cancel_method == 'pre_stream':
+            if use_ctx_cancel_method:
                 await ctx.cancel()
 
                 # NOTE: means the local side `ctx._scope` will
                 # have been cancelled by an ctxc ack and thus
                 # `._scope.cancelled_caught` should be set.
-                async with (
-                    expect_ctxc(
-                        # XXX: the cause is US since we call
-                        # `Context.cancel()` just above!
-                        yay=True,
-
-                        # XXX: must be propagated to __aexit__
-                        # and should be silently absorbed there
-                        # since we called `.cancel()` just above ;)
-                        reraise=True,
-                    ) as maybe_ctxc,
-                ):
+                try:
                     async with ctx.open_stream() as stream:
+                        async for msg in stream:
+                            pass
 
-                        if rent_wait_for_msg:
-                            async for msg in stream:
-                                print(f'PARENT rx: {msg!r}\n')
-                                break
+                except tractor.ContextCancelled as ctxc:
+                    # XXX: the cause is US since we call
+                    # `Context.cancel()` just above!
+                    assert (
+                        ctxc.canceller
+                        ==
+                        current_actor().uid
+                        ==
+                        root.uid
+                    )
 
-                        if use_ctx_cancel_method == 'post_stream_open':
-                            await ctx.cancel()
+                    # XXX: must be propagated to __aexit__
+                    # and should be silently absorbed there
+                    # since we called `.cancel()` just above ;)
+                    raise
 
-                    if use_ctx_cancel_method == 'post_stream_close':
-                        await ctx.cancel()
-
-                ctxc: tractor.ContextCancelled = maybe_ctxc.value
-                assert (
-                    ctxc.canceller
-                    ==
-                    current_actor().uid
-                    ==
-                    root.uid
-                )
+                else:
+                    assert 0, "Should have context cancelled?"
 
                 # channel should still be up
                 assert portal.channel.connected()
@@ -703,20 +632,13 @@ async def test_parent_exits_ctx_after_child_enters_stream(
                     value=False,
                 )
 
-            # XXX CHILD-BLOCKS case, we SHOULD NOT exit from the
-            # `.open_context()` before the child has returned,
-            # errored or been cancelled!
             else:
                 try:
-                    with trio.fail_after(
-                        0.5  # if not debug_mode else 999
-                    ):
-                        res = await ctx.wait_for_result()
-                        assert res is not tractor._context.Unresolved
+                    with trio.fail_after(0.2):
+                        await ctx.result()
                         assert 0, "Callee should have blocked!?"
                 except trio.TooSlowError:
-                    # NO-OP -> since already triggered by
-                    # `trio.fail_after()` above!
+                    # NO-OP -> since already called above
                     await ctx.cancel()
 
         # NOTE: local scope should have absorbed the cancellation since
@@ -756,7 +678,7 @@ async def test_parent_exits_ctx_after_child_enters_stream(
 
 
 @tractor_test
-async def test_multitask_parent_cancels_from_nonroot_task(
+async def test_multitask_caller_cancels_from_nonroot_task(
     debug_mode: bool,
 ):
     async with tractor.open_nursery(
@@ -808,6 +730,7 @@ async def test_multitask_parent_cancels_from_nonroot_task(
 
 @tractor.context
 async def cancel_self(
+
     ctx: Context,
 
 ) -> None:
@@ -847,11 +770,11 @@ async def cancel_self(
 
 
 @tractor_test
-async def test_child_cancels_before_started(
+async def test_callee_cancels_before_started(
     debug_mode: bool,
 ):
     '''
-    Callee calls `Context.cancel()` while streaming and parent
+    Callee calls `Context.cancel()` while streaming and caller
     sees stream terminated in `ContextCancelled`.
 
     '''
@@ -872,12 +795,10 @@ async def test_child_cancels_before_started(
 
         # raises a special cancel signal
         except tractor.ContextCancelled as ce:
-            _ce = ce  # for debug on crash
             ce.boxed_type == trio.Cancelled
 
             # the traceback should be informative
-            assert 'itself' in ce.tb_str
-            assert ce.tb_str == ce.msgdata['tb_str']
+            assert 'itself' in ce.msgdata['tb_str']
 
         # teardown the actor
         await portal.cancel_actor()
@@ -898,13 +819,14 @@ async def never_open_stream(
 
 
 @tractor.context
-async def keep_sending_from_child(
+async def keep_sending_from_callee(
+
     ctx:  Context,
     msg_buffer_size: int|None = None,
 
 ) -> None:
     '''
-    Send endlessly on the child stream.
+    Send endlessly on the calleee stream.
 
     '''
     await ctx.started()
@@ -912,7 +834,7 @@ async def keep_sending_from_child(
         msg_buffer_size=msg_buffer_size,
     ) as stream:
         for msg in count():
-            print(f'child sending {msg}')
+            print(f'callee sending {msg}')
             await stream.send(msg)
             await trio.sleep(0.01)
 
@@ -920,13 +842,10 @@ async def keep_sending_from_child(
 @pytest.mark.parametrize(
     'overrun_by',
     [
-        ('parent', 1, never_open_stream),
-        ('child', 0, keep_sending_from_child),
+        ('caller', 1, never_open_stream),
+        ('callee', 0, keep_sending_from_callee),
     ],
-    ids=[
-         ('parent_1buf_never_open_stream'),
-         ('child_0buf_keep_sending_from_child'),
-    ]
+    ids='overrun_condition={}'.format,
 )
 def test_one_end_stream_not_opened(
     overrun_by: tuple[str, int, Callable],
@@ -950,48 +869,48 @@ def test_one_end_stream_not_opened(
                 enable_modules=[__name__],
             )
 
-            with trio.fail_after(1):
-                async with portal.open_context(
-                    entrypoint,
-                ) as (ctx, sent):
-                    assert sent is None
+            async with portal.open_context(
+                entrypoint,
+            ) as (ctx, sent):
+                assert sent is None
 
-                    if 'parent' in overrunner:
-                        async with ctx.open_stream() as stream:
+                if 'caller' in overrunner:
 
-                            # itersend +1 msg more then the buffer size
-                            # to cause the most basic overrun.
-                            for i in range(buf_size):
-                                print(f'sending {i}')
-                                await stream.send(i)
+                    async with ctx.open_stream() as stream:
 
-                            else:
-                                # expect overrun error to be relayed back
-                                # and this sleep interrupted
-                                await trio.sleep_forever()
+                        # itersend +1 msg more then the buffer size
+                        # to cause the most basic overrun.
+                        for i in range(buf_size):
+                            print(f'sending {i}')
+                            await stream.send(i)
 
-                    else:
-                        # child overruns parent case so we do nothing here
-                        await trio.sleep_forever()
+                        else:
+                            # expect overrun error to be relayed back
+                            # and this sleep interrupted
+                            await trio.sleep_forever()
+
+                else:
+                    # callee overruns caller case so we do nothing here
+                    await trio.sleep_forever()
 
             await portal.cancel_actor()
 
     # 2 overrun cases and the no overrun case (which pushes right up to
     # the msg limit)
     if (
-        overrunner == 'parent'
+        overrunner == 'caller'
     ):
         with pytest.raises(tractor.RemoteActorError) as excinfo:
             trio.run(main)
 
         assert excinfo.value.boxed_type == StreamOverrun
 
-    elif overrunner == 'child':
+    elif overrunner == 'callee':
         with pytest.raises(tractor.RemoteActorError) as excinfo:
             trio.run(main)
 
         # TODO: embedded remote errors so that we can verify the source
-        # error? the child delivers an error which is an overrun
+        # error? the callee delivers an error which is an overrun
         # wrapped in a remote actor error.
         assert excinfo.value.boxed_type == tractor.RemoteActorError
 
@@ -1001,7 +920,8 @@ def test_one_end_stream_not_opened(
 
 @tractor.context
 async def echo_back_sequence(
-    ctx: Context,
+
+    ctx:  Context,
     seq: list[int],
     wait_for_cancel: bool,
     allow_overruns_side: str,
@@ -1010,12 +930,12 @@ async def echo_back_sequence(
 
 ) -> None:
     '''
-    Send endlessly on the child stream using a small buffer size
+    Send endlessly on the calleee stream using a small buffer size
     setting on the contex to simulate backlogging that would normally
     cause overruns.
 
     '''
-    # NOTE: ensure that if the parent is expecting to cancel this task
+    # NOTE: ensure that if the caller is expecting to cancel this task
     # that we stay echoing much longer then they are so we don't
     # return early instead of receive the cancel msg.
     total_batches: int = (
@@ -1024,7 +944,7 @@ async def echo_back_sequence(
     )
 
     await ctx.started()
-    # await tractor.pause()
+    # await tractor.breakpoint()
     async with ctx.open_stream(
         msg_buffer_size=msg_buffer_size,
 
@@ -1065,18 +985,18 @@ async def echo_back_sequence(
                 if be_slow:
                     await trio.sleep(0.05)
 
-                print('child waiting on next')
+                print('callee waiting on next')
 
-            print(f'child echoing back latest batch\n{batch}')
+            print(f'callee echoing back latest batch\n{batch}')
             for msg in batch:
-                print(f'child sending msg\n{msg}')
+                print(f'callee sending msg\n{msg}')
                 await stream.send(msg)
 
     try:
         return 'yo'
     finally:
         print(
-            'exiting child with context:\n'
+            'exiting callee with context:\n'
             f'{pformat(ctx)}\n'
         )
 
@@ -1130,68 +1050,59 @@ def test_maybe_allow_overruns_stream(
             debug_mode=debug_mode,
         ) as an:
             portal = await an.start_actor(
-                'child_sends_forever',
+                'callee_sends_forever',
                 enable_modules=[__name__],
                 loglevel=loglevel,
                 debug_mode=debug_mode,
             )
+            seq = list(range(10))
+            async with portal.open_context(
+                echo_back_sequence,
+                seq=seq,
+                wait_for_cancel=cancel_ctx,
+                be_slow=(slow_side == 'child'),
+                allow_overruns_side=allow_overruns_side,
 
-            # stream-sequence batch info with send delay to determine
-            # approx timeout determining whether test has hung.
-            total_batches: int = 2
-            num_items: int = 10
-            seq = list(range(num_items))
-            parent_send_delay: float = 0.16
-            timeout: float = math.ceil(
-                total_batches * num_items * parent_send_delay
-            )
-            with trio.fail_after(timeout):
-                async with portal.open_context(
-                    echo_back_sequence,
-                    seq=seq,
-                    wait_for_cancel=cancel_ctx,
-                    be_slow=(slow_side == 'child'),
-                    allow_overruns_side=allow_overruns_side,
+            ) as (ctx, sent):
+                assert sent is None
 
-                ) as (ctx, sent):
-                    assert sent is None
+                async with ctx.open_stream(
+                    msg_buffer_size=1 if slow_side == 'parent' else None,
+                    allow_overruns=(allow_overruns_side in {'parent', 'both'}),
+                ) as stream:
 
-                    async with ctx.open_stream(
-                        msg_buffer_size=1 if slow_side == 'parent' else None,
-                        allow_overruns=(allow_overruns_side in {'parent', 'both'}),
-                    ) as stream:
+                    total_batches: int = 2
+                    for _ in range(total_batches):
+                        for msg in seq:
+                            # print(f'root tx {msg}')
+                            await stream.send(msg)
+                            if slow_side == 'parent':
+                                # NOTE: we make the parent slightly
+                                # slower, when it is slow, to make sure
+                                # that in the overruns everywhere case
+                                await trio.sleep(0.16)
 
-                        for _ in range(total_batches):
-                            for msg in seq:
-                                # print(f'root tx {msg}')
-                                await stream.send(msg)
-                                if slow_side == 'parent':
-                                    # NOTE: we make the parent slightly
-                                    # slower, when it is slow, to make sure
-                                    # that in the overruns everywhere case
-                                    await trio.sleep(parent_send_delay)
-
-                            batch = []
-                            async for msg in stream:
-                                print(f'root rx {msg}')
-                                batch.append(msg)
-                                if batch == seq:
-                                    break
-
-                    if cancel_ctx:
-                        # cancel the remote task
-                        print('Requesting `ctx.cancel()` in parent!')
-                        await ctx.cancel()
-
-                res: str|ContextCancelled = await ctx.result()
+                        batch = []
+                        async for msg in stream:
+                            print(f'root rx {msg}')
+                            batch.append(msg)
+                            if batch == seq:
+                                break
 
                 if cancel_ctx:
-                    assert isinstance(res, ContextCancelled)
-                    assert tuple(res.canceller) == current_actor().uid
+                    # cancel the remote task
+                    print('Requesting `ctx.cancel()` in parent!')
+                    await ctx.cancel()
 
-                else:
-                    print(f'RX ROOT SIDE RESULT {res}')
-                    assert res == 'yo'
+            res: str|ContextCancelled = await ctx.result()
+
+            if cancel_ctx:
+                assert isinstance(res, ContextCancelled)
+                assert tuple(res.canceller) == current_actor().uid
+
+            else:
+                print(f'RX ROOT SIDE RESULT {res}')
+                assert res == 'yo'
 
             # cancel the daemon
             await portal.cancel_actor()
@@ -1232,8 +1143,7 @@ def test_maybe_allow_overruns_stream(
 
         elif slow_side == 'parent':
             assert err.boxed_type == tractor.RemoteActorError
-            assert 'StreamOverrun' in err.tb_str
-            assert err.tb_str == err.msgdata['tb_str']
+            assert 'StreamOverrun' in err.msgdata['tb_str']
 
     else:
         # if this hits the logic blocks from above are not

tests/test_debugger.py

@@ -10,37 +10,31 @@ TODO:
     - wonder if any of it'll work on OS X?
 
 """
-from __future__ import annotations
 from functools import partial
 import itertools
+from typing import Optional
 import platform
+import pathlib
 import time
-from typing import (
-    TYPE_CHECKING,
-)
 
 import pytest
+import pexpect
 from pexpect.exceptions import (
     TIMEOUT,
     EOF,
 )
 
-from .conftest import (
-    do_ctlc,
-    PROMPT,
+from tractor._testing import (
+    examples_dir,
+)
+from tractor.devx._debug import (
     _pause_msg,
     _crash_msg,
-    _repl_fail_msg,
 )
 from .conftest import (
-    expect,
-    in_prompt_msg,
-    assert_before,
+    _ci_env,
 )
 
-if TYPE_CHECKING:
-    from ..conftest import PexpectSpawner
-
 # TODO: The next great debugger audit could be done by you!
 # - recurrent entry to breakpoint() from single actor *after* and an
 #   error in another task?
@@ -58,6 +52,15 @@ if platform.system() == 'Windows':
     )
 
 
+def mk_cmd(ex_name: str) -> str:
+    '''
+    Generate a command suitable to pass to ``pexpect.spawn()``.
+
+    '''
+    script_path: pathlib.Path = examples_dir() / 'debugging' / f'{ex_name}.py'
+    return ' '.join(['python', str(script_path)])
+
+
 # TODO: was trying to this xfail style but some weird bug i see in CI
 # that's happening at collect time.. pretty soon gonna dump actions i'm
 # thinkin...
@@ -76,6 +79,136 @@ has_nested_actors = pytest.mark.has_nested_actors
 # )
 
 
+@pytest.fixture
+def spawn(
+    start_method,
+    testdir,
+    reg_addr,
+) -> 'pexpect.spawn':
+
+    if start_method != 'trio':
+        pytest.skip(
+            "Debugger tests are only supported on the trio backend"
+        )
+
+    def _spawn(cmd):
+        return testdir.spawn(
+            cmd=mk_cmd(cmd),
+            expect_timeout=3,
+        )
+
+    return _spawn
+
+
+PROMPT = r"\(Pdb\+\)"
+
+
+def expect(
+    child,
+
+    # prompt by default
+    patt: str = PROMPT,
+
+    **kwargs,
+
+) -> None:
+    '''
+    Expect wrapper that prints last seen console
+    data before failing.
+
+    '''
+    try:
+        child.expect(
+            patt,
+            **kwargs,
+        )
+    except TIMEOUT:
+        before = str(child.before.decode())
+        print(before)
+        raise
+
+
+def in_prompt_msg(
+    prompt: str,
+    parts: list[str],
+
+    pause_on_false: bool = False,
+    print_prompt_on_false: bool = True,
+
+) -> bool:
+    '''
+    Predicate check if (the prompt's) std-streams output has all
+    `str`-parts in it.
+
+    Can be used in test asserts for bulk matching expected
+    log/REPL output for a given `pdb` interact point.
+
+    '''
+    for part in parts:
+        if part not in prompt:
+
+            if pause_on_false:
+                import pdbp
+                pdbp.set_trace()
+
+            if print_prompt_on_false:
+                print(prompt)
+
+            return False
+
+    return True
+
+def assert_before(
+    child,
+    patts: list[str],
+
+    **kwargs,
+
+) -> None:
+
+    # as in before the prompt end
+    before: str = str(child.before.decode())
+    assert in_prompt_msg(
+        prompt=before,
+        parts=patts,
+
+        **kwargs
+    )
+
+
+@pytest.fixture(
+    params=[False, True],
+    ids='ctl-c={}'.format,
+)
+def ctlc(
+    request,
+    ci_env: bool,
+
+) -> bool:
+
+    use_ctlc = request.param
+
+    node = request.node
+    markers = node.own_markers
+    for mark in markers:
+        if mark.name == 'has_nested_actors':
+            pytest.skip(
+                f'Test {node} has nested actors and fails with Ctrl-C.\n'
+                f'The test can sometimes run fine locally but until'
+                ' we solve' 'this issue this CI test will be xfail:\n'
+                'https://github.com/goodboy/tractor/issues/320'
+            )
+
+    if use_ctlc:
+        # XXX: disable pygments highlighting for auto-tests
+        # since some envs (like actions CI) will struggle
+        # the the added color-char encoding..
+        from tractor.devx._debug import TractorConfig
+        TractorConfig.use_pygements = False
+
+    yield use_ctlc
+
+
 @pytest.mark.parametrize(
     'user_in_out',
     [
@@ -84,10 +217,7 @@ has_nested_actors = pytest.mark.has_nested_actors
     ],
     ids=lambda item: f'{item[0]} -> {item[1]}',
 )
-def test_root_actor_error(
-    spawn,
-    user_in_out,
-):
+def test_root_actor_error(spawn, user_in_out):
     '''
     Demonstrate crash handler entering pdb from basic error in root actor.
 
@@ -99,15 +229,14 @@ def test_root_actor_error(
     # scan for the prompt
     expect(child, PROMPT)
 
+    before = str(child.before.decode())
+
     # make sure expected logging and error arrives
     assert in_prompt_msg(
-        child,
-        [
-            _crash_msg,
-            "('root'",
-            'AssertionError',
-        ]
+        before,
+        [_crash_msg, "('root'"]
     )
+    assert 'AssertionError' in before
 
     # send user command
     child.sendline(user_input)
@@ -126,10 +255,8 @@ def test_root_actor_error(
     ids=lambda item: f'{item[0]} -> {item[1]}',
 )
 def test_root_actor_bp(spawn, user_in_out):
-    '''
-    Demonstrate breakpoint from in root actor.
-
-    '''
+    """Demonstrate breakpoint from in root actor.
+    """
     user_input, expect_err_str = user_in_out
     child = spawn('root_actor_breakpoint')
 
@@ -143,7 +270,7 @@ def test_root_actor_bp(spawn, user_in_out):
     child.expect('\r\n')
 
     # process should exit
-    child.expect(EOF)
+    child.expect(pexpect.EOF)
 
     if expect_err_str is None:
         assert 'Error' not in str(child.before)
@@ -151,6 +278,38 @@ def test_root_actor_bp(spawn, user_in_out):
         assert expect_err_str in str(child.before)
 
 
+def do_ctlc(
+    child,
+    count: int = 3,
+    delay: float = 0.1,
+    patt: Optional[str] = None,
+
+    # expect repl UX to reprint the prompt after every
+    # ctrl-c send.
+    # XXX: no idea but, in CI this never seems to work even on 3.10 so
+    # needs some further investigation potentially...
+    expect_prompt: bool = not _ci_env,
+
+) -> None:
+
+    # make sure ctl-c sends don't do anything but repeat output
+    for _ in range(count):
+        time.sleep(delay)
+        child.sendcontrol('c')
+
+        # TODO: figure out why this makes CI fail..
+        # if you run this test manually it works just fine..
+        if expect_prompt:
+            before = str(child.before.decode())
+            time.sleep(delay)
+            child.expect(PROMPT)
+            time.sleep(delay)
+
+            if patt:
+                # should see the last line on console
+                assert patt in before
+
+
 def test_root_actor_bp_forever(
     spawn,
     ctlc: bool,
@@ -190,7 +349,7 @@ def test_root_actor_bp_forever(
 
     # quit out of the loop
     child.sendline('q')
-    child.expect(EOF)
+    child.expect(pexpect.EOF)
 
 
 @pytest.mark.parametrize(
@@ -212,12 +371,10 @@ def test_subactor_error(
     # scan for the prompt
     child.expect(PROMPT)
 
+    before = str(child.before.decode())
     assert in_prompt_msg(
-        child,
-        [
-            _crash_msg,
-            "('name_error'",
-        ]
+        before,
+        [_crash_msg, "('name_error'"]
     )
 
     if do_next:
@@ -236,15 +393,17 @@ def test_subactor_error(
         child.sendline('continue')
 
     child.expect(PROMPT)
+    before = str(child.before.decode())
+
+    # root actor gets debugger engaged
     assert in_prompt_msg(
-        child,
-        [
-            _crash_msg,
-            # root actor gets debugger engaged
-            "('root'",
-            # error is a remote error propagated from the subactor
-            "('name_error'",
-        ]
+        before,
+        [_crash_msg, "('root'"]
+    )
+    # error is a remote error propagated from the subactor
+    assert in_prompt_msg(
+        before,
+        [_crash_msg, "('name_error'"]
     )
 
     # another round
@@ -255,7 +414,7 @@ def test_subactor_error(
     child.expect('\r\n')
 
     # process should exit
-    child.expect(EOF)
+    child.expect(pexpect.EOF)
 
 
 def test_subactor_breakpoint(
@@ -265,11 +424,14 @@ def test_subactor_breakpoint(
     "Single subactor with an infinite breakpoint loop"
 
     child = spawn('subactor_breakpoint')
+
+    # scan for the prompt
     child.expect(PROMPT)
+
+    before = str(child.before.decode())
     assert in_prompt_msg(
-        child,
-        [_pause_msg,
-         "('breakpoint_forever'",]
+        before,
+        [_pause_msg, "('breakpoint_forever'"]
     )
 
     # do some "next" commands to demonstrate recurrent breakpoint
@@ -285,8 +447,9 @@ def test_subactor_breakpoint(
     for _ in range(5):
         child.sendline('continue')
         child.expect(PROMPT)
+        before = str(child.before.decode())
         assert in_prompt_msg(
-            child,
+            before,
             [_pause_msg, "('breakpoint_forever'"]
         )
 
@@ -299,12 +462,9 @@ def test_subactor_breakpoint(
     # child process should exit but parent will capture pdb.BdbQuit
     child.expect(PROMPT)
 
-    assert in_prompt_msg(
-        child,
-        ['RemoteActorError:',
-         "('breakpoint_forever'",
-         'bdb.BdbQuit',]
-    )
+    before = str(child.before.decode())
+    assert "RemoteActorError: ('breakpoint_forever'" in before
+    assert 'bdb.BdbQuit' in before
 
     if ctlc:
         do_ctlc(child)
@@ -313,17 +473,11 @@ def test_subactor_breakpoint(
     child.sendline('c')
 
     # process should exit
-    child.expect(EOF)
+    child.expect(pexpect.EOF)
 
-    assert in_prompt_msg(
-        child, [
-        'MessagingError:',
-        'RemoteActorError:',
-         "('breakpoint_forever'",
-         'bdb.BdbQuit',
-        ],
-        pause_on_false=True,
-    )
+    before = str(child.before.decode())
+    assert "RemoteActorError: ('breakpoint_forever'" in before
+    assert 'bdb.BdbQuit' in before
 
 
 @has_nested_actors
@@ -343,7 +497,7 @@ def test_multi_subactors(
 
     before = str(child.before.decode())
     assert in_prompt_msg(
-        child,
+        before,
         [_pause_msg, "('breakpoint_forever'"]
     )
 
@@ -364,14 +518,12 @@ def test_multi_subactors(
 
     # first name_error failure
     child.expect(PROMPT)
+    before = str(child.before.decode())
     assert in_prompt_msg(
-        child,
-        [
-            _crash_msg,
-            "('name_error'",
-            "NameError",
-        ]
+        before,
+        [_crash_msg, "('name_error'"]
     )
+    assert "NameError" in before
 
     if ctlc:
         do_ctlc(child)
@@ -395,8 +547,9 @@ def test_multi_subactors(
     # breakpoint loop should re-engage
     child.sendline('c')
     child.expect(PROMPT)
+    before = str(child.before.decode())
     assert in_prompt_msg(
-        child,
+        before,
         [_pause_msg, "('breakpoint_forever'"]
     )
 
@@ -459,7 +612,7 @@ def test_multi_subactors(
 
     # process should exit
     child.sendline('c')
-    child.expect(EOF)
+    child.expect(pexpect.EOF)
 
     # repeat of previous multierror for final output
     assert_before(child, [
@@ -489,28 +642,25 @@ def test_multi_daemon_subactors(
     # the root's tty lock first so anticipate either crash
     # message on the first entry.
 
-    bp_forev_parts = [
-        _pause_msg,
-        "('bp_forever'",
-    ]
+    bp_forev_parts = [_pause_msg, "('bp_forever'"]
     bp_forev_in_msg = partial(
         in_prompt_msg,
         parts=bp_forev_parts,
     )
 
-    name_error_msg: str = "NameError: name 'doggypants' is not defined"
-    name_error_parts: list[str] = [name_error_msg]
+    name_error_msg = "NameError: name 'doggypants' is not defined"
+    name_error_parts = [name_error_msg]
 
     before = str(child.before.decode())
 
-    if bp_forev_in_msg(child=child):
+    if bp_forev_in_msg(prompt=before):
         next_parts = name_error_parts
 
     elif name_error_msg in before:
         next_parts = bp_forev_parts
 
     else:
-        raise ValueError('Neither log msg was found !?')
+        raise ValueError("Neither log msg was found !?")
 
     if ctlc:
         do_ctlc(child)
@@ -535,7 +685,7 @@ def test_multi_daemon_subactors(
     # now the root actor won't clobber the bp_forever child
     # during it's first access to the debug lock, but will instead
     # wait for the lock to release, by the edge triggered
-    # ``devx.debug.Lock.no_remote_has_tty`` event before sending cancel messages
+    # ``devx._debug.Lock.no_remote_has_tty`` event before sending cancel messages
     # (via portals) to its underlings B)
 
     # at some point here there should have been some warning msg from
@@ -579,12 +729,14 @@ def test_multi_daemon_subactors(
     # wait for final error in root
     # where it crashs with boxed error
     while True:
-        child.sendline('c')
-        child.expect(PROMPT)
-        if not in_prompt_msg(
-            child,
-            bp_forev_parts
-        ):
+        try:
+            child.sendline('c')
+            child.expect(PROMPT)
+            assert_before(
+                child,
+                bp_forev_parts
+            )
+        except AssertionError:
             break
 
     assert_before(
@@ -593,14 +745,13 @@ def test_multi_daemon_subactors(
             # boxed error raised in root task
             # "Attaching to pdb in crashed actor: ('root'",
             _crash_msg,
-            "('root'",  # should attach in root
-            "_exceptions.RemoteActorError:",  # with an embedded RAE for..
-            "('name_error'",  # the src subactor which raised
+            "('root'",
+            "_exceptions.RemoteActorError: ('name_error'",
         ]
     )
 
     child.sendline('c')
-    child.expect(EOF)
+    child.expect(pexpect.EOF)
 
 
 @has_nested_actors
@@ -676,7 +827,7 @@ def test_multi_subactors_root_errors(
     ])
 
     child.sendline('c')
-    child.expect(EOF)
+    child.expect(pexpect.EOF)
 
     assert_before(child, [
         # "Attaching to pdb in crashed actor: ('root'",
@@ -696,11 +847,10 @@ def test_multi_nested_subactors_error_through_nurseries(
     # https://github.com/goodboy/tractor/issues/320
     # ctlc: bool,
 ):
-    '''
-    Verify deeply nested actors that error trigger debugger entries
+    """Verify deeply nested actors that error trigger debugger entries
     at each actor nurserly (level) all the way up the tree.
 
-    '''
+    """
     # NOTE: previously, inside this script was a bug where if the
     # parent errors before a 2-levels-lower actor has released the lock,
     # the parent tries to cancel it but it's stuck in the debugger?
@@ -720,31 +870,22 @@ def test_multi_nested_subactors_error_through_nurseries(
         except EOF:
             break
 
-    assert_before(
-        child,
-        [ # boxed source errors
-            "NameError: name 'doggypants' is not defined",
-            "tractor._exceptions.RemoteActorError:",
-            "('name_error'",
-            "bdb.BdbQuit",
+    assert_before(child, [
 
-            # first level subtrees
-            # "tractor._exceptions.RemoteActorError: ('spawner0'",
-            "src_uid=('spawner0'",
+        # boxed source errors
+        "NameError: name 'doggypants' is not defined",
+        "tractor._exceptions.RemoteActorError: ('name_error'",
+        "bdb.BdbQuit",
 
-            # "tractor._exceptions.RemoteActorError: ('spawner1'",
+        # first level subtrees
+        "tractor._exceptions.RemoteActorError: ('spawner0'",
+        # "tractor._exceptions.RemoteActorError: ('spawner1'",
 
-            # 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_0'",
-            "relay_uid=('spawn_until_1'",
-            "src_uid=('spawn_until_2'",
-        ]
-    )
+        # 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'",
+    ])
 
 
 @pytest.mark.timeout(15)
@@ -765,13 +906,10 @@ def test_root_nursery_cancels_before_child_releases_tty_lock(
     child = spawn('root_cancelled_but_child_is_in_tty_lock')
 
     child.expect(PROMPT)
-    assert_before(
-        child,
-        [
-            "NameError: name 'doggypants' is not defined",
-            "tractor._exceptions.RemoteActorError: ('name_error'",
-        ],
-    )
+
+    before = str(child.before.decode())
+    assert "NameError: name 'doggypants' is not defined" in before
+    assert "tractor._exceptions.RemoteActorError: ('name_error'" not in before
     time.sleep(0.5)
 
     if ctlc:
@@ -809,7 +947,7 @@ def test_root_nursery_cancels_before_child_releases_tty_lock(
 
     for i in range(3):
         try:
-            child.expect(EOF, timeout=0.5)
+            child.expect(pexpect.EOF, timeout=0.5)
             break
         except TIMEOUT:
             child.sendline('c')
@@ -851,7 +989,7 @@ def test_root_cancels_child_context_during_startup(
         do_ctlc(child)
 
     child.sendline('c')
-    child.expect(EOF)
+    child.expect(pexpect.EOF)
 
 
 def test_different_debug_mode_per_actor(
@@ -862,8 +1000,9 @@ def test_different_debug_mode_per_actor(
     child.expect(PROMPT)
 
     # only one actor should enter the debugger
+    before = str(child.before.decode())
     assert in_prompt_msg(
-        child,
+        before,
         [_crash_msg, "('debugged_boi'", "RuntimeError"],
     )
 
@@ -871,322 +1010,82 @@ def test_different_debug_mode_per_actor(
         do_ctlc(child)
 
     child.sendline('c')
-    child.expect(EOF)
+    child.expect(pexpect.EOF)
+
+    before = str(child.before.decode())
 
     # NOTE: this debugged actor error currently WON'T show up since the
     # root will actually cancel and terminate the nursery before the error
     # msg reported back from the debug mode actor is processed.
     # assert "tractor._exceptions.RemoteActorError: ('debugged_boi'" in before
 
+    assert "tractor._exceptions.RemoteActorError: ('crash_boi'" in before
+
     # the crash boi should not have made a debugger request but
     # instead crashed completely
-    assert_before(
-        child,
-        [
-            "tractor._exceptions.RemoteActorError:",
-            "src_uid=('crash_boi'",
-            "RuntimeError",
-        ]
-    )
+    assert "tractor._exceptions.RemoteActorError: ('crash_boi'" in before
+    assert "RuntimeError" in before
 
 
-def test_post_mortem_api(
+
+def test_pause_from_sync(
     spawn,
-    ctlc: bool,
+    ctlc: bool
 ):
     '''
-    Verify the `tractor.post_mortem()` API works in an exception
-    handler block.
+    Verify we can use the `pdbp` REPL from sync functions AND from
+    any thread spawned with `trio.to_thread.run_sync()`.
+
+    `examples/debugging/sync_bp.py`
 
     '''
-    child = spawn('pm_in_subactor')
-
-    # First entry is via manual `.post_mortem()`
+    child = spawn('sync_bp')
     child.expect(PROMPT)
     assert_before(
         child,
         [
-            _crash_msg,
-            "<Task 'name_error'",
-            "NameError",
-            "('child'",
-            "tractor.post_mortem()",
+            '`greenback` portal opened!',
+            # pre-prompt line
+            _pause_msg, "('root'",
         ]
     )
     if ctlc:
         do_ctlc(child)
     child.sendline('c')
-
-    # 2nd is RPC crash handler
     child.expect(PROMPT)
+
+    # XXX shouldn't see gb loaded again
+    before = str(child.before.decode())
+    assert not in_prompt_msg(
+        before,
+        ['`greenback` portal opened!'],
+    )
     assert_before(
         child,
-        [
-            _crash_msg,
-            "<Task 'name_error'",
-            "NameError",
-            "('child'",
-        ]
+        [_pause_msg, "('root'",],
     )
+
     if ctlc:
         do_ctlc(child)
     child.sendline('c')
-
-    # 3rd is via RAE bubbled to root's parent ctx task and
-    # crash-handled via another manual pm call.
     child.expect(PROMPT)
     assert_before(
         child,
-        [
-            _crash_msg,
-            "<Task '__main__.main'",
-            "('root'",
-            "NameError",
-            "tractor.post_mortem()",
-            "src_uid=('child'",
-        ]
+        [_pause_msg, "('subactor'",],
     )
+
     if ctlc:
         do_ctlc(child)
     child.sendline('c')
-
-    # 4th and FINAL is via RAE bubbled to root's parent ctx task and
-    # crash-handled via another manual pm call.
     child.expect(PROMPT)
+    # non-main thread case
+    # TODO: should we agument the pre-prompt msg in this case?
     assert_before(
         child,
-        [
-            _crash_msg,
-            "<Task '__main__.main'",
-            "('root'",
-            "NameError",
-            "src_uid=('child'",
-        ]
+        [_pause_msg, "('root'",],
     )
+
     if ctlc:
         do_ctlc(child)
-
-
-    # TODO: ensure we're stopped and showing the right call stack frame
-    # -[ ] need a way to strip the terminal color chars in order to
-    #    pattern match... see TODO around `assert_before()` above!
-    # child.sendline('w')
-    # child.expect(PROMPT)
-    # assert_before(
-    #     child,
-    #     [
-    #         # error src block annot at ctx open
-    #         '-> async with p.open_context(name_error) as (ctx, first):',
-    #     ]
-    # )
-
-    # # step up a frame to ensure the it's the root's nursery
-    # child.sendline('u')
-    # child.expect(PROMPT)
-    # assert_before(
-    #     child,
-    #     [
-    #         # handler block annotation
-    #         '-> async with tractor.open_nursery(',
-    #     ]
-    # )
-
     child.sendline('c')
-    child.expect(EOF)
-
-
-def test_shield_pause(
-    spawn,
-):
-    '''
-    Verify the `tractor.pause()/.post_mortem()` API works inside an
-    already cancelled `trio.CancelScope` and that you can step to the
-    next checkpoint wherein the cancelled will get raised.
-
-    '''
-    child = spawn('shielded_pause')
-
-    # First entry is via manual `.post_mortem()`
-    child.expect(PROMPT)
-    assert_before(
-        child,
-        [
-            _pause_msg,
-            "cancellable_pause_loop'",
-            "('cancelled_before_pause'",  # actor name
-        ]
-    )
-
-    # since 3 tries in ex. shield pause loop
-    for i in range(3):
-        child.sendline('c')
-        child.expect(PROMPT)
-        assert_before(
-            child,
-            [
-                _pause_msg,
-                "INSIDE SHIELDED PAUSE",
-                "('cancelled_before_pause'",  # actor name
-            ]
-        )
-
-    # back inside parent task that opened nursery
-    child.sendline('c')
-    child.expect(PROMPT)
-    assert_before(
-        child,
-        [
-            _crash_msg,
-            "('cancelled_before_pause'",  # actor name
-            _repl_fail_msg,
-            "trio.Cancelled",
-            "raise Cancelled._create()",
-
-            # we should be handling a taskc inside
-            # the first `.port_mortem()` sin-shield!
-            'await DebugStatus.req_finished.wait()',
-        ]
-    )
-
-    # same as above but in the root actor's task
-    child.sendline('c')
-    child.expect(PROMPT)
-    assert_before(
-        child,
-        [
-            _crash_msg,
-            "('root'",  # actor name
-            _repl_fail_msg,
-            "trio.Cancelled",
-            "raise Cancelled._create()",
-
-            # handling a taskc inside the first unshielded
-            # `.port_mortem()`.
-            # BUT in this case in the root-proc path ;)
-            'wait Lock._debug_lock.acquire()',
-        ]
-    )
-    child.sendline('c')
-    child.expect(EOF)
-
-
-@pytest.mark.parametrize(
-    'quit_early', [False, True]
-)
-def test_ctxep_pauses_n_maybe_ipc_breaks(
-    spawn: PexpectSpawner,
-    quit_early: bool,
-):
-    '''
-    Audit generator embedded `.pause()`es from within a `@context`
-    endpoint with a chan close at the end, requiring that ctl-c is
-    mashed and zombie reaper kills sub with no hangs.
-
-    '''
-    child = spawn('subactor_bp_in_ctx')
-    child.expect(PROMPT)
-
-    # 3 iters for the `gen()` pause-points
-    for i in range(3):
-        assert_before(
-            child,
-            [
-                _pause_msg,
-                "('bp_boi'",  # actor name
-                "<Task 'just_bp'",  # task name
-            ]
-        )
-        if (
-            i == 1
-            and
-            quit_early
-        ):
-            child.sendline('q')
-            child.expect(PROMPT)
-            assert_before(
-                child,
-                ["tractor._exceptions.RemoteActorError: remote task raised a 'BdbQuit'",
-                 "bdb.BdbQuit",
-                 "('bp_boi'",
-                ]
-            )
-            child.sendline('c')
-            child.expect(EOF)
-            assert_before(
-                child,
-                ["tractor._exceptions.RemoteActorError: remote task raised a 'BdbQuit'",
-                 "bdb.BdbQuit",
-                 "('bp_boi'",
-                ]
-            )
-            break  # end-of-test
-
-        child.sendline('c')
-        try:
-            child.expect(PROMPT)
-        except TIMEOUT:
-            # no prompt since we hang due to IPC chan purposely
-            # closed so verify we see error reporting as well as
-            # a failed crash-REPL request msg and can CTL-c our way
-            # out.
-            assert_before(
-                child,
-                ['peer IPC channel closed abruptly?',
-                 'another task closed this fd',
-                 'Debug lock request was CANCELLED?',
-                 "TransportClosed: 'MsgpackUDSStream' was already closed locally ?",]
-
-                # XXX races on whether these show/hit?
-                 # 'Failed to REPl via `_pause()` You called `tractor.pause()` from an already cancelled scope!',
-                 # 'AssertionError',
-            )
-            # OSc(ancel) the hanging tree
-            do_ctlc(
-                child=child,
-                expect_prompt=False,
-            )
-            child.expect(EOF)
-            assert_before(
-                child,
-                ['KeyboardInterrupt'],
-            )
-
-
-# TODO: better error for "non-ideal" usage from the root actor.
-# -[ ] if called from an async scope emit a message that suggests
-#    using `await tractor.pause()` instead since it's less overhead
-#    (in terms of `greenback` and/or extra threads) and if it's from
-#    a sync scope suggest that usage must first call
-#    `ensure_portal()` in the (eventual parent) async calling scope?
-def test_sync_pause_from_bg_task_in_root_actor_():
-    '''
-    When used from the root actor, normally we can only implicitly
-    support `.pause_from_sync()` from the main-parent-task (that
-    opens the runtime via `open_root_actor()`) since `greenback`
-    requires a `.ensure_portal()` call per `trio.Task` where it is
-    used.
-
-    '''
-    ...
-
-# TODO: needs ANSI code stripping tho, see `assert_before()` # above!
-def test_correct_frames_below_hidden():
-    '''
-    Ensure that once a `tractor.pause()` enages, when the user
-    inputs a "next"/"n" command the actual next line steps
-    and that using a "step"/"s" into the next LOC, particuarly
-    `tractor` APIs, you can step down into that code.
-
-    '''
-    ...
-
-
-def test_cant_pause_from_paused_task():
-    '''
-    Pausing from with an already paused task should raise an error.
-
-    Normally this should only happen in practise while debugging the call stack of `tractor.pause()` itself, likely
-    by a `.pause()` line somewhere inside our runtime.
-
-    '''
-    ...
+    child.expect(pexpect.EOF)

tests/test_discovery.py

@@ -7,9 +7,7 @@ import platform
 from functools import partial
 import itertools
 
-import psutil
 import pytest
-import subprocess
 import tractor
 from tractor._testing import tractor_test
 import trio
@@ -28,7 +26,7 @@ async def test_reg_then_unreg(reg_addr):
         portal = await n.start_actor('actor', enable_modules=[__name__])
         uid = portal.channel.uid
 
-        async with tractor.get_registry(reg_addr) as aportal:
+        async with tractor.get_arbiter(*reg_addr) as aportal:
             # this local actor should be the arbiter
             assert actor is aportal.actor
 
@@ -154,25 +152,15 @@ async def unpack_reg(actor_or_portal):
 async def spawn_and_check_registry(
     reg_addr: tuple,
     use_signal: bool,
-    debug_mode: bool = False,
     remote_arbiter: bool = False,
     with_streaming: bool = False,
-    maybe_daemon: tuple[
-        subprocess.Popen,
-        psutil.Process,
-    ]|None = None,
 
 ) -> None:
 
-    if maybe_daemon:
-        popen, proc = maybe_daemon
-        # breakpoint()
-
     async with tractor.open_root_actor(
         registry_addrs=[reg_addr],
-        debug_mode=debug_mode,
     ):
-        async with tractor.get_registry(reg_addr) as portal:
+        async with tractor.get_arbiter(*reg_addr) as portal:
             # runtime needs to be up to call this
             actor = tractor.current_actor()
 
@@ -188,30 +176,28 @@ async def spawn_and_check_registry(
                 extra = 2  # local root actor + remote arbiter
 
             # ensure current actor is registered
-            registry: dict = await get_reg()
+            registry = await get_reg()
             assert actor.uid in registry
 
             try:
-                async with tractor.open_nursery() as an:
-                    async with trio.open_nursery(
-                        strict_exception_groups=False,
-                    ) as trion:
+                async with tractor.open_nursery() as n:
+                    async with trio.open_nursery() as trion:
 
                         portals = {}
                         for i in range(3):
                             name = f'a{i}'
                             if with_streaming:
-                                portals[name] = await an.start_actor(
+                                portals[name] = await n.start_actor(
                                     name=name, enable_modules=[__name__])
 
                             else:  # no streaming
-                                portals[name] = await an.run_in_actor(
+                                portals[name] = await n.run_in_actor(
                                     trio.sleep_forever, name=name)
 
                         # wait on last actor to come up
                         async with tractor.wait_for_actor(name):
                             registry = await get_reg()
-                            for uid in an._children:
+                            for uid in n._children:
                                 assert uid in registry
 
                         assert len(portals) + extra == len(registry)
@@ -244,7 +230,6 @@ async def spawn_and_check_registry(
 @pytest.mark.parametrize('use_signal', [False, True])
 @pytest.mark.parametrize('with_streaming', [False, True])
 def test_subactors_unregister_on_cancel(
-    debug_mode: bool,
     start_method,
     use_signal,
     reg_addr,
@@ -261,7 +246,6 @@ def test_subactors_unregister_on_cancel(
                 spawn_and_check_registry,
                 reg_addr,
                 use_signal,
-                debug_mode=debug_mode,
                 remote_arbiter=False,
                 with_streaming=with_streaming,
             ),
@@ -271,8 +255,7 @@ def test_subactors_unregister_on_cancel(
 @pytest.mark.parametrize('use_signal', [False, True])
 @pytest.mark.parametrize('with_streaming', [False, True])
 def test_subactors_unregister_on_cancel_remote_daemon(
-    daemon: subprocess.Popen,
-    debug_mode: bool,
+    daemon,
     start_method,
     use_signal,
     reg_addr,
@@ -288,13 +271,8 @@ def test_subactors_unregister_on_cancel_remote_daemon(
                 spawn_and_check_registry,
                 reg_addr,
                 use_signal,
-                debug_mode=debug_mode,
                 remote_arbiter=True,
                 with_streaming=with_streaming,
-                maybe_daemon=(
-                    daemon,
-                    psutil.Process(daemon.pid)
-                ),
             ),
         )
 
@@ -320,7 +298,7 @@ async def close_chans_before_nursery(
     async with tractor.open_root_actor(
         registry_addrs=[reg_addr],
     ):
-        async with tractor.get_registry(reg_addr) as aportal:
+        async with tractor.get_arbiter(*reg_addr) as aportal:
             try:
                 get_reg = partial(unpack_reg, aportal)
 
@@ -338,9 +316,7 @@ async def close_chans_before_nursery(
                         async with portal2.open_stream_from(
                             stream_forever
                         ) as agen2:
-                            async with trio.open_nursery(
-                                strict_exception_groups=False,
-                            ) as n:
+                            async with trio.open_nursery() as n:
                                 n.start_soon(streamer, agen1)
                                 n.start_soon(cancel, use_signal, .5)
                                 try:
@@ -393,7 +369,7 @@ def test_close_channel_explicit(
 
 @pytest.mark.parametrize('use_signal', [False, True])
 def test_close_channel_explicit_remote_arbiter(
-    daemon: subprocess.Popen,
+    daemon,
     start_method,
     use_signal,
     reg_addr,

tests/test_docs_examples.py

@@ -19,7 +19,7 @@ from tractor._testing import (
 @pytest.fixture
 def run_example_in_subproc(
     loglevel: str,
-    testdir: pytest.Pytester,
+    testdir,
     reg_addr: tuple[str, int],
 ):
 
@@ -66,9 +66,6 @@ def run_example_in_subproc(
         # due to backpressure!!!
         proc = testdir.popen(
             cmdargs,
-            stdin=subprocess.PIPE,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
             **kwargs,
         )
         assert not proc.returncode
@@ -84,36 +81,28 @@ def run_example_in_subproc(
 
     # walk yields: (dirpath, dirnames, filenames)
     [
-        (p[0], f)
-        for p in os.walk(examples_dir())
-        for f in p[2]
+        (p[0], f) for p in os.walk(examples_dir()) for f in p[2]
 
-        if (
-            '__' not in f
-            and f[0] != '_'
-            and 'debugging' not in p[0]
-            and 'integration' not in p[0]
-            and 'advanced_faults' not in p[0]
-            and 'multihost' not in p[0]
-        )
+        if '__' not in f
+        and f[0] != '_'
+        and 'debugging' not in p[0]
+        and 'integration' not in p[0]
+        and 'advanced_faults' not in p[0]
+        and 'multihost' not in p[0]
     ],
+
     ids=lambda t: t[1],
 )
-def test_example(
-    run_example_in_subproc,
-    example_script,
-):
-    '''
-    Load and run scripts from this repo's ``examples/`` dir as a user
+def test_example(run_example_in_subproc, example_script):
+    """Load and run scripts from this repo's ``examples/`` dir as a user
     would copy and pasing them into their editor.
 
     On windows a little more "finessing" is done to make
     ``multiprocessing`` play nice: we copy the ``__main__.py`` into the
     test directory and invoke the script as a module with ``python -m
     test_example``.
-
-    '''
-    ex_file: str = os.path.join(*example_script)
+    """
+    ex_file = os.path.join(*example_script)
 
     if 'rpc_bidir_streaming' in ex_file and sys.version_info < (3, 9):
         pytest.skip("2-way streaming example requires py3.9 async with syntax")
@@ -122,14 +111,10 @@ def test_example(
         code = ex.read()
 
         with run_example_in_subproc(code) as proc:
-            err = None
-            try:
-                if not proc.poll():
-                    _, err = proc.communicate(timeout=15)
-
-            except subprocess.TimeoutExpired as e:
-                proc.kill()
-                err = e.stderr
+            proc.wait()
+            err, _ = proc.stderr.read(), proc.stdout.read()
+            # print(f'STDERR: {err}')
+            # print(f'STDOUT: {out}')
 
             # if we get some gnarly output let's aggregate and raise
             if err:
@@ -143,8 +128,7 @@ def test_example(
                     # shouldn't eventually once we figure out what's
                     # a better way to be explicit about aio side
                     # cancels?
-                    and
-                    'asyncio.exceptions.CancelledError' not in last_error
+                    and 'asyncio.exceptions.CancelledError' not in last_error
                 ):
                     raise Exception(errmsg)
 

tests/test_ext_types_msgspec.py

@@ -1,946 +0,0 @@
-'''
-Low-level functional audits for our
-"capability based messaging"-spec feats.
-
-B~)
-
-'''
-from contextlib import (
-    contextmanager as cm,
-    # nullcontext,
-)
-import importlib
-from typing import (
-    Any,
-    Type,
-    Union,
-)
-
-from msgspec import (
-    # structs,
-    # msgpack,
-    Raw,
-    # Struct,
-    ValidationError,
-)
-import pytest
-import trio
-
-import tractor
-from tractor import (
-    Actor,
-    # _state,
-    MsgTypeError,
-    Context,
-)
-from tractor.msg import (
-    _codec,
-    _ctxvar_MsgCodec,
-    _exts,
-
-    NamespacePath,
-    MsgCodec,
-    MsgDec,
-    mk_codec,
-    mk_dec,
-    apply_codec,
-    current_codec,
-)
-from tractor.msg.types import (
-    log,
-    Started,
-    # _payload_msgs,
-    # PayloadMsg,
-    # mk_msg_spec,
-)
-from tractor.msg._ops import (
-    limit_plds,
-)
-
-def enc_nsp(obj: Any) -> Any:
-    actor: Actor = tractor.current_actor(
-        err_on_no_runtime=False,
-    )
-    uid: tuple[str, str]|None = None if not actor else actor.uid
-    print(f'{uid} ENC HOOK')
-
-    match obj:
-        # case NamespacePath()|str():
-        case NamespacePath():
-            encoded: str = str(obj)
-            print(
-                f'----- ENCODING `NamespacePath` as `str` ------\n'
-                f'|_obj:{type(obj)!r} = {obj!r}\n'
-                f'|_encoded: str = {encoded!r}\n'
-            )
-            # if type(obj) != NamespacePath:
-            #     breakpoint()
-            return encoded
-        case _:
-            logmsg: str = (
-                f'{uid}\n'
-                'FAILED ENCODE\n'
-                f'obj-> `{obj}: {type(obj)}`\n'
-            )
-            raise NotImplementedError(logmsg)
-
-
-def dec_nsp(
-    obj_type: Type,
-    obj: Any,
-
-) -> Any:
-    # breakpoint()
-    actor: Actor = tractor.current_actor(
-        err_on_no_runtime=False,
-    )
-    uid: tuple[str, str]|None = None if not actor else actor.uid
-    print(
-        f'{uid}\n'
-        'CUSTOM DECODE\n'
-        f'type-arg-> {obj_type}\n'
-        f'obj-arg-> `{obj}`: {type(obj)}\n'
-    )
-    nsp = None
-    # XXX, never happens right?
-    if obj_type is Raw:
-        breakpoint()
-
-    if (
-        obj_type is NamespacePath
-        and isinstance(obj, str)
-        and ':' in obj
-    ):
-        nsp = NamespacePath(obj)
-        # TODO: we could built a generic handler using
-        # JUST matching the obj_type part?
-        # nsp = obj_type(obj)
-
-    if nsp:
-        print(f'Returning NSP instance: {nsp}')
-        return nsp
-
-    logmsg: str = (
-        f'{uid}\n'
-        'FAILED DECODE\n'
-        f'type-> {obj_type}\n'
-        f'obj-arg-> `{obj}`: {type(obj)}\n\n'
-        f'current codec:\n'
-        f'{current_codec()}\n'
-    )
-    # TODO: figure out the ignore subsys for this!
-    # -[ ] option whether to defense-relay backc the msg
-    #   inside an `Invalid`/`Ignore`
-    # -[ ] how to make this handling pluggable such that a
-    #   `Channel`/`MsgTransport` can intercept and process
-    #   back msgs either via exception handling or some other
-    #   signal?
-    log.warning(logmsg)
-    # NOTE: this delivers the invalid
-    # value up to `msgspec`'s decoding
-    # machinery for error raising.
-    return obj
-    # raise NotImplementedError(logmsg)
-
-
-def ex_func(*args):
-    '''
-    A mod level func we can ref and load via our `NamespacePath`
-    python-object pointer `str` subtype.
-
-    '''
-    print(f'ex_func({args})')
-
-
-@pytest.mark.parametrize(
-    'add_codec_hooks',
-    [
-        True,
-        False,
-    ],
-    ids=['use_codec_hooks', 'no_codec_hooks'],
-)
-def test_custom_extension_types(
-    debug_mode: bool,
-    add_codec_hooks: bool
-):
-    '''
-    Verify that a `MsgCodec` (used for encoding all outbound IPC msgs
-    and decoding all inbound `PayloadMsg`s) and a paired `MsgDec`
-    (used for decoding the `PayloadMsg.pld: Raw` received within a given
-    task's ipc `Context` scope) can both send and receive "extension types"
-    as supported via custom converter hooks passed to `msgspec`.
-
-    '''
-    nsp_pld_dec: MsgDec = mk_dec(
-        spec=None,  # ONLY support the ext type
-        dec_hook=dec_nsp if add_codec_hooks else None,
-        ext_types=[NamespacePath],
-    )
-    nsp_codec: MsgCodec = mk_codec(
-        # ipc_pld_spec=Raw,  # default!
-
-        # NOTE XXX: the encode hook MUST be used no matter what since
-        # our `NamespacePath` is not any of a `Any` native type nor
-        # a `msgspec.Struct` subtype - so `msgspec` has no way to know
-        # how to encode it unless we provide the custom hook.
-        #
-        # AGAIN that is, regardless of whether we spec an
-        # `Any`-decoded-pld the enc has no knowledge (by default)
-        # how to enc `NamespacePath` (nsp), so we add a custom
-        # hook to do that ALWAYS.
-        enc_hook=enc_nsp if add_codec_hooks else None,
-
-        # XXX NOTE: pretty sure this is mutex with the `type=` to
-        # `Decoder`? so it won't work in tandem with the
-        # `ipc_pld_spec` passed above?
-        ext_types=[NamespacePath],
-
-        # TODO? is it useful to have the `.pld` decoded *prior* to
-        # the `PldRx`?? like perf or mem related?
-        # ext_dec=nsp_pld_dec,
-    )
-    if add_codec_hooks:
-        assert nsp_codec.dec.dec_hook is None
-
-        # TODO? if we pass `ext_dec` above?
-        # assert nsp_codec.dec.dec_hook is dec_nsp
-
-        assert nsp_codec.enc.enc_hook is enc_nsp
-
-    nsp = NamespacePath.from_ref(ex_func)
-
-    try:
-        nsp_bytes: bytes = nsp_codec.encode(nsp)
-        nsp_rt_sin_msg = nsp_pld_dec.decode(nsp_bytes)
-        nsp_rt_sin_msg.load_ref() is ex_func
-    except TypeError:
-        if not add_codec_hooks:
-            pass
-
-    try:
-        msg_bytes: bytes = nsp_codec.encode(
-            Started(
-                cid='cid',
-                pld=nsp,
-            )
-        )
-        # since the ext-type obj should also be set as the msg.pld
-        assert nsp_bytes in msg_bytes
-        started_rt: Started = nsp_codec.decode(msg_bytes)
-        pld: Raw = started_rt.pld
-        assert isinstance(pld, Raw)
-        nsp_rt: NamespacePath = nsp_pld_dec.decode(pld)
-        assert isinstance(nsp_rt, NamespacePath)
-        # in obj comparison terms they should be the same
-        assert nsp_rt == nsp
-        # ensure we've decoded to ext type!
-        assert nsp_rt.load_ref() is ex_func
-
-    except TypeError:
-        if not add_codec_hooks:
-            pass
-
-@tractor.context
-async def sleep_forever_in_sub(
-    ctx: Context,
-) -> None:
-    await trio.sleep_forever()
-
-
-def mk_custom_codec(
-    add_hooks: bool,
-
-) -> tuple[
-    MsgCodec,  # encode to send
-    MsgDec,  # pld receive-n-decode
-]:
-    '''
-    Create custom `msgpack` enc/dec-hooks and set a `Decoder`
-    which only loads `pld_spec` (like `NamespacePath`) types.
-
-    '''
-
-    # XXX NOTE XXX: despite defining `NamespacePath` as a type
-    # field on our `PayloadMsg.pld`, we still need a enc/dec_hook() pair
-    # to cast to/from that type on the wire. See the docs:
-    # https://jcristharif.com/msgspec/extending.html#mapping-to-from-native-types
-
-    # if pld_spec is Any:
-    #     pld_spec = Raw
-
-    nsp_codec: MsgCodec = mk_codec(
-        # ipc_pld_spec=Raw,  # default!
-
-        # NOTE XXX: the encode hook MUST be used no matter what since
-        # our `NamespacePath` is not any of a `Any` native type nor
-        # a `msgspec.Struct` subtype - so `msgspec` has no way to know
-        # how to encode it unless we provide the custom hook.
-        #
-        # AGAIN that is, regardless of whether we spec an
-        # `Any`-decoded-pld the enc has no knowledge (by default)
-        # how to enc `NamespacePath` (nsp), so we add a custom
-        # hook to do that ALWAYS.
-        enc_hook=enc_nsp if add_hooks else None,
-
-        # XXX NOTE: pretty sure this is mutex with the `type=` to
-        # `Decoder`? so it won't work in tandem with the
-        # `ipc_pld_spec` passed above?
-        ext_types=[NamespacePath],
-    )
-    # dec_hook=dec_nsp if add_hooks else None,
-    return nsp_codec
-
-
-@pytest.mark.parametrize(
-    'limit_plds_args',
-    [
-        (
-            {'dec_hook': None, 'ext_types': None},
-            None,
-        ),
-        (
-            {'dec_hook': dec_nsp, 'ext_types': None},
-            TypeError,
-        ),
-        (
-            {'dec_hook': dec_nsp, 'ext_types': [NamespacePath]},
-            None,
-        ),
-        (
-            {'dec_hook': dec_nsp, 'ext_types': [NamespacePath|None]},
-            None,
-        ),
-    ],
-    ids=[
-        'no_hook_no_ext_types',
-        'only_hook',
-        'hook_and_ext_types',
-        'hook_and_ext_types_w_null',
-    ]
-)
-def test_pld_limiting_usage(
-    limit_plds_args: tuple[dict, Exception|None],
-):
-    '''
-    Verify `dec_hook()` and `ext_types` need to either both be
-    provided or we raise a explanator type-error.
-
-    '''
-    kwargs, maybe_err = limit_plds_args
-    async def main():
-        async with tractor.open_nursery() as an:  # just to open runtime
-
-            # XXX SHOULD NEVER WORK outside an ipc ctx scope!
-            try:
-                with limit_plds(**kwargs):
-                    pass
-            except RuntimeError:
-                pass
-
-            p: tractor.Portal = await an.start_actor(
-                'sub',
-                enable_modules=[__name__],
-            )
-            async with (
-                p.open_context(
-                    sleep_forever_in_sub
-                ) as (ctx, first),
-            ):
-                try:
-                    with limit_plds(**kwargs):
-                        pass
-                except maybe_err as exc:
-                    assert type(exc) is maybe_err
-                    pass
-
-
-def chk_codec_applied(
-    expect_codec: MsgCodec|None,
-    enter_value: MsgCodec|None = None,
-
-) -> MsgCodec:
-    '''
-    buncha sanity checks ensuring that the IPC channel's
-    context-vars are set to the expected codec and that are
-    ctx-var wrapper APIs match the same.
-
-    '''
-    # TODO: play with tricyle again, bc this is supposed to work
-    # the way we want?
-    #
-    # TreeVar
-    # task: trio.Task = trio.lowlevel.current_task()
-    # curr_codec = _ctxvar_MsgCodec.get_in(task)
-
-    # ContextVar
-    # task_ctx: Context = task.context
-    # assert _ctxvar_MsgCodec in task_ctx
-    # curr_codec: MsgCodec = task.context[_ctxvar_MsgCodec]
-    if expect_codec is None:
-        assert enter_value is None
-        return
-
-    # NOTE: currently we use this!
-    # RunVar
-    curr_codec: MsgCodec = current_codec()
-    last_read_codec = _ctxvar_MsgCodec.get()
-    # assert curr_codec is last_read_codec
-
-    assert (
-        (same_codec := expect_codec) is
-        # returned from `mk_codec()`
-
-        # yielded value from `apply_codec()`
-
-        # read from current task's `contextvars.Context`
-        curr_codec is
-        last_read_codec
-
-        # the default `msgspec` settings
-        is not _codec._def_msgspec_codec
-        is not _codec._def_tractor_codec
-    )
-
-    if enter_value:
-        assert enter_value is same_codec
-
-
-@tractor.context
-async def send_back_values(
-    ctx: Context,
-    rent_pld_spec_type_strs: list[str],
-    add_hooks: bool,
-
-) -> None:
-    '''
-    Setup up a custom codec to load instances of `NamespacePath`
-    and ensure we can round trip a func ref with our parent.
-
-    '''
-    uid: tuple = tractor.current_actor().uid
-
-    # init state in sub-actor should be default
-    chk_codec_applied(
-        expect_codec=_codec._def_tractor_codec,
-    )
-
-    # load pld spec from input str
-    rent_pld_spec = _exts.dec_type_union(
-        rent_pld_spec_type_strs,
-        mods=[
-            importlib.import_module(__name__),
-        ],
-    )
-    rent_pld_spec_types: set[Type] = _codec.unpack_spec_types(
-        rent_pld_spec,
-    )
-
-    # ONLY add ext-hooks if the rent specified a non-std type!
-    add_hooks: bool = (
-        NamespacePath in rent_pld_spec_types
-        and
-        add_hooks
-    )
-
-    # same as on parent side config.
-    nsp_codec: MsgCodec|None = None
-    if add_hooks:
-        nsp_codec = mk_codec(
-            enc_hook=enc_nsp,
-            ext_types=[NamespacePath],
-        )
-
-    with (
-        maybe_apply_codec(nsp_codec) as codec,
-        limit_plds(
-            rent_pld_spec,
-            dec_hook=dec_nsp if add_hooks else None,
-            ext_types=[NamespacePath]  if add_hooks else None,
-        ) as pld_dec,
-    ):
-        # ?XXX? SHOULD WE NOT be swapping the global codec since it
-        # breaks `Context.started()` roundtripping checks??
-        chk_codec_applied(
-            expect_codec=nsp_codec,
-            enter_value=codec,
-        )
-
-        # ?TODO, mismatch case(s)?
-        #
-        # ensure pld spec matches on both sides
-        ctx_pld_dec: MsgDec = ctx._pld_rx._pld_dec
-        assert pld_dec is ctx_pld_dec
-        child_pld_spec: Type = pld_dec.spec
-        child_pld_spec_types: set[Type] = _codec.unpack_spec_types(
-            child_pld_spec,
-        )
-        assert (
-            child_pld_spec_types.issuperset(
-                rent_pld_spec_types
-            )
-        )
-
-        # ?TODO, try loop for each of the types in pld-superset?
-        #
-        # for send_value in [
-        #     nsp,
-        #     str(nsp),
-        #     None,
-        # ]:
-        nsp = NamespacePath.from_ref(ex_func)
-        try:
-            print(
-                f'{uid}: attempting to `.started({nsp})`\n'
-                f'\n'
-                f'rent_pld_spec: {rent_pld_spec}\n'
-                f'child_pld_spec: {child_pld_spec}\n'
-                f'codec: {codec}\n'
-            )
-            # await tractor.pause()
-            await ctx.started(nsp)
-
-        except tractor.MsgTypeError as _mte:
-            mte = _mte
-
-            # false -ve case
-            if add_hooks:
-                raise RuntimeError(
-                    f'EXPECTED to `.started()` value given spec ??\n\n'
-                    f'child_pld_spec -> {child_pld_spec}\n'
-                    f'value = {nsp}: {type(nsp)}\n'
-                )
-
-            # true -ve case
-            raise mte
-
-        # TODO: maybe we should add our own wrapper error so as to
-        # be interchange-lib agnostic?
-        # -[ ] the error type is wtv is raised from the hook so we
-        #   could also require a type-class of errors for
-        #   indicating whether the hook-failure can be handled by
-        #   a nasty-dialog-unprot sub-sys?
-        except TypeError as typerr:
-            # false -ve
-            if add_hooks:
-                raise RuntimeError('Should have been able to send `nsp`??')
-
-            # true -ve
-            print('Failed to send `nsp` due to no ext hooks set!')
-            raise typerr
-
-        # now try sending a set of valid and invalid plds to ensure
-        # the pld spec is respected.
-        sent: list[Any] = []
-        async with ctx.open_stream() as ipc:
-            print(
-                f'{uid}: streaming all pld types to rent..'
-            )
-
-            # for send_value, expect_send in iter_send_val_items:
-            for send_value in [
-                nsp,
-                str(nsp),
-                None,
-            ]:
-                send_type: Type = type(send_value)
-                print(
-                    f'{uid}: SENDING NEXT pld\n'
-                    f'send_type: {send_type}\n'
-                    f'send_value: {send_value}\n'
-                )
-                try:
-                    await ipc.send(send_value)
-                    sent.append(send_value)
-
-                except ValidationError as valerr:
-                    print(f'{uid} FAILED TO SEND {send_value}!')
-
-                    # false -ve
-                    if add_hooks:
-                        raise RuntimeError(
-                            f'EXPECTED to roundtrip value given spec:\n'
-                            f'rent_pld_spec -> {rent_pld_spec}\n'
-                            f'child_pld_spec -> {child_pld_spec}\n'
-                            f'value = {send_value}: {send_type}\n'
-                        )
-
-                    # true -ve
-                    raise valerr
-                    # continue
-
-            else:
-                print(
-                    f'{uid}: finished sending all values\n'
-                    'Should be exiting stream block!\n'
-                )
-
-        print(f'{uid}: exited streaming block!')
-
-
-
-@cm
-def maybe_apply_codec(codec: MsgCodec|None) -> MsgCodec|None:
-    if codec is None:
-        yield None
-        return
-
-    with apply_codec(codec) as codec:
-        yield codec
-
-
-@pytest.mark.parametrize(
-    'pld_spec',
-    [
-        Any,
-        NamespacePath,
-        NamespacePath|None,  # the "maybe" spec Bo
-    ],
-    ids=[
-        'any_type',
-        'only_nsp_ext',
-        'maybe_nsp_ext',
-    ]
-)
-@pytest.mark.parametrize(
-    'add_hooks',
-    [
-        True,
-        False,
-    ],
-    ids=[
-        'use_codec_hooks',
-        'no_codec_hooks',
-    ],
-)
-def test_ext_types_over_ipc(
-    debug_mode: bool,
-    pld_spec: Union[Type],
-    add_hooks: bool,
-):
-    '''
-    Ensure we can support extension types coverted using
-    `enc/dec_hook()`s passed to the `.msg.limit_plds()` API
-    and that sane errors happen when we try do the same without
-    the codec hooks.
-
-    '''
-    pld_types: set[Type] = _codec.unpack_spec_types(pld_spec)
-
-    async def main():
-
-        # sanity check the default pld-spec beforehand
-        chk_codec_applied(
-            expect_codec=_codec._def_tractor_codec,
-        )
-
-        # extension type we want to send as msg payload
-        nsp = NamespacePath.from_ref(ex_func)
-
-        # ^NOTE, 2 cases:
-        # - codec hooks noto added -> decode nsp as `str`
-        # - codec with hooks -> decode nsp as `NamespacePath`
-        nsp_codec: MsgCodec|None = None
-        if (
-            NamespacePath in pld_types
-            and
-            add_hooks
-        ):
-            nsp_codec = mk_codec(
-                enc_hook=enc_nsp,
-                ext_types=[NamespacePath],
-            )
-
-        async with tractor.open_nursery(
-            debug_mode=debug_mode,
-        ) as an:
-            p: tractor.Portal = await an.start_actor(
-                'sub',
-                enable_modules=[__name__],
-            )
-            with (
-                maybe_apply_codec(nsp_codec) as codec,
-            ):
-                chk_codec_applied(
-                    expect_codec=nsp_codec,
-                    enter_value=codec,
-                )
-                rent_pld_spec_type_strs: list[str] = _exts.enc_type_union(pld_spec)
-
-                # XXX should raise an mte (`MsgTypeError`)
-                # when `add_hooks == False` bc the input
-                # `expect_ipc_send` kwarg has a nsp which can't be
-                # serialized!
-                #
-                # TODO:can we ensure this happens from the
-                # `Return`-side (aka the sub) as well?
-                try:
-                    ctx: tractor.Context
-                    ipc: tractor.MsgStream
-                    async with (
-
-                        # XXX should raise an mte (`MsgTypeError`)
-                        # when `add_hooks == False`..
-                        p.open_context(
-                            send_back_values,
-                            # expect_debug=debug_mode,
-                            rent_pld_spec_type_strs=rent_pld_spec_type_strs,
-                            add_hooks=add_hooks,
-                            # expect_ipc_send=expect_ipc_send,
-                        ) as (ctx, first),
-
-                        ctx.open_stream() as ipc,
-                    ):
-                        with (
-                            limit_plds(
-                                pld_spec,
-                                dec_hook=dec_nsp if add_hooks else None,
-                                ext_types=[NamespacePath]  if add_hooks else None,
-                            ) as pld_dec,
-                        ):
-                            ctx_pld_dec: MsgDec = ctx._pld_rx._pld_dec
-                            assert pld_dec is ctx_pld_dec
-
-                            # if (
-                            #     not add_hooks
-                            #     and
-                            #     NamespacePath in 
-                            # ):
-                            #     pytest.fail('ctx should fail to open without custom enc_hook!?')
-
-                            await ipc.send(nsp)
-                            nsp_rt = await ipc.receive()
-
-                            assert nsp_rt == nsp
-                            assert nsp_rt.load_ref() is ex_func
-
-                # this test passes bc we can go no further!
-                except MsgTypeError as mte:
-                    # if not add_hooks:
-                    #     # teardown nursery
-                    #     await p.cancel_actor()
-                        # return
-
-                    raise mte
-
-            await p.cancel_actor()
-
-    if (
-        NamespacePath in pld_types
-        and
-        add_hooks
-    ):
-        trio.run(main)
-
-    else:
-        with pytest.raises(
-            expected_exception=tractor.RemoteActorError,
-        ) as excinfo:
-            trio.run(main)
-
-        exc = excinfo.value
-        # bc `.started(nsp: NamespacePath)` will raise
-        assert exc.boxed_type is TypeError
-
-
-# def chk_pld_type(
-#     payload_spec: Type[Struct]|Any,
-#     pld: Any,
-
-#     expect_roundtrip: bool|None = None,
-
-# ) -> bool:
-
-#     pld_val_type: Type = type(pld)
-
-#     # TODO: verify that the overridden subtypes
-#     # DO NOT have modified type-annots from original!
-#     # 'Start',  .pld: FuncSpec
-#     # 'StartAck',  .pld: IpcCtxSpec
-#     # 'Stop',  .pld: UNSEt
-#     # 'Error',  .pld: ErrorData
-
-#     codec: MsgCodec = mk_codec(
-#         # NOTE: this ONLY accepts `PayloadMsg.pld` fields of a specified
-#         # type union.
-#         ipc_pld_spec=payload_spec,
-#     )
-
-#     # make a one-off dec to compare with our `MsgCodec` instance
-#     # which does the below `mk_msg_spec()` call internally
-#     ipc_msg_spec: Union[Type[Struct]]
-#     msg_types: list[PayloadMsg[payload_spec]]
-#     (
-#         ipc_msg_spec,
-#         msg_types,
-#     ) = mk_msg_spec(
-#         payload_type_union=payload_spec,
-#     )
-#     _enc = msgpack.Encoder()
-#     _dec = msgpack.Decoder(
-#         type=ipc_msg_spec or Any,  # like `PayloadMsg[Any]`
-#     )
-
-#     assert (
-#         payload_spec
-#         ==
-#         codec.pld_spec
-#     )
-
-#     # assert codec.dec == dec
-#     #
-#     # ^-XXX-^ not sure why these aren't "equal" but when cast
-#     # to `str` they seem to match ?? .. kk
-
-#     assert (
-#         str(ipc_msg_spec)
-#         ==
-#         str(codec.msg_spec)
-#         ==
-#         str(_dec.type)
-#         ==
-#         str(codec.dec.type)
-#     )
-
-#     # verify the boxed-type for all variable payload-type msgs.
-#     if not msg_types:
-#         breakpoint()
-
-#     roundtrip: bool|None = None
-#     pld_spec_msg_names: list[str] = [
-#         td.__name__ for td in _payload_msgs
-#     ]
-#     for typedef in msg_types:
-
-#         skip_runtime_msg: bool = typedef.__name__ not in pld_spec_msg_names
-#         if skip_runtime_msg:
-#             continue
-
-#         pld_field = structs.fields(typedef)[1]
-#         assert pld_field.type is payload_spec # TODO-^ does this need to work to get all subtypes to adhere?
-
-#         kwargs: dict[str, Any] = {
-#             'cid': '666',
-#             'pld': pld,
-#         }
-#         enc_msg: PayloadMsg = typedef(**kwargs)
-
-#         _wire_bytes: bytes = _enc.encode(enc_msg)
-#         wire_bytes: bytes = codec.enc.encode(enc_msg)
-#         assert _wire_bytes == wire_bytes
-
-#         ve: ValidationError|None = None
-#         try:
-#             dec_msg = codec.dec.decode(wire_bytes)
-#             _dec_msg = _dec.decode(wire_bytes)
-
-#             # decoded msg and thus payload should be exactly same!
-#             assert (roundtrip := (
-#                 _dec_msg
-#                 ==
-#                 dec_msg
-#                 ==
-#                 enc_msg
-#             ))
-
-#             if (
-#                 expect_roundtrip is not None
-#                 and expect_roundtrip != roundtrip
-#             ):
-#                 breakpoint()
-
-#             assert (
-#                 pld
-#                 ==
-#                 dec_msg.pld
-#                 ==
-#                 enc_msg.pld
-#             )
-#             # assert (roundtrip := (_dec_msg == enc_msg))
-
-#         except ValidationError as _ve:
-#             ve = _ve
-#             roundtrip: bool = False
-#             if pld_val_type is payload_spec:
-#                 raise ValueError(
-#                    'Got `ValidationError` despite type-var match!?\n'
-#                     f'pld_val_type: {pld_val_type}\n'
-#                     f'payload_type: {payload_spec}\n'
-#                 ) from ve
-
-#             else:
-#                 # ow we good cuz the pld spec mismatched.
-#                 print(
-#                     'Got expected `ValidationError` since,\n'
-#                     f'{pld_val_type} is not {payload_spec}\n'
-#                 )
-#         else:
-#             if (
-#                 payload_spec is not Any
-#                 and
-#                 pld_val_type is not payload_spec
-#             ):
-#                 raise ValueError(
-#                    'DID NOT `ValidationError` despite expected type match!?\n'
-#                     f'pld_val_type: {pld_val_type}\n'
-#                     f'payload_type: {payload_spec}\n'
-#                 )
-
-#     # full code decode should always be attempted!
-#     if roundtrip is None:
-#         breakpoint()
-
-#     return roundtrip
-
-
-# ?TODO? maybe remove since covered in the newer `test_pldrx_limiting`
-# via end-2-end testing of all this?
-# -[ ] IOW do we really NEED this lowlevel unit testing?
-#
-# def test_limit_msgspec(
-#     debug_mode: bool,
-# ):
-#     '''
-#     Internals unit testing to verify that type-limiting an IPC ctx's
-#     msg spec with `Pldrx.limit_plds()` results in various
-#     encapsulated `msgspec` object settings and state.
-
-#     '''
-#     async def main():
-#         async with tractor.open_root_actor(
-#             debug_mode=debug_mode,
-#         ):
-#             # ensure we can round-trip a boxing `PayloadMsg`
-#             assert chk_pld_type(
-#                 payload_spec=Any,
-#                 pld=None,
-#                 expect_roundtrip=True,
-#             )
-
-#             # verify that a mis-typed payload value won't decode
-#             assert not chk_pld_type(
-#                 payload_spec=int,
-#                 pld='doggy',
-#             )
-
-#             # parametrize the boxed `.pld` type as a custom-struct
-#             # and ensure that parametrization propagates
-#             # to all payload-msg-spec-able subtypes!
-#             class CustomPayload(Struct):
-#                 name: str
-#                 value: Any
-
-#             assert not chk_pld_type(
-#                 payload_spec=CustomPayload,
-#                 pld='doggy',
-#             )
-
-#             assert chk_pld_type(
-#                 payload_spec=CustomPayload,
-#                 pld=CustomPayload(name='doggy', value='urmom')
-#             )
-
-#             # yah, we can `.pause_from_sync()` now!
-#             # breakpoint()
-
-#     trio.run(main)

tests/test_inter_peer_cancellation.py

@@ -55,10 +55,9 @@ from tractor._testing import (
 
 
 @tractor.context
-async def open_stream_then_sleep_forever(
+async def sleep_forever(
     ctx: Context,
     expect_ctxc: bool = False,
-
 ) -> None:
     '''
     Sync the context, open a stream then just sleep.
@@ -68,10 +67,6 @@ async def open_stream_then_sleep_forever(
     '''
     try:
         await ctx.started()
-
-        # NOTE: the below means this child will send a `Stop`
-        # to it's parent-side task despite that side never
-        # opening a stream itself.
         async with ctx.open_stream():
             await trio.sleep_forever()
 
@@ -105,7 +100,7 @@ async def error_before_started(
     '''
     async with tractor.wait_for_actor('sleeper') as p2:
         async with (
-            p2.open_context(open_stream_then_sleep_forever) as (peer_ctx, first),
+            p2.open_context(sleep_forever) as (peer_ctx, first),
             peer_ctx.open_stream(),
         ):
             # NOTE: this WAS inside an @acm body but i factored it
@@ -170,7 +165,7 @@ def test_do_not_swallow_error_before_started_by_remote_contextcancelled(
         trio.run(main)
 
     rae = excinfo.value
-    assert rae.boxed_type is TypeError
+    assert rae.boxed_type == TypeError
 
 
 @tractor.context
@@ -190,10 +185,6 @@ async def sleep_a_bit_then_cancel_peer(
         await trio.sleep(cancel_after)
         await peer.cancel_actor()
 
-        # such that we're cancelled by our rent ctx-task
-        await trio.sleep(3)
-        print('CANCELLER RETURNING!')
-
 
 @tractor.context
 async def stream_ints(
@@ -209,13 +200,9 @@ async def stream_ints(
 @tractor.context
 async def stream_from_peer(
     ctx: Context,
-    debug_mode: bool,
     peer_name: str = 'sleeper',
 ) -> None:
 
-    # sanity
-    assert tractor._state.debug_mode() == debug_mode
-
     peer: Portal
     try:
         async with (
@@ -249,54 +236,20 @@ async def stream_from_peer(
                 assert msg is not None
                 print(msg)
 
-    # NOTE: cancellation of the (sleeper) peer should always cause
-    # a `ContextCancelled` raise in this streaming actor.
-    except ContextCancelled as _ctxc:
-        ctxc = _ctxc
+    # NOTE: cancellation of the (sleeper) peer should always
+    # cause a `ContextCancelled` raise in this streaming
+    # actor.
+    except ContextCancelled as ctxc:
+        ctxerr = ctxc
 
-        # print("TRYING TO ENTER PAUSSE!!!")
-        # await tractor.pause(shield=True)
-        re: ContextCancelled = peer_ctx._remote_error
-
-        # XXX YES XXX, remote error should be unpacked only once!
-        assert (
-            re
-            is
-            peer_ctx.maybe_error
-            is
-            ctxc
-            is
-            peer_ctx._local_error
-        )
-        # NOTE: these errors should all match!
-        #   ------ - ------
-        # XXX [2024-05-03] XXX
-        #   ------ - ------
-        # broke this due to a re-raise inside `.msg._ops.drain_to_final_msg()`
-        # where the `Error()` msg was directly raising the ctxc
-        # instead of just returning up to the caller inside
-        # `Context.return()` which would results in a diff instance of
-        # the same remote error bubbling out above vs what was
-        # already unpacked and set inside `Context.
-        assert (
-            peer_ctx._remote_error.msgdata
-            ==
-            ctxc.msgdata
-        )
-        # ^-XXX-^ notice the data is of course the exact same.. so
-        # the above larger assert makes sense to also always be true!
-
-        # XXX YES XXX, bc should be exact same msg instances
-        assert peer_ctx._remote_error._ipc_msg is ctxc._ipc_msg
-
-        # XXX NO XXX, bc new one always created for property accesss
-        assert peer_ctx._remote_error.ipc_msg != ctxc.ipc_msg
+        assert peer_ctx._remote_error is ctxerr
+        assert peer_ctx._remote_error.msgdata == ctxerr.msgdata
 
         # the peer ctx is the canceller even though it's canceller
         # is the "canceller" XD
         assert peer_name in peer_ctx.canceller
 
-        assert "canceller" in ctxc.canceller
+        assert "canceller" in ctxerr.canceller
 
         # caller peer should not be the cancel requester
         assert not ctx.cancel_called
@@ -320,13 +273,12 @@ async def stream_from_peer(
 
         # TODO / NOTE `.canceller` won't have been set yet
         # here because that machinery is inside
-        # `Portal.open_context().__aexit__()` BUT, if we had
+        # `.open_context().__aexit__()` BUT, if we had
         # a way to know immediately (from the last
         # checkpoint) that cancellation was due to
         # a remote, we COULD assert this here..see,
         # https://github.com/goodboy/tractor/issues/368
         #
-        # await tractor.pause()
         # assert 'canceller' in ctx.canceller
 
         # root/parent actor task should NEVER HAVE cancelled us!
@@ -430,13 +382,12 @@ def test_peer_canceller(
             try:
                 async with (
                     sleeper.open_context(
-                        open_stream_then_sleep_forever,
+                        sleep_forever,
                         expect_ctxc=True,
                     ) as (sleeper_ctx, sent),
 
                     just_caller.open_context(
                         stream_from_peer,
-                        debug_mode=debug_mode,
                     ) as (caller_ctx, sent),
 
                     canceller.open_context(
@@ -462,11 +413,10 @@ def test_peer_canceller(
 
                     # should always raise since this root task does
                     # not request the sleeper cancellation ;)
-                    except ContextCancelled as _ctxc:
-                        ctxc = _ctxc
+                    except ContextCancelled as ctxerr:
                         print(
                             'CAUGHT REMOTE CONTEXT CANCEL\n\n'
-                            f'{ctxc}\n'
+                            f'{ctxerr}\n'
                         )
 
                         # canceller and caller peers should not
@@ -477,7 +427,7 @@ def test_peer_canceller(
                         # we were not the actor, our peer was
                         assert not sleeper_ctx.cancel_acked
 
-                        assert ctxc.canceller[0] == 'canceller'
+                        assert ctxerr.canceller[0] == 'canceller'
 
                         # XXX NOTE XXX: since THIS `ContextCancelled`
                         # HAS NOT YET bubbled up to the
@@ -488,7 +438,7 @@ def test_peer_canceller(
 
                         # CASE_1: error-during-ctxc-handling,
                         if error_during_ctxerr_handling:
-                            raise RuntimeError('Simulated RTE re-raise during ctxc handling')
+                            raise RuntimeError('Simulated error during teardown')
 
                         # CASE_2: standard teardown inside in `.open_context()` block
                         raise
@@ -553,9 +503,6 @@ def test_peer_canceller(
                 #   should be cancelled by US.
                 #
                 if error_during_ctxerr_handling:
-                    print(f'loc_err: {_loc_err}\n')
-                    assert isinstance(loc_err, RuntimeError)
-
                     # since we do a rte reraise above, the
                     # `.open_context()` error handling should have
                     # raised a local rte, thus the internal
@@ -564,6 +511,9 @@ def test_peer_canceller(
                     # a `trio.Cancelled` due to a local
                     # `._scope.cancel()` call.
                     assert not sleeper_ctx._scope.cancelled_caught
+
+                    assert isinstance(loc_err, RuntimeError)
+                    print(f'_loc_err: {_loc_err}\n')
                     # assert sleeper_ctx._local_error is _loc_err
                     # assert sleeper_ctx._local_error is _loc_err
                     assert not (
@@ -600,12 +550,9 @@ def test_peer_canceller(
 
                         else:  # the other 2 ctxs
                             assert (
-                                isinstance(re, ContextCancelled)
-                                and (
-                                    re.canceller
-                                    ==
-                                    canceller.channel.uid
-                                )
+                                re.canceller
+                                ==
+                                canceller.channel.uid
                             )
 
                     # since the sleeper errors while handling a
@@ -854,7 +801,8 @@ async def serve_subactors(
     async with open_nursery() as an:
 
         # sanity
-        assert tractor._state.debug_mode() == debug_mode
+        if debug_mode:
+            assert tractor._state.debug_mode()
 
         await ctx.started(peer_name)
         async with ctx.open_stream() as ipc:
@@ -871,7 +819,7 @@ async def serve_subactors(
                 )
                 await ipc.send((
                     peer.chan.uid,
-                    peer.chan.raddr.unwrap(),
+                    peer.chan.raddr,
                 ))
 
         print('Spawner exiting spawn serve loop!')
@@ -1133,6 +1081,7 @@ def test_peer_spawns_and_cancels_service_subactor(
                             '-> root checking `client_ctx.result()`,\n'
                             f'-> checking that sub-spawn {peer_name} is down\n'
                         )
+                    # else:
 
                     try:
                         res = await client_ctx.result(hide_tb=False)

tests/test_local.py

@@ -38,7 +38,7 @@ async def test_self_is_registered_localportal(reg_addr):
     "Verify waiting on the arbiter to register itself using a local portal."
     actor = tractor.current_actor()
     assert actor.is_arbiter
-    async with tractor.get_registry(reg_addr) as portal:
+    async with tractor.get_arbiter(*reg_addr) as portal:
         assert isinstance(portal, tractor._portal.LocalPortal)
 
         with trio.fail_after(0.2):

tests/test_multi_program.py

@@ -32,7 +32,7 @@ def test_abort_on_sigint(daemon):
 @tractor_test
 async def test_cancel_remote_arbiter(daemon, reg_addr):
     assert not tractor.current_actor().is_arbiter
-    async with tractor.get_registry(reg_addr) as portal:
+    async with tractor.get_arbiter(*reg_addr) as portal:
         await portal.cancel_actor()
 
     time.sleep(0.1)
@@ -41,7 +41,7 @@ async def test_cancel_remote_arbiter(daemon, reg_addr):
 
     # no arbiter socket should exist
     with pytest.raises(OSError):
-        async with tractor.get_registry(reg_addr) as portal:
+        async with tractor.get_arbiter(*reg_addr) as portal:
             pass
 
 

tests/test_pldrx_limiting.py

@@ -1,364 +0,0 @@
-'''
-Audit sub-sys APIs from `.msg._ops`
-mostly for ensuring correct `contextvars`
-related settings around IPC contexts.
-
-'''
-from contextlib import (
-    asynccontextmanager as acm,
-)
-
-from msgspec import (
-    Struct,
-)
-import pytest
-import trio
-
-import tractor
-from tractor import (
-    Context,
-    MsgTypeError,
-    current_ipc_ctx,
-    Portal,
-)
-from tractor.msg import (
-    _ops as msgops,
-    Return,
-)
-from tractor.msg import (
-    _codec,
-)
-from tractor.msg.types import (
-    log,
-)
-
-
-class PldMsg(
-    Struct,
-
-    # TODO: with multiple structs in-spec we need to tag them!
-    # -[ ] offer a built-in `PldMsg` type to inherit from which takes
-    #      case of these details?
-    #
-    # https://jcristharif.com/msgspec/structs.html#tagged-unions
-    # tag=True,
-    # tag_field='msg_type',
-):
-    field: str
-
-
-maybe_msg_spec = PldMsg|None
-
-
-@acm
-async def maybe_expect_raises(
-    raises: BaseException|None = None,
-    ensure_in_message: list[str]|None = None,
-    post_mortem: bool = False,
-    timeout: int = 3,
-) -> None:
-    '''
-    Async wrapper for ensuring errors propagate from the inner scope.
-
-    '''
-    if tractor._state.debug_mode():
-        timeout += 999
-
-    with trio.fail_after(timeout):
-        try:
-            yield
-        except BaseException as _inner_err:
-            inner_err = _inner_err
-            # wasn't-expected to error..
-            if raises is None:
-                raise
-
-            else:
-                assert type(inner_err) is raises
-
-                # maybe check for error txt content
-                if ensure_in_message:
-                    part: str
-                    err_repr: str = repr(inner_err)
-                    for part in ensure_in_message:
-                        for i, arg in enumerate(inner_err.args):
-                            if part in err_repr:
-                                break
-                        # if part never matches an arg, then we're
-                        # missing a match.
-                        else:
-                            raise ValueError(
-                                'Failed to find error message content?\n\n'
-                                f'expected: {ensure_in_message!r}\n'
-                                f'part: {part!r}\n\n'
-                                f'{inner_err.args}'
-                        )
-
-                if post_mortem:
-                    await tractor.post_mortem()
-
-        else:
-            if raises:
-                raise RuntimeError(
-                    f'Expected a {raises.__name__!r} to be raised?'
-                )
-
-
-@tractor.context(
-    pld_spec=maybe_msg_spec,
-)
-async def child(
-    ctx: Context,
-    started_value: int|PldMsg|None,
-    return_value: str|None,
-    validate_pld_spec: bool,
-    raise_on_started_mte: bool = True,
-
-) -> None:
-    '''
-    Call ``Context.started()`` more then once (an error).
-
-    '''
-    expect_started_mte: bool = started_value == 10
-
-    # sanaity check that child RPC context is the current one
-    curr_ctx: Context = current_ipc_ctx()
-    assert ctx is curr_ctx
-
-    rx: msgops.PldRx = ctx._pld_rx
-    curr_pldec: _codec.MsgDec = rx.pld_dec
-
-    ctx_meta: dict = getattr(
-        child,
-        '_tractor_context_meta',
-        None,
-    )
-    if ctx_meta:
-        assert (
-            ctx_meta['pld_spec']
-            is curr_pldec.spec
-            is curr_pldec.pld_spec
-        )
-
-    # 2 cases: hdndle send-side and recv-only validation
-    # - when `raise_on_started_mte == True`, send validate
-    # - else, parent-recv-side only validation
-    mte: MsgTypeError|None = None
-    try:
-        await ctx.started(
-            value=started_value,
-            validate_pld_spec=validate_pld_spec,
-        )
-
-    except MsgTypeError as _mte:
-        mte = _mte
-        log.exception('started()` raised an MTE!\n')
-        if not expect_started_mte:
-            raise RuntimeError(
-                'Child-ctx-task SHOULD NOT HAVE raised an MTE for\n\n'
-                f'{started_value!r}\n'
-            )
-
-        boxed_div: str = '------ - ------'
-        assert boxed_div not in mte._message
-        assert boxed_div not in mte.tb_str
-        assert boxed_div not in repr(mte)
-        assert boxed_div not in str(mte)
-        mte_repr: str = repr(mte)
-        for line in mte.message.splitlines():
-            assert line in mte_repr
-
-        # since this is a *local error* there should be no
-        # boxed traceback content!
-        assert not mte.tb_str
-
-        # propagate to parent?
-        if raise_on_started_mte:
-            raise
-
-    # no-send-side-error fallthrough
-    if (
-        validate_pld_spec
-        and
-        expect_started_mte
-    ):
-        raise RuntimeError(
-            'Child-ctx-task SHOULD HAVE raised an MTE for\n\n'
-            f'{started_value!r}\n'
-        )
-
-    assert (
-        not expect_started_mte
-        or
-        not validate_pld_spec
-    )
-
-    # if wait_for_parent_to_cancel:
-    #     ...
-    #
-    # ^-TODO-^ logic for diff validation policies on each side:
-    #
-    # -[ ] ensure that if we don't validate on the send
-    #   side, that we are eventually error-cancelled by our
-    #   parent due to the bad `Started` payload!
-    # -[ ] the boxed error should be srced from the parent's
-    #   runtime NOT ours!
-    # -[ ] we should still error on bad `return_value`s
-    #   despite the parent not yet error-cancelling us?
-    #   |_ how do we want the parent side to look in that
-    #     case?
-    #     -[ ] maybe the equiv of "during handling of the
-    #       above error another occurred" for the case where
-    #       the parent sends a MTE to this child and while
-    #       waiting for the child to terminate it gets back
-    #       the MTE for this case?
-    #
-
-    # XXX should always fail on recv side since we can't
-    # really do much else beside terminate and relay the
-    # msg-type-error from this RPC task ;)
-    return return_value
-
-
-@pytest.mark.parametrize(
-    'return_value',
-    [
-        'yo',
-        None,
-    ],
-    ids=[
-        'return[invalid-"yo"]',
-        'return[valid-None]',
-    ],
-)
-@pytest.mark.parametrize(
-    'started_value',
-    [
-        10,
-        PldMsg(field='yo'),
-    ],
-    ids=[
-        'Started[invalid-10]',
-        'Started[valid-PldMsg]',
-    ],
-)
-@pytest.mark.parametrize(
-    'pld_check_started_value',
-    [
-        True,
-        False,
-    ],
-    ids=[
-        'check-started-pld',
-        'no-started-pld-validate',
-    ],
-)
-def test_basic_payload_spec(
-    debug_mode: bool,
-    loglevel: str,
-    return_value: str|None,
-    started_value: int|PldMsg,
-    pld_check_started_value: bool,
-):
-    '''
-    Validate the most basic `PldRx` msg-type-spec semantics around
-    a IPC `Context` endpoint start, started-sync, and final return
-    value depending on set payload types and the currently applied
-    pld-spec.
-
-    '''
-    invalid_return: bool = return_value == 'yo'
-    invalid_started: bool = started_value == 10
-
-    async def main():
-        async with tractor.open_nursery(
-            debug_mode=debug_mode,
-            loglevel=loglevel,
-        ) as an:
-            p: Portal = await an.start_actor(
-                'child',
-                enable_modules=[__name__],
-            )
-
-            # since not opened yet.
-            assert current_ipc_ctx() is None
-
-            if invalid_started:
-                msg_type_str: str = 'Started'
-                bad_value: int = 10
-            elif invalid_return:
-                msg_type_str: str = 'Return'
-                bad_value: str = 'yo'
-            else:
-                # XXX but should never be used below then..
-                msg_type_str: str = ''
-                bad_value: str = ''
-
-            maybe_mte: MsgTypeError|None = None
-            should_raise: Exception|None = (
-                MsgTypeError if (
-                    invalid_return
-                    or
-                    invalid_started
-                ) else None
-            )
-            async with (
-                maybe_expect_raises(
-                    raises=should_raise,
-                    ensure_in_message=[
-                        f"invalid `{msg_type_str}` msg payload",
-                        f'{bad_value}',
-                        f'has type {type(bad_value)!r}',
-                        'not match type-spec',
-                        f'`{msg_type_str}.pld: PldMsg|NoneType`',
-                    ],
-                    # only for debug
-                    # post_mortem=True,
-                ),
-                p.open_context(
-                    child,
-                    return_value=return_value,
-                    started_value=started_value,
-                    validate_pld_spec=pld_check_started_value,
-                ) as (ctx, first),
-            ):
-                # now opened with 'child' sub
-                assert current_ipc_ctx() is ctx
-
-                assert type(first) is PldMsg
-                assert first.field == 'yo'
-
-                try:
-                    res: None|PldMsg = await ctx.result(hide_tb=False)
-                    assert res is None
-                except MsgTypeError as mte:
-                    maybe_mte = mte
-                    if not invalid_return:
-                        raise
-
-                    # expected this invalid `Return.pld` so audit
-                    # the error state + meta-data
-                    assert mte.expected_msg_type is Return
-                    assert mte.cid == ctx.cid
-                    mte_repr: str = repr(mte)
-                    for line in mte.message.splitlines():
-                        assert line in mte_repr
-
-                    assert mte.tb_str
-                    # await tractor.pause(shield=True)
-
-                    # verify expected remote mte deats
-                    assert ctx._local_error is None
-                    assert (
-                        mte is
-                        ctx._remote_error is
-                        ctx.maybe_error is
-                        ctx.outcome
-                    )
-
-            if should_raise is None:
-                assert maybe_mte is None
-
-            await p.cancel_actor()
-
-    trio.run(main)

tests/test_resource_cache.py

@@ -100,29 +100,16 @@ async def streamer(
 @acm
 async def open_stream() -> Awaitable[tractor.MsgStream]:
 
-    try:
-        async with tractor.open_nursery() as an:
-            portal = await an.start_actor(
-                'streamer',
-                enable_modules=[__name__],
-            )
-            async with (
-                portal.open_context(streamer) as (ctx, first),
-                ctx.open_stream() as stream,
-            ):
-                yield stream
+    async with tractor.open_nursery() as tn:
+        portal = await tn.start_actor('streamer', enable_modules=[__name__])
+        async with (
+            portal.open_context(streamer) as (ctx, first),
+            ctx.open_stream() as stream,
+        ):
+            yield stream
 
-            print('Cancelling streamer')
-            await portal.cancel_actor()
-            print('Cancelled streamer')
-
-    except Exception as err:
-        print(
-            f'`open_stream()` errored?\n'
-            f'{err!r}\n'
-        )
-        await tractor.pause(shield=True)
-        raise err
+        await portal.cancel_actor()
+    print('CANCELLED STREAMER')
 
 
 @acm
@@ -145,28 +132,19 @@ async def maybe_open_stream(taskname: str):
             yield stream
 
 
-def test_open_local_sub_to_stream(
-    debug_mode: bool,
-):
+def test_open_local_sub_to_stream():
     '''
     Verify a single inter-actor stream can can be fanned-out shared to
-    N local tasks using `trionics.maybe_open_context()`.
+    N local tasks using ``trionics.maybe_open_context():``.
 
     '''
-    timeout: float = 3.6
-    if platform.system() == "Windows":
-        timeout: float = 10
-
-    if debug_mode:
-        timeout = 999
+    timeout: float = 3.6 if platform.system() != "Windows" else 10
 
     async def main():
 
         full = list(range(1000))
 
         async def get_sub_and_pull(taskname: str):
-
-            stream: tractor.MsgStream
             async with (
                 maybe_open_stream(taskname) as stream,
             ):
@@ -187,27 +165,17 @@ def test_open_local_sub_to_stream(
                 assert set(seq).issubset(set(full))
             print(f'{taskname} finished')
 
-        with trio.fail_after(timeout) as cs:
+        with trio.fail_after(timeout):
             # TODO: turns out this isn't multi-task entrant XD
             # We probably need an indepotent entry semantic?
-            async with tractor.open_root_actor(
-                debug_mode=debug_mode,
-            ):
+            async with tractor.open_root_actor():
                 async with (
-                    trio.open_nursery() as tn,
+                    trio.open_nursery() as nurse,
                 ):
                     for i in range(10):
-                        tn.start_soon(
-                            get_sub_and_pull,
-                            f'task_{i}',
-                        )
+                        nurse.start_soon(get_sub_and_pull, f'task_{i}')
                         await trio.sleep(0.001)
 
                 print('all consumer tasks finished')
 
-        if cs.cancelled_caught:
-            pytest.fail(
-                'Should NOT time out in `open_root_actor()` ?'
-            )
-
     trio.run(main)

tests/test_ringbuf.py

@@ -1,211 +0,0 @@
-import time
-
-import trio
-import pytest
-
-import tractor
-from tractor.ipc._ringbuf import (
-    open_ringbuf,
-    RBToken,
-    RingBuffSender,
-    RingBuffReceiver
-)
-from tractor._testing.samples import (
-    generate_sample_messages,
-)
-
-# in case you don't want to melt your cores, uncomment dis!
-pytestmark = pytest.mark.skip
-
-
-@tractor.context
-async def child_read_shm(
-    ctx: tractor.Context,
-    msg_amount: int,
-    token: RBToken,
-    total_bytes: int,
-) -> None:
-    recvd_bytes = 0
-    await ctx.started()
-    start_ts = time.time()
-    async with RingBuffReceiver(token) as receiver:
-        while recvd_bytes < total_bytes:
-            msg = await receiver.receive_some()
-            recvd_bytes += len(msg)
-
-        # make sure we dont hold any memoryviews
-        # before the ctx manager aclose()
-        msg = None
-
-    end_ts = time.time()
-    elapsed = end_ts - start_ts
-    elapsed_ms = int(elapsed * 1000)
-
-    print(f'\n\telapsed ms: {elapsed_ms}')
-    print(f'\tmsg/sec: {int(msg_amount / elapsed):,}')
-    print(f'\tbytes/sec: {int(recvd_bytes / elapsed):,}')
-
-
-@tractor.context
-async def child_write_shm(
-    ctx: tractor.Context,
-    msg_amount: int,
-    rand_min: int,
-    rand_max: int,
-    token: RBToken,
-) -> None:
-    msgs, total_bytes = generate_sample_messages(
-        msg_amount,
-        rand_min=rand_min,
-        rand_max=rand_max,
-    )
-    await ctx.started(total_bytes)
-    async with RingBuffSender(token) as sender:
-        for msg in msgs:
-            await sender.send_all(msg)
-
-
-@pytest.mark.parametrize(
-    'msg_amount,rand_min,rand_max,buf_size',
-    [
-        # simple case, fixed payloads, large buffer
-        (100_000, 0, 0, 10 * 1024),
-
-        # guaranteed wrap around on every write
-        (100, 10 * 1024, 20 * 1024, 10 * 1024),
-
-        # large payload size, but large buffer
-        (10_000, 256 * 1024, 512 * 1024, 10 * 1024 * 1024)
-    ],
-    ids=[
-        'fixed_payloads_large_buffer',
-        'wrap_around_every_write',
-        'large_payloads_large_buffer',
-    ]
-)
-def test_ringbuf(
-    msg_amount: int,
-    rand_min: int,
-    rand_max: int,
-    buf_size: int
-):
-    async def main():
-        with open_ringbuf(
-            'test_ringbuf',
-            buf_size=buf_size
-        ) as token:
-            proc_kwargs = {
-                'pass_fds': (token.write_eventfd, token.wrap_eventfd)
-            }
-
-            common_kwargs = {
-                'msg_amount': msg_amount,
-                'token': token,
-            }
-            async with tractor.open_nursery() as an:
-                send_p = await an.start_actor(
-                    'ring_sender',
-                    enable_modules=[__name__],
-                    proc_kwargs=proc_kwargs
-                )
-                recv_p = await an.start_actor(
-                    'ring_receiver',
-                    enable_modules=[__name__],
-                    proc_kwargs=proc_kwargs
-                )
-                async with (
-                    send_p.open_context(
-                        child_write_shm,
-                        rand_min=rand_min,
-                        rand_max=rand_max,
-                        **common_kwargs
-                    ) as (sctx, total_bytes),
-                    recv_p.open_context(
-                        child_read_shm,
-                        **common_kwargs,
-                        total_bytes=total_bytes,
-                    ) as (sctx, _sent),
-                ):
-                    await recv_p.result()
-
-                await send_p.cancel_actor()
-                await recv_p.cancel_actor()
-
-
-    trio.run(main)
-
-
-@tractor.context
-async def child_blocked_receiver(
-    ctx: tractor.Context,
-    token: RBToken
-):
-    async with RingBuffReceiver(token) as receiver:
-        await ctx.started()
-        await receiver.receive_some()
-
-
-def test_ring_reader_cancel():
-    async def main():
-        with open_ringbuf('test_ring_cancel_reader') as token:
-            async with (
-                tractor.open_nursery() as an,
-                RingBuffSender(token) as _sender,
-            ):
-                recv_p = await an.start_actor(
-                    'ring_blocked_receiver',
-                    enable_modules=[__name__],
-                    proc_kwargs={
-                        'pass_fds': (token.write_eventfd, token.wrap_eventfd)
-                    }
-                )
-                async with (
-                    recv_p.open_context(
-                        child_blocked_receiver,
-                        token=token
-                    ) as (sctx, _sent),
-                ):
-                    await trio.sleep(1)
-                    await an.cancel()
-
-
-    with pytest.raises(tractor._exceptions.ContextCancelled):
-        trio.run(main)
-
-
-@tractor.context
-async def child_blocked_sender(
-    ctx: tractor.Context,
-    token: RBToken
-):
-    async with RingBuffSender(token) as sender:
-        await ctx.started()
-        await sender.send_all(b'this will wrap')
-
-
-def test_ring_sender_cancel():
-    async def main():
-        with open_ringbuf(
-            'test_ring_cancel_sender',
-            buf_size=1
-        ) as token:
-            async with tractor.open_nursery() as an:
-                recv_p = await an.start_actor(
-                    'ring_blocked_sender',
-                    enable_modules=[__name__],
-                    proc_kwargs={
-                        'pass_fds': (token.write_eventfd, token.wrap_eventfd)
-                    }
-                )
-                async with (
-                    recv_p.open_context(
-                        child_blocked_sender,
-                        token=token
-                    ) as (sctx, _sent),
-                ):
-                    await trio.sleep(1)
-                    await an.cancel()
-
-
-    with pytest.raises(tractor._exceptions.ContextCancelled):
-        trio.run(main)

tests/test_root_infect_asyncio.py

@@ -1,248 +0,0 @@
-'''
-Special attention cases for using "infect `asyncio`" mode from a root
-actor; i.e. not using a std `trio.run()` bootstrap.
-
-'''
-import asyncio
-from functools import partial
-
-import pytest
-import trio
-import tractor
-from tractor import (
-    to_asyncio,
-)
-from tests.test_infected_asyncio import (
-    aio_echo_server,
-)
-
-
-@pytest.mark.parametrize(
-    'raise_error_mid_stream',
-    [
-        False,
-        Exception,
-        KeyboardInterrupt,
-    ],
-    ids='raise_error={}'.format,
-)
-def test_infected_root_actor(
-    raise_error_mid_stream: bool|Exception,
-
-    # conftest wide
-    loglevel: str,
-    debug_mode: bool,
-):
-    '''
-    Verify you can run the `tractor` runtime with `Actor.is_infected_aio() == True`
-    in the root actor.
-
-    '''
-    async def _trio_main():
-        with trio.fail_after(2 if not debug_mode else 999):
-            first: str
-            chan: to_asyncio.LinkedTaskChannel
-            async with (
-                tractor.open_root_actor(
-                    debug_mode=debug_mode,
-                    loglevel=loglevel,
-                ),
-                to_asyncio.open_channel_from(
-                    aio_echo_server,
-                ) as (first, chan),
-            ):
-                assert first == 'start'
-
-                for i in range(1000):
-                    await chan.send(i)
-                    out = await chan.receive()
-                    assert out == i
-                    print(f'asyncio echoing {i}')
-
-                    if (
-                        raise_error_mid_stream
-                        and
-                        i == 500
-                    ):
-                        raise raise_error_mid_stream
-
-                    if out is None:
-                        try:
-                            out = await chan.receive()
-                        except trio.EndOfChannel:
-                            break
-                        else:
-                            raise RuntimeError(
-                                'aio channel never stopped?'
-                            )
-
-    if raise_error_mid_stream:
-        with pytest.raises(raise_error_mid_stream):
-            tractor.to_asyncio.run_as_asyncio_guest(
-                trio_main=_trio_main,
-            )
-    else:
-        tractor.to_asyncio.run_as_asyncio_guest(
-            trio_main=_trio_main,
-        )
-
-
-
-async def sync_and_err(
-    # just signature placeholders for compat with
-    # ``to_asyncio.open_channel_from()``
-    to_trio: trio.MemorySendChannel,
-    from_trio: asyncio.Queue,
-    ev: asyncio.Event,
-
-):
-    if to_trio:
-        to_trio.send_nowait('start')
-
-    await ev.wait()
-    raise RuntimeError('asyncio-side')
-
-
-@pytest.mark.parametrize(
-    'aio_err_trigger',
-    [
-        'before_start_point',
-        'after_trio_task_starts',
-        'after_start_point',
-    ],
-    ids='aio_err_triggered={}'.format
-)
-def test_trio_prestarted_task_bubbles(
-    aio_err_trigger: str,
-
-    # conftest wide
-    loglevel: str,
-    debug_mode: bool,
-):
-    async def pre_started_err(
-        raise_err: bool = False,
-        pre_sleep: float|None = None,
-        aio_trigger: asyncio.Event|None = None,
-        task_status=trio.TASK_STATUS_IGNORED,
-    ):
-        '''
-        Maybe pre-started error then sleep.
-
-        '''
-        if pre_sleep is not None:
-            print(f'Sleeping from trio for {pre_sleep!r}s !')
-            await trio.sleep(pre_sleep)
-
-        # signal aio-task to raise JUST AFTER this task
-        # starts but has not yet `.started()`
-        if aio_trigger:
-            print('Signalling aio-task to raise from `trio`!!')
-            aio_trigger.set()
-
-        if raise_err:
-            print('Raising from trio!')
-            raise TypeError('trio-side')
-
-        task_status.started()
-        await trio.sleep_forever()
-
-    async def _trio_main():
-        # with trio.fail_after(2):
-        with trio.fail_after(999):
-            first: str
-            chan: to_asyncio.LinkedTaskChannel
-            aio_ev = asyncio.Event()
-
-            async with (
-                tractor.open_root_actor(
-                    debug_mode=False,
-                    loglevel=loglevel,
-                ),
-            ):
-                # TODO, tests for this with 3.13 egs?
-                # from tractor.devx import open_crash_handler
-                # with open_crash_handler():
-                async with (
-                    # where we'll start a sub-task that errors BEFORE
-                    # calling `.started()` such that the error should
-                    # bubble before the guest run terminates!
-                    trio.open_nursery() as tn,
-
-                    # THEN start an infect task which should error just
-                    # after the trio-side's task does.
-                    to_asyncio.open_channel_from(
-                        partial(
-                            sync_and_err,
-                            ev=aio_ev,
-                        )
-                    ) as (first, chan),
-                ):
-
-                    for i in range(5):
-                        pre_sleep: float|None = None
-                        last_iter: bool = (i == 4)
-
-                        # TODO, missing cases?
-                        # -[ ] error as well on
-                        #    'after_start_point' case as well for
-                        #    another case?
-                        raise_err: bool = False
-
-                        if last_iter:
-                            raise_err: bool = True
-
-                            # trigger aio task to error on next loop
-                            # tick/checkpoint
-                            if aio_err_trigger == 'before_start_point':
-                                aio_ev.set()
-
-                            pre_sleep: float = 0
-
-                        await tn.start(
-                            pre_started_err,
-                            raise_err,
-                            pre_sleep,
-                            (aio_ev if (
-                                    aio_err_trigger == 'after_trio_task_starts'
-                                    and
-                                    last_iter
-                                ) else None
-                            ),
-                        )
-
-                        if (
-                            aio_err_trigger == 'after_start_point'
-                            and
-                            last_iter
-                        ):
-                            aio_ev.set()
-
-    with pytest.raises(
-        expected_exception=ExceptionGroup,
-    ) as excinfo:
-        tractor.to_asyncio.run_as_asyncio_guest(
-            trio_main=_trio_main,
-        )
-
-    eg = excinfo.value
-    rte_eg, rest_eg = eg.split(RuntimeError)
-
-    # ensure the trio-task's error bubbled despite the aio-side
-    # having (maybe) errored first.
-    if aio_err_trigger in (
-        'after_trio_task_starts',
-        'after_start_point',
-    ):
-        assert len(errs := rest_eg.exceptions) == 1
-        typerr = errs[0]
-        assert (
-            type(typerr) is TypeError
-            and
-            'trio-side' in typerr.args
-        )
-
-    # when aio errors BEFORE (last) trio task is scheduled, we should
-    # never see anythinb but the aio-side.
-    else:
-        assert len(rtes := rte_eg.exceptions) == 1
-        assert 'asyncio-side' in rtes[0].args[0]

tests/test_root_runtime.py

@@ -1,108 +0,0 @@
-'''
-Runtime boot/init sanity.
-
-'''
-
-import pytest
-import trio
-
-import tractor
-from tractor._exceptions import RuntimeFailure
-
-
-@tractor.context
-async def open_new_root_in_sub(
-    ctx: tractor.Context,
-) -> None:
-
-    async with tractor.open_root_actor():
-        pass
-
-
-@pytest.mark.parametrize(
-    'open_root_in',
-    ['root', 'sub'],
-    ids='open_2nd_root_in={}'.format,
-)
-def test_only_one_root_actor(
-    open_root_in: str,
-    reg_addr: tuple,
-    debug_mode: bool
-):
-    '''
-    Verify we specially fail whenever more then one root actor
-    is attempted to be opened within an already opened tree.
-
-    '''
-    async def main():
-        async with tractor.open_nursery() as an:
-
-            if open_root_in == 'root':
-                async with tractor.open_root_actor(
-                    registry_addrs=[reg_addr],
-                ):
-                    pass
-
-            ptl: tractor.Portal = await an.start_actor(
-                name='bad_rooty_boi',
-                enable_modules=[__name__],
-            )
-
-            async with ptl.open_context(
-                open_new_root_in_sub,
-            ) as (ctx, first):
-                pass
-
-    if open_root_in == 'root':
-        with pytest.raises(
-            RuntimeFailure
-        ) as excinfo:
-            trio.run(main)
-
-    else:
-        with pytest.raises(
-            tractor.RemoteActorError,
-        ) as excinfo:
-            trio.run(main)
-
-        assert excinfo.value.boxed_type is RuntimeFailure
-
-
-def test_implicit_root_via_first_nursery(
-    reg_addr: tuple,
-    debug_mode: bool
-):
-    '''
-    The first `ActorNursery` open should implicitly call
-    `_root.open_root_actor()`.
-
-    '''
-    async def main():
-        async with tractor.open_nursery() as an:
-            assert an._implicit_runtime_started
-            assert tractor.current_actor().aid.name == 'root'
-
-    trio.run(main)
-
-
-def test_runtime_vars_unset(
-    reg_addr: tuple,
-    debug_mode: bool
-):
-    '''
-    Ensure any `._state._runtime_vars` are restored to default values
-    after the root actor-runtime exits!
-
-    '''
-    assert not tractor._state._runtime_vars['_debug_mode']
-    async def main():
-        assert not tractor._state._runtime_vars['_debug_mode']
-        async with tractor.open_nursery(
-            debug_mode=True,
-        ):
-            assert tractor._state._runtime_vars['_debug_mode']
-
-        # after runtime closure, should be reverted!
-        assert not tractor._state._runtime_vars['_debug_mode']
-
-    trio.run(main)

tests/test_shm.py

@@ -1,167 +0,0 @@
-"""
-Shared mem primitives and APIs.
-
-"""
-import uuid
-
-# import numpy
-import pytest
-import trio
-import tractor
-from tractor.ipc._shm import (
-    open_shm_list,
-    attach_shm_list,
-)
-
-
-@tractor.context
-async def child_attach_shml_alot(
-    ctx: tractor.Context,
-    shm_key: str,
-) -> None:
-
-    await ctx.started(shm_key)
-
-    # now try to attach a boatload of times in a loop..
-    for _ in range(1000):
-        shml = attach_shm_list(
-            key=shm_key,
-            readonly=False,
-        )
-        assert shml.shm.name == shm_key
-        await trio.sleep(0.001)
-
-
-def test_child_attaches_alot():
-    async def main():
-        async with tractor.open_nursery() as an:
-
-            # allocate writeable list in parent
-            key = f'shml_{uuid.uuid4()}'
-            shml = open_shm_list(
-                key=key,
-            )
-
-            portal = await an.start_actor(
-                'shm_attacher',
-                enable_modules=[__name__],
-            )
-
-            async with (
-                portal.open_context(
-                    child_attach_shml_alot,
-                    shm_key=shml.key,
-                ) as (ctx, start_val),
-            ):
-                assert start_val == key
-                await ctx.result()
-
-            await portal.cancel_actor()
-
-    trio.run(main)
-
-
-@tractor.context
-async def child_read_shm_list(
-    ctx: tractor.Context,
-    shm_key: str,
-    use_str: bool,
-    frame_size: int,
-) -> None:
-
-    # attach in child
-    shml = attach_shm_list(
-        key=shm_key,
-        # dtype=str if use_str else float,
-    )
-    await ctx.started(shml.key)
-
-    async with ctx.open_stream() as stream:
-        async for i in stream:
-            print(f'(child): reading shm list index: {i}')
-
-            if use_str:
-                expect = str(float(i))
-            else:
-                expect = float(i)
-
-            if frame_size == 1:
-                val = shml[i]
-                assert expect == val
-                print(f'(child): reading value: {val}')
-            else:
-                frame = shml[i - frame_size:i]
-                print(f'(child): reading frame: {frame}')
-
-
-@pytest.mark.parametrize(
-    'use_str',
-    [False, True],
-    ids=lambda i: f'use_str_values={i}',
-)
-@pytest.mark.parametrize(
-    'frame_size',
-    [1, 2**6, 2**10],
-    ids=lambda i: f'frame_size={i}',
-)
-def test_parent_writer_child_reader(
-    use_str: bool,
-    frame_size: int,
-):
-
-    async def main():
-        async with tractor.open_nursery(
-            # debug_mode=True,
-        ) as an:
-
-            portal = await an.start_actor(
-                'shm_reader',
-                enable_modules=[__name__],
-                debug_mode=True,
-            )
-
-            # allocate writeable list in parent
-            key = 'shm_list'
-            seq_size = int(2 * 2 ** 10)
-            shml = open_shm_list(
-                key=key,
-                size=seq_size,
-                dtype=str if use_str else float,
-                readonly=False,
-            )
-
-            async with (
-                portal.open_context(
-                    child_read_shm_list,
-                    shm_key=key,
-                    use_str=use_str,
-                    frame_size=frame_size,
-                ) as (ctx, sent),
-
-                ctx.open_stream() as stream,
-            ):
-
-                assert sent == key
-
-                for i in range(seq_size):
-
-                    val = float(i)
-                    if use_str:
-                        val = str(val)
-
-                    # print(f'(parent): writing {val}')
-                    shml[i] = val
-
-                    # only on frame fills do we
-                    # signal to the child that a frame's
-                    # worth is ready.
-                    if (i % frame_size) == 0:
-                        print(f'(parent): signalling frame full on {val}')
-                        await stream.send(i)
-                else:
-                    print(f'(parent): signalling final frame on {val}')
-                    await stream.send(i)
-
-            await portal.cancel_actor()
-
-    trio.run(main)

tests/test_spawning.py

@@ -2,10 +2,7 @@
 Spawning basics
 
 """
-from functools import partial
-from typing import (
-    Any,
-)
+from typing import Optional
 
 import pytest
 import trio
@@ -13,99 +10,76 @@ import tractor
 
 from tractor._testing import tractor_test
 
-data_to_pass_down = {
-    'doggy': 10,
-    'kitty': 4,
-}
+data_to_pass_down = {'doggy': 10, 'kitty': 4}
 
 
 async def spawn(
-    should_be_root: bool,
+    is_arbiter: bool,
     data: dict,
     reg_addr: tuple[str, int],
-
-    debug_mode: bool = False,
 ):
+    namespaces = [__name__]
+
     await trio.sleep(0.1)
-    actor = tractor.current_actor(err_on_no_runtime=False)
 
-    if should_be_root:
-        assert actor is None  # no runtime yet
-        async with (
-            tractor.open_root_actor(
-                arbiter_addr=reg_addr,
-            ),
-            tractor.open_nursery() as an,
-        ):
-            # now runtime exists
-            actor: tractor.Actor = tractor.current_actor()
-            assert actor.is_arbiter == should_be_root
+    async with tractor.open_root_actor(
+        arbiter_addr=reg_addr,
+    ):
 
-            # spawns subproc here
-            portal: tractor.Portal = await an.run_in_actor(
-                fn=spawn,
+        actor = tractor.current_actor()
+        assert actor.is_arbiter == is_arbiter
+        data = data_to_pass_down
 
-                # spawning args
-                name='sub-actor',
-                enable_modules=[__name__],
+        if actor.is_arbiter:
 
-                # passed to a subactor-recursive RPC invoke
-                # of this same `spawn()` fn.
-                should_be_root=False,
-                data=data_to_pass_down,
-                reg_addr=reg_addr,
-            )
+            async with tractor.open_nursery() as nursery:
 
-            assert len(an._children) == 1
-            assert (
-                portal.channel.uid
-                in
-                tractor.current_actor().ipc_server._peers
-            )
+                # forks here
+                portal = await nursery.run_in_actor(
+                    spawn,
+                    is_arbiter=False,
+                    name='sub-actor',
+                    data=data,
+                    reg_addr=reg_addr,
+                    enable_modules=namespaces,
+                )
 
-            # get result from child subactor
-            result = await portal.result()
-            assert result == 10
-            return result
-    else:
-        assert actor.is_arbiter == should_be_root
-        return 10
+                assert len(nursery._children) == 1
+                assert portal.channel.uid in tractor.current_actor()._peers
+                # be sure we can still get the result
+                result = await portal.result()
+                assert result == 10
+                return result
+        else:
+            return 10
 
 
-def test_run_in_actor_same_func_in_child(
-    reg_addr: tuple,
-    debug_mode: bool,
+def test_local_arbiter_subactor_global_state(
+    reg_addr,
 ):
     result = trio.run(
-        partial(
-            spawn,
-            should_be_root=True,
-            data=data_to_pass_down,
-            reg_addr=reg_addr,
-            debug_mode=debug_mode,
-        )
+        spawn,
+        True,
+        data_to_pass_down,
+        reg_addr,
     )
     assert result == 10
 
 
 async def movie_theatre_question():
-    '''
-    A question asked in a dark theatre, in a tangent
+    """A question asked in a dark theatre, in a tangent
     (errr, I mean different) process.
-
-    '''
+    """
     return 'have you ever seen a portal?'
 
 
 @tractor_test
 async def test_movie_theatre_convo(start_method):
-    '''
-    The main ``tractor`` routine.
+    """The main ``tractor`` routine.
+    """
+    async with tractor.open_nursery() as n:
 
-    '''
-    async with tractor.open_nursery(debug_mode=True) as an:
-
-        portal = await an.start_actor(
+        portal = await n.start_actor(
             'frank',
             # enable the actor to run funcs from this current module
             enable_modules=[__name__],
@@ -121,9 +95,7 @@ async def test_movie_theatre_convo(start_method):
         await portal.cancel_actor()
 
 
-async def cellar_door(
-    return_value: str|None,
-):
+async def cellar_door(return_value: Optional[str]):
     return return_value
 
 
@@ -133,19 +105,17 @@ async def cellar_door(
 )
 @tractor_test
 async def test_most_beautiful_word(
-    start_method: str,
-    return_value: Any,
-    debug_mode: bool,
+    start_method,
+    return_value
 ):
     '''
     The main ``tractor`` routine.
 
     '''
     with trio.fail_after(1):
-        async with tractor.open_nursery(
-            debug_mode=debug_mode,
-        ) as an:
-            portal = await an.run_in_actor(
+        async with tractor.open_nursery() as n:
+
+            portal = await n.run_in_actor(
                 cellar_door,
                 return_value=return_value,
                 name='some_linguist',

tests/test_task_broadcasting.py

@@ -2,9 +2,7 @@
 Broadcast channels for fan-out to local tasks.
 
 """
-from contextlib import (
-    asynccontextmanager as acm,
-)
+from contextlib import asynccontextmanager
 from functools import partial
 from itertools import cycle
 import time
@@ -17,7 +15,6 @@ import tractor
 from tractor.trionics import (
     broadcast_receiver,
     Lagged,
-    collapse_eg,
 )
 
 
@@ -65,7 +62,7 @@ async def ensure_sequence(
                 break
 
 
-@acm
+@asynccontextmanager
 async def open_sequence_streamer(
 
     sequence: list[int],
@@ -77,9 +74,9 @@ async def open_sequence_streamer(
     async with tractor.open_nursery(
         arbiter_addr=reg_addr,
         start_method=start_method,
-    ) as an:
+    ) as tn:
 
-        portal = await an.start_actor(
+        portal = await tn.start_actor(
             'sequence_echoer',
             enable_modules=[__name__],
         )
@@ -158,12 +155,9 @@ def test_consumer_and_parent_maybe_lag(
         ) as stream:
 
             try:
-                async with (
-                    collapse_eg(),
-                    trio.open_nursery() as tn,
-                ):
+                async with trio.open_nursery() as n:
 
-                    tn.start_soon(
+                    n.start_soon(
                         ensure_sequence,
                         stream,
                         sequence.copy(),
@@ -236,8 +230,8 @@ def test_faster_task_to_recv_is_cancelled_by_slower(
 
         ) as stream:
 
-            async with trio.open_nursery() as tn:
-                tn.start_soon(
+            async with trio.open_nursery() as n:
+                n.start_soon(
                     ensure_sequence,
                     stream,
                     sequence.copy(),
@@ -259,7 +253,7 @@ def test_faster_task_to_recv_is_cancelled_by_slower(
                         continue
 
                 print('cancelling faster subtask')
-                tn.cancel_scope.cancel()
+                n.cancel_scope.cancel()
 
             try:
                 value = await stream.receive()
@@ -277,7 +271,7 @@ def test_faster_task_to_recv_is_cancelled_by_slower(
                         # the faster subtask was cancelled
                         break
 
-                # await tractor.pause()
+                # await tractor.breakpoint()
                 # await stream.receive()
                 print(f'final value: {value}')
 
@@ -377,13 +371,13 @@ def test_ensure_slow_consumers_lag_out(
                                     f'on {lags}:{value}')
                                 return
 
-            async with trio.open_nursery() as tn:
+            async with trio.open_nursery() as nursery:
 
                 for i in range(1, num_laggers):
 
                     task_name = f'sub_{i}'
                     laggers[task_name] = 0
-                    tn.start_soon(
+                    nursery.start_soon(
                         partial(
                             sub_and_print,
                             delay=i*0.001,
@@ -503,7 +497,6 @@ def test_no_raise_on_lag():
                 # internals when the no raise flag is set.
                 loglevel='warning',
             ),
-            collapse_eg(),
             trio.open_nursery() as n,
         ):
             n.start_soon(slow)

tests/test_trioisms.py

@@ -3,10 +3,6 @@ Reminders for oddities in `trio` that we need to stay aware of and/or
 want to see changed.
 
 '''
-from contextlib import (
-    asynccontextmanager as acm,
-)
-
 import pytest
 import trio
 from trio import TaskStatus
@@ -64,9 +60,7 @@ def test_stashed_child_nursery(use_start_soon):
     async def main():
 
         async with (
-            trio.open_nursery(
-                strict_exception_groups=False,
-            ) as pn,
+            trio.open_nursery() as pn,
         ):
             cn = await pn.start(mk_child_nursery)
             assert cn
@@ -86,119 +80,3 @@ def test_stashed_child_nursery(use_start_soon):
 
     with pytest.raises(NameError):
         trio.run(main)
-
-
-@pytest.mark.parametrize(
-    ('unmask_from_canc', 'canc_from_finally'),
-    [
-        (True, False),
-        (True, True),
-        pytest.param(False, True,
-                     marks=pytest.mark.xfail(reason="never raises!")
-        ),
-    ],
-    # TODO, ask ronny how to impl this .. XD
-    # ids='unmask_from_canc={0}, canc_from_finally={1}',#.format,
-)
-def test_acm_embedded_nursery_propagates_enter_err(
-    canc_from_finally: bool,
-    unmask_from_canc: bool,
-    debug_mode: bool,
-):
-    '''
-    Demo how a masking `trio.Cancelled` could be handled by unmasking from the
-    `.__context__` field when a user (by accident) re-raises from a `finally:`.
-
-    '''
-    import tractor
-
-    @acm
-    async def maybe_raise_from_masking_exc(
-        tn: trio.Nursery,
-        unmask_from: BaseException|None = trio.Cancelled
-
-        # TODO, maybe offer a collection?
-        # unmask_from: set[BaseException] = {
-        #     trio.Cancelled,
-        # },
-    ):
-        if not unmask_from:
-            yield
-            return
-
-        try:
-            yield
-        except* unmask_from as be_eg:
-
-            # TODO, if we offer `unmask_from: set`
-            # for masker_exc_type in unmask_from:
-
-            matches, rest = be_eg.split(unmask_from)
-            if not matches:
-                raise
-
-            for exc_match in be_eg.exceptions:
-                if (
-                    (exc_ctx := exc_match.__context__)
-                    and
-                    type(exc_ctx) not in {
-                        # trio.Cancelled,  # always by default?
-                        unmask_from,
-                    }
-                ):
-                    exc_ctx.add_note(
-                        f'\n'
-                        f'WARNING: the above error was masked by a {unmask_from!r} !?!\n'
-                        f'Are you always cancelling? Say from a `finally:` ?\n\n'
-
-                        f'{tn!r}'
-                    )
-                    raise exc_ctx from exc_match
-
-
-    @acm
-    async def wraps_tn_that_always_cancels():
-        async with (
-            trio.open_nursery() as tn,
-            maybe_raise_from_masking_exc(
-                tn=tn,
-                unmask_from=(
-                    trio.Cancelled
-                    if unmask_from_canc
-                    else None
-                ),
-            )
-        ):
-            try:
-                yield tn
-            finally:
-                if canc_from_finally:
-                    tn.cancel_scope.cancel()
-                    await trio.lowlevel.checkpoint()
-
-    async def _main():
-        with tractor.devx.maybe_open_crash_handler(
-            pdb=debug_mode,
-        ) as bxerr:
-            if bxerr:
-                assert not bxerr.value
-
-            async with (
-                wraps_tn_that_always_cancels() as tn,
-            ):
-                assert not tn.cancel_scope.cancel_called
-                assert 0
-
-        assert (
-            (err := bxerr.value)
-            and
-            type(err) is AssertionError
-        )
-
-    with pytest.raises(ExceptionGroup) as excinfo:
-        trio.run(_main)
-
-    eg: ExceptionGroup = excinfo.value
-    assert_eg, rest_eg = eg.split(AssertionError)
-
-    assert len(assert_eg.exceptions) == 1

tractor/__init__.py

@@ -31,7 +31,7 @@ from ._streaming import (
     stream as stream,
 )
 from ._discovery import (
-    get_registry as get_registry,
+    get_arbiter as get_arbiter,
     find_actor as find_actor,
     wait_for_actor as wait_for_actor,
     query_actor as query_actor,
@@ -43,15 +43,11 @@ from ._supervise import (
 from ._state import (
     current_actor as current_actor,
     is_root_process as is_root_process,
-    current_ipc_ctx as current_ipc_ctx,
-    debug_mode as debug_mode
 )
 from ._exceptions import (
-    ContextCancelled as ContextCancelled,
-    ModuleNotExposed as ModuleNotExposed,
-    MsgTypeError as MsgTypeError,
     RemoteActorError as RemoteActorError,
-    TransportClosed as TransportClosed,
+    ModuleNotExposed as ModuleNotExposed,
+    ContextCancelled as ContextCancelled,
 )
 from .devx import (
     breakpoint as breakpoint,
@@ -64,7 +60,6 @@ from ._root import (
     run_daemon as run_daemon,
     open_root_actor as open_root_actor,
 )
-from .ipc import Channel as Channel
+from ._ipc import Channel as Channel
 from ._portal import Portal as Portal
 from ._runtime import Actor as Actor
-# from . import hilevel as hilevel

tractor/_addr.py

@@ -1,282 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <https://www.gnu.org/licenses/>.
-from __future__ import annotations
-from uuid import uuid4
-from typing import (
-    Protocol,
-    ClassVar,
-    Type,
-    TYPE_CHECKING,
-)
-
-from bidict import bidict
-from trio import (
-    SocketListener,
-)
-
-from .log import get_logger
-from ._state import (
-    _def_tpt_proto,
-)
-from .ipc._tcp import TCPAddress
-from .ipc._uds import UDSAddress
-
-if TYPE_CHECKING:
-    from ._runtime import Actor
-
-log = get_logger(__name__)
-
-
-# TODO, maybe breakout the netns key to a struct?
-# class NetNs(Struct)[str, int]:
-#     ...
-
-# TODO, can't we just use a type alias
-# for this? namely just some `tuple[str, int, str, str]`?
-#
-# -[ ] would also just be simpler to keep this as SockAddr[tuple]
-#     or something, implying it's just a simple pair of values which can
-#     presumably be mapped to all transports?
-# -[ ] `pydoc socket.socket.getsockname()` delivers a 4-tuple for
-#     ipv6 `(hostaddr, port, flowinfo, scope_id)`.. so how should we
-#     handle that?
-# -[ ] as a further alternative to this wrap()/unwrap() approach we
-#     could just implement `enc/dec_hook()`s for the `Address`-types
-#     and just deal with our internal objs directly and always and
-#     leave it to the codec layer to figure out marshalling?
-#    |_ would mean only one spot to do the `.unwrap()` (which we may
-#       end up needing to call from the hook()s anyway?)
-# -[x] rename to `UnwrappedAddress[Descriptor]` ??
-#    seems like the right name as per,
-#    https://www.geeksforgeeks.org/introduction-to-address-descriptor/
-#
-UnwrappedAddress = (
-    # tcp/udp/uds
-    tuple[
-        str,  # host/domain(tcp), filesys-dir(uds)
-        int|str,  # port/path(uds)
-    ]
-    # ?TODO? should we also include another 2 fields from
-    # our `Aid` msg such that we include the runtime `Actor.uid`
-    # of `.name` and `.uuid`?
-    # - would ensure uniqueness across entire net?
-    # - allows for easier runtime-level filtering of "actors by
-    #   service name"
-)
-
-
-# TODO, maybe rename to `SocketAddress`?
-class Address(Protocol):
-    proto_key: ClassVar[str]
-    unwrapped_type: ClassVar[UnwrappedAddress]
-
-    # TODO, i feel like an `.is_bound()` is a better thing to
-    # support?
-    # Lke, what use does this have besides a noop and if it's not
-    # valid why aren't we erroring on creation/use?
-    @property
-    def is_valid(self) -> bool:
-        ...
-
-    # TODO, maybe `.netns` is a better name?
-    @property
-    def namespace(self) -> tuple[str, int]|None:
-        '''
-        The if-available, OS-specific "network namespace" key.
-
-        '''
-        ...
-
-    @property
-    def bindspace(self) -> str:
-        '''
-        Deliver the socket address' "bindable space" from
-        a `socket.socket.bind()` and thus from the perspective of
-        specific transport protocol domain.
-
-        I.e. for most (layer-4) network-socket protocols this is
-        normally the ipv4/6 address, for UDS this is normally
-        a filesystem (sub-directory).
-
-        For (distributed) network protocols this is normally the routing
-        layer's domain/(ip-)address, though it might also include a "network namespace"
-        key different then the default.
-
-        For local-host-only transports this is either an explicit
-        namespace (with types defined by the OS: netns, Cgroup, IPC,
-        pid, etc. on linux) or failing that the sub-directory in the
-        filesys in which socket/shm files are located *under*.
-
-        '''
-        ...
-
-    @classmethod
-    def from_addr(cls, addr: UnwrappedAddress) -> Address:
-        ...
-
-    def unwrap(self) -> UnwrappedAddress:
-        '''
-        Deliver the underying minimum field set in
-        a primitive python data type-structure.
-        '''
-        ...
-
-    @classmethod
-    def get_random(
-        cls,
-        current_actor: Actor,
-        bindspace: str|None = None,
-    ) -> Address:
-        ...
-
-    # TODO, this should be something like a `.get_def_registar_addr()`
-    # or similar since,
-    # - it should be a **host singleton** (not root/tree singleton)
-    # - we **only need this value** when one isn't provided to the
-    #   runtime at boot and we want to implicitly provide a host-wide
-    #   registrar.
-    # - each rooted-actor-tree should likely have its own
-    #   micro-registry (likely the root being it), also see
-    @classmethod
-    def get_root(cls) -> Address:
-        ...
-
-    def __repr__(self) -> str:
-        ...
-
-    def __eq__(self, other) -> bool:
-        ...
-
-    async def open_listener(
-        self,
-        **kwargs,
-    ) -> SocketListener:
-        ...
-
-    async def close_listener(self):
-        ...
-
-
-_address_types: bidict[str, Type[Address]] = {
-    'tcp': TCPAddress,
-    'uds': UDSAddress
-}
-
-
-# TODO! really these are discovery sys default addrs ONLY useful for
-# when none is provided to a root actor on first boot.
-_default_lo_addrs: dict[
-    str,
-    UnwrappedAddress
-] = {
-    'tcp': TCPAddress.get_root().unwrap(),
-    'uds': UDSAddress.get_root().unwrap(),
-}
-
-
-def get_address_cls(name: str) -> Type[Address]:
-    return _address_types[name]
-
-
-def is_wrapped_addr(addr: any) -> bool:
-    return type(addr) in _address_types.values()
-
-
-def mk_uuid() -> str:
-    '''
-    Encapsulate creation of a uuid4 as `str` as used
-    for creating `Actor.uid: tuple[str, str]` and/or
-    `.msg.types.Aid`.
-
-    '''
-    return str(uuid4())
-
-
-def wrap_address(
-    addr: UnwrappedAddress
-) -> Address:
-    '''
-    Wrap an `UnwrappedAddress` as an `Address`-type based
-    on matching builtin python data-structures which we adhoc
-    use for each.
-
-    XXX NOTE, careful care must be placed to ensure
-    `UnwrappedAddress` cases are **definitely unique** otherwise the
-    wrong transport backend may be loaded and will break many
-    low-level things in our runtime in a not-fun-to-debug way!
-
-    XD
-
-    '''
-    if is_wrapped_addr(addr):
-        return addr
-
-    cls: Type|None = None
-    # if 'sock' in addr[0]:
-    #     import pdbp; pdbp.set_trace()
-    match addr:
-
-        # classic network socket-address as tuple/list
-        case (
-            (str(), int())
-            |
-            [str(), int()]
-        ):
-            cls = TCPAddress
-
-        case (
-            # (str()|Path(), str()|Path()),
-            # ^TODO? uhh why doesn't this work!?
-
-            (_, filename)
-        ) if type(filename) is str:
-            cls = UDSAddress
-
-        # likely an unset UDS or TCP reg address as defaulted in
-        # `_state._runtime_vars['_root_mailbox']`
-        #
-        # TODO? figure out when/if we even need this?
-        case (
-            None
-            |
-            [None, None]
-        ):
-            cls: Type[Address] = get_address_cls(_def_tpt_proto)
-            addr: UnwrappedAddress = cls.get_root().unwrap()
-
-        case _:
-            # import pdbp; pdbp.set_trace()
-            raise TypeError(
-                f'Can not wrap unwrapped-address ??\n'
-                f'type(addr): {type(addr)!r}\n'
-                f'addr: {addr!r}\n'
-            )
-
-    return cls.from_addr(addr)
-
-
-def default_lo_addrs(
-    transports: list[str],
-) -> list[Type[Address]]:
-    '''
-    Return the default, host-singleton, registry address
-    for an input transport key set.
-
-    '''
-    return [
-        _default_lo_addrs[transport]
-        for transport in transports
-    ]

tractor/_child.py

@@ -31,12 +31,8 @@ def parse_uid(arg):
     return str(name), str(uuid)  # ensures str encoding
 
 def parse_ipaddr(arg):
-    try:
-        return literal_eval(arg)
-
-    except (ValueError, SyntaxError):
-        # UDS: try to interpret as a straight up str
-        return arg
+    host, port = literal_eval(arg)
+    return (str(host), int(port))
 
 
 if __name__ == "__main__":
@@ -50,8 +46,8 @@ if __name__ == "__main__":
     args = parser.parse_args()
 
     subactor = Actor(
-        name=args.uid[0],
-        uuid=args.uid[1],
+        args.uid[0],
+        uid=args.uid[1],
         loglevel=args.loglevel,
         spawn_method="trio"
     )

tractor/_clustering.py

@@ -19,13 +19,10 @@ Actor cluster helpers.
 
 '''
 from __future__ import annotations
-from contextlib import (
-    asynccontextmanager as acm,
-)
+
+from contextlib import asynccontextmanager as acm
 from multiprocessing import cpu_count
-from typing import (
-    AsyncGenerator,
-)
+from typing import AsyncGenerator, Optional
 
 import trio
 import tractor

tractor/_discovery.py

@@ -26,15 +26,10 @@ from typing import (
     TYPE_CHECKING,
 )
 from contextlib import asynccontextmanager as acm
+import warnings
 
-from tractor.log import get_logger
 from .trionics import gather_contexts
-from .ipc import _connect_chan, Channel
-from ._addr import (
-    UnwrappedAddress,
-    Address,
-    wrap_address
-)
+from ._ipc import _connect_chan, Channel
 from ._portal import (
     Portal,
     open_portal,
@@ -43,51 +38,61 @@ from ._portal import (
 from ._state import (
     current_actor,
     _runtime_vars,
-    _def_tpt_proto,
 )
 
+
 if TYPE_CHECKING:
     from ._runtime import Actor
 
 
-log = get_logger(__name__)
-
-
 @acm
 async def get_registry(
-    addr: UnwrappedAddress|None = None,
+    host: str,
+    port: int,
+
 ) -> AsyncGenerator[
     Portal | LocalPortal | None,
     None,
 ]:
     '''
     Return a portal instance connected to a local or remote
-    registry-service actor; if a connection already exists re-use it
-    (presumably to call a `.register_actor()` registry runtime RPC
-    ep).
+    arbiter.
 
     '''
-    actor: Actor = current_actor()
+    actor = current_actor()
+
+    if not actor:
+        raise RuntimeError("No actor instance has been defined yet?")
+
     if actor.is_registrar:
         # we're already the arbiter
         # (likely a re-entrant call from the arbiter actor)
         yield LocalPortal(
             actor,
-            Channel(transport=None)
-            # ^XXX, we DO NOT actually provide nor connect an
-            # underlying transport since this is merely an API shim.
+            Channel((host, port))
         )
     else:
-        # TODO: try to look pre-existing connection from
-        # `Server._peers` and use it instead?
         async with (
-            _connect_chan(addr) as chan,
+            _connect_chan(host, port) as chan,
             open_portal(chan) as regstr_ptl,
         ):
             yield regstr_ptl
 
 
 
+# TODO: deprecate and this remove _arbiter form!
+@acm
+async def get_arbiter(*args, **kwargs):
+    warnings.warn(
+        '`tractor.get_arbiter()` is now deprecated!\n'
+        'Use `.get_registry()` instead!',
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    async with get_registry(*args, **kwargs) as to_yield:
+        yield to_yield
+
+
 @acm
 async def get_root(
     **kwargs,
@@ -95,68 +100,32 @@ async def get_root(
 
     # TODO: rename mailbox to `_root_maddr` when we finally
     # add and impl libp2p multi-addrs?
-    addr = _runtime_vars['_root_mailbox']
+    host, port = _runtime_vars['_root_mailbox']
+    assert host is not None
 
     async with (
-        _connect_chan(addr) as chan,
+        _connect_chan(host, port) as chan,
         open_portal(chan, **kwargs) as portal,
     ):
         yield portal
 
 
-def get_peer_by_name(
-    name: str,
-    # uuid: str|None = None,
-
-) -> list[Channel]|None:  # at least 1
-    '''
-    Scan for an existing connection (set) to a named actor
-    and return any channels from `Server._peers: dict`.
-
-    This is an optimization method over querying the registrar for
-    the same info.
-
-    '''
-    actor: Actor = current_actor()
-    to_scan: dict[tuple, list[Channel]] = actor.ipc_server._peers.copy()
-
-    # TODO: is this ever needed? creates a duplicate channel on actor._peers
-    # when multiple find_actor calls are made to same actor from a single ctx
-    # which causes actor exit to hang waiting forever on
-    # `actor._no_more_peers.wait()` in `_runtime.async_main`
-
-    # pchan: Channel|None = actor._parent_chan
-    # if pchan and pchan.uid not in to_scan:
-    #     to_scan[pchan.uid].append(pchan)
-
-    for aid, chans in to_scan.items():
-        _, peer_name = aid
-        if name == peer_name:
-            if not chans:
-                log.warning(
-                    'No IPC chans for matching peer {peer_name}\n'
-                )
-                continue
-            return chans
-
-    return None
-
-
 @acm
 async def query_actor(
     name: str,
-    regaddr: UnwrappedAddress|None = None,
+    arbiter_sockaddr: tuple[str, int] | None = None,
+    regaddr: tuple[str, int] | None = None,
 
 ) -> AsyncGenerator[
-    UnwrappedAddress|None,
+    tuple[str, int] | None,
     None,
 ]:
     '''
-    Lookup a transport address (by actor name) via querying a registrar
-    listening @ `regaddr`.
+    Make a transport address lookup for an actor name to a specific
+    registrar.
 
-    Returns the transport protocol (socket) address or `None` if no
-    entry under that name exists.
+    Returns the (socket) address or ``None`` if no entry under that
+    name exists for the given registrar listening @ `regaddr`.
 
     '''
     actor: Actor = current_actor()
@@ -168,48 +137,33 @@ async def query_actor(
             'The current actor IS the registry!?'
         )
 
-    maybe_peers: list[Channel]|None = get_peer_by_name(name)
-    if maybe_peers:
-        yield maybe_peers[0].raddr
-        return
+    if arbiter_sockaddr is not None:
+        warnings.warn(
+            '`tractor.query_actor(regaddr=<blah>)` is deprecated.\n'
+            'Use `registry_addrs: list[tuple]` instead!',
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        regaddr: list[tuple[str, int]] = arbiter_sockaddr
 
     reg_portal: Portal
-    regaddr: Address = wrap_address(regaddr) or actor.reg_addrs[0]
-    async with get_registry(regaddr) as reg_portal:
+    regaddr: tuple[str, int] = regaddr or actor.reg_addrs[0]
+    async with get_registry(*regaddr) as reg_portal:
         # TODO: return portals to all available actors - for now
         # just the last one that registered
-        addr: UnwrappedAddress = await reg_portal.run_from_ns(
+        sockaddr: tuple[str, int] = await reg_portal.run_from_ns(
             'self',
             'find_actor',
             name=name,
         )
-        yield addr
-
-
-@acm
-async def maybe_open_portal(
-    addr: UnwrappedAddress,
-    name: str,
-):
-    async with query_actor(
-        name=name,
-        regaddr=addr,
-    ) as addr:
-        pass
-
-    if addr:
-        async with _connect_chan(addr) as chan:
-            async with open_portal(chan) as portal:
-                yield portal
-    else:
-        yield None
+        yield sockaddr
 
 
 @acm
 async def find_actor(
     name: str,
-    registry_addrs: list[UnwrappedAddress]|None = None,
-    enable_transports: list[str] = [_def_tpt_proto],
+    arbiter_sockaddr: tuple[str, int]|None = None,
+    registry_addrs: list[tuple[str, int]]|None = None,
 
     only_first: bool = True,
     raise_on_none: bool = False,
@@ -225,34 +179,48 @@ async def find_actor(
     known to the arbiter.
 
     '''
-    # optimization path, use any pre-existing peer channel
-    maybe_peers: list[Channel]|None = get_peer_by_name(name)
-    if maybe_peers and only_first:
-        async with open_portal(maybe_peers[0]) as peer_portal:
-            yield peer_portal
-            return
+    if arbiter_sockaddr is not None:
+        warnings.warn(
+            '`tractor.find_actor(arbiter_sockaddr=<blah>)` is deprecated.\n'
+            'Use `registry_addrs: list[tuple]` instead!',
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        registry_addrs: list[tuple[str, int]] = [arbiter_sockaddr]
+
+    @acm
+    async def maybe_open_portal_from_reg_addr(
+        addr: tuple[str, int],
+    ):
+        async with query_actor(
+            name=name,
+            regaddr=addr,
+        ) as sockaddr:
+            if sockaddr:
+                async with _connect_chan(*sockaddr) as chan:
+                    async with open_portal(chan) as portal:
+                        yield portal
+            else:
+                yield None
 
     if not registry_addrs:
         # XXX NOTE: make sure to dynamically read the value on
         # every call since something may change it globally (eg.
         # like in our discovery test suite)!
-        from ._addr import default_lo_addrs
+        from . import _root
         registry_addrs = (
             _runtime_vars['_registry_addrs']
             or
-            default_lo_addrs(enable_transports)
+            _root._default_lo_addrs
         )
 
     maybe_portals: list[
-        AsyncContextManager[UnwrappedAddress]
+        AsyncContextManager[tuple[str, int]]
     ] = list(
-        maybe_open_portal(
-            addr=addr,
-            name=name,
-        )
+        maybe_open_portal_from_reg_addr(addr)
         for addr in registry_addrs
     )
-    portals: list[Portal]
+
     async with gather_contexts(
         mngrs=maybe_portals,
     ) as portals:
@@ -286,33 +254,33 @@ async def find_actor(
 @acm
 async def wait_for_actor(
     name: str,
-    registry_addr: UnwrappedAddress | None = None,
+    arbiter_sockaddr: tuple[str, int] | None = None,
+    registry_addr: tuple[str, int] | None = None,
 
 ) -> AsyncGenerator[Portal, None]:
     '''
-    Wait on at least one peer actor to register `name` with the
-    registrar, yield a `Portal to the first registree.
+    Wait on an actor to register with the arbiter.
+
+    A portal to the first registered actor is returned.
 
     '''
     actor: Actor = current_actor()
 
-    # optimization path, use any pre-existing peer channel
-    maybe_peers: list[Channel]|None = get_peer_by_name(name)
-    if maybe_peers:
-        async with open_portal(maybe_peers[0]) as peer_portal:
-            yield peer_portal
-            return
+    if arbiter_sockaddr is not None:
+        warnings.warn(
+            '`tractor.wait_for_actor(arbiter_sockaddr=<foo>)` is deprecated.\n'
+            'Use `registry_addr: tuple` instead!',
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        registry_addr: tuple[str, int] = arbiter_sockaddr
 
-    regaddr: UnwrappedAddress = (
-        registry_addr
-        or
-        actor.reg_addrs[0]
-    )
     # TODO: use `.trionics.gather_contexts()` like
     # above in `find_actor()` as well?
     reg_portal: Portal
-    async with get_registry(regaddr) as reg_portal:
-        addrs = await reg_portal.run_from_ns(
+    regaddr: tuple[str, int] = registry_addr or actor.reg_addrs[0]
+    async with get_registry(*regaddr) as reg_portal:
+        sockaddrs = await reg_portal.run_from_ns(
             'self',
             'wait_for_actor',
             name=name,
@@ -320,8 +288,8 @@ async def wait_for_actor(
 
         # get latest registered addr by default?
         # TODO: offer multi-portal yields in multi-homed case?
-        addr: UnwrappedAddress = addrs[-1]
+        sockaddr: tuple[str, int] = sockaddrs[-1]
 
-        async with _connect_chan(addr) as chan:
+        async with _connect_chan(*sockaddr) as chan:
             async with open_portal(chan) as portal:
                 yield portal

tractor/_entry.py

@@ -20,8 +20,6 @@ Sub-process entry points.
 """
 from __future__ import annotations
 from functools import partial
-import multiprocessing as mp
-import os
 from typing import (
     Any,
     TYPE_CHECKING,
@@ -34,12 +32,7 @@ from .log import (
     get_logger,
 )
 from . import _state
-from .devx import (
-    _frame_stack,
-    pformat,
-)
 from .to_asyncio import run_as_asyncio_guest
-from ._addr import UnwrappedAddress
 from ._runtime import (
     async_main,
     Actor,
@@ -55,35 +48,33 @@ log = get_logger(__name__)
 def _mp_main(
 
     actor: Actor,
-    accept_addrs: list[UnwrappedAddress],
+    accept_addrs: list[tuple[str, int]],
     forkserver_info: tuple[Any, Any, Any, Any, Any],
     start_method: SpawnMethodKey,
-    parent_addr: UnwrappedAddress | None = None,
+    parent_addr: tuple[str, int] | None = None,
     infect_asyncio: bool = False,
 
 ) -> None:
     '''
-    The routine called *after fork* which invokes a fresh `trio.run()`
+    The routine called *after fork* which invokes a fresh ``trio.run``
 
     '''
     actor._forkserver_info = forkserver_info
     from ._spawn import try_set_start_method
-    spawn_ctx: mp.context.BaseContext = try_set_start_method(start_method)
-    assert spawn_ctx
+    spawn_ctx = try_set_start_method(start_method)
 
     if actor.loglevel is not None:
         log.info(
-            f'Setting loglevel for {actor.uid} to {actor.loglevel}'
-        )
+            f"Setting loglevel for {actor.uid} to {actor.loglevel}")
         get_console_log(actor.loglevel)
 
-    # TODO: use scops headers like for `trio` below!
-    # (well after we libify it maybe..)
+    assert spawn_ctx
     log.info(
-        f'Started new {spawn_ctx.current_process()} for {actor.uid}'
-    #     f"parent_addr is {parent_addr}"
-    )
-    _state._current_actor: Actor = actor
+        f"Started new {spawn_ctx.current_process()} for {actor.uid}")
+
+    _state._current_actor = actor
+
+    log.debug(f"parent_addr is {parent_addr}")
     trio_main = partial(
         async_main,
         actor=actor,
@@ -100,15 +91,14 @@ def _mp_main(
         pass  # handle it the same way trio does?
 
     finally:
-        log.info(
-            f'`mp`-subactor {actor.uid} exited'
-        )
+        log.info(f"Actor {actor.uid} terminated")
 
 
 def _trio_main(
+
     actor: Actor,
     *,
-    parent_addr: UnwrappedAddress|None = None,
+    parent_addr: tuple[str, int] | None = None,
     infect_asyncio: bool = False,
 
 ) -> None:
@@ -116,8 +106,7 @@ def _trio_main(
     Entry point for a `trio_run_in_process` subactor.
 
     '''
-    _frame_stack.hide_runtime_frames()
-
+    __tracebackhide__: bool = True
     _state._current_actor = actor
     trio_main = partial(
         async_main,
@@ -127,6 +116,7 @@ def _trio_main(
 
     if actor.loglevel is not None:
         get_console_log(actor.loglevel)
+        import os
         actor_info: str = (
             f'|_{actor}\n'
             f'  uid: {actor.uid}\n'
@@ -135,54 +125,27 @@ def _trio_main(
             f'  loglevel: {actor.loglevel}\n'
         )
         log.info(
-            'Starting new `trio` subactor\n'
+            'Started new trio process:\n'
             +
-            pformat.nest_from_op(
-                input_op='>(',  # see syntax ideas above
-                text=actor_info,
-                nest_indent=2,  # since "complete"
-            )
+            actor_info
         )
-    logmeth = log.info
-    exit_status: str = (
-        'Subactor exited\n'
-        +
-        pformat.nest_from_op(
-            input_op=')>',  # like a "closed-to-play"-icon from super perspective
-            text=actor_info,
-            nest_indent=1,
-        )
-    )
+
     try:
         if infect_asyncio:
             actor._infected_aio = True
             run_as_asyncio_guest(trio_main)
         else:
             trio.run(trio_main)
-
     except KeyboardInterrupt:
-        logmeth = log.cancel
-        exit_status: str = (
-            'Actor received KBI (aka an OS-cancel)\n'
+        log.cancel(
+            'Actor received KBI\n'
             +
-            pformat.nest_from_op(
-                input_op='c)>',  # closed due to cancel (see above)
-                text=actor_info,
-            )
+            actor_info
         )
-    except BaseException as err:
-        logmeth = log.error
-        exit_status: str = (
-            'Main actor task exited due to crash?\n'
-            +
-            pformat.nest_from_op(
-                input_op='x)>',  # closed by error
-                text=actor_info,
-            )
-        )
-        # NOTE since we raise a tb will already be shown on the
-        # console, thus we do NOT use `.exception()` above.
-        raise err
 
     finally:
-        logmeth(exit_status)
+        log.info(
+            'Actor terminated\n'
+            +
+            actor_info
+        )

tractor/_ipc.py

@@ -0,0 +1,532 @@
+# tractor: structured concurrent "actors".
+# Copyright 2018-eternity Tyler Goodlet.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""
+Inter-process comms abstractions
+
+"""
+from __future__ import annotations
+from collections.abc import (
+    AsyncGenerator,
+    AsyncIterator,
+)
+from contextlib import asynccontextmanager as acm
+import platform
+from pprint import pformat
+import struct
+import typing
+from typing import (
+    Any,
+    runtime_checkable,
+    Protocol,
+    Type,
+    TypeVar,
+)
+
+import msgspec
+from tricycle import BufferedReceiveStream
+import trio
+
+from tractor.log import get_logger
+from tractor._exceptions import TransportClosed
+
+log = get_logger(__name__)
+
+_is_windows = platform.system() == 'Windows'
+
+
+def get_stream_addrs(stream: trio.SocketStream) -> tuple:
+    # should both be IP sockets
+    lsockname = stream.socket.getsockname()
+    rsockname = stream.socket.getpeername()
+    return (
+        tuple(lsockname[:2]),
+        tuple(rsockname[:2]),
+    )
+
+
+MsgType = TypeVar("MsgType")
+
+# TODO: consider using a generic def and indexing with our eventual
+# msg definition/types?
+# - https://docs.python.org/3/library/typing.html#typing.Protocol
+# - https://jcristharif.com/msgspec/usage.html#structs
+
+
+@runtime_checkable
+class MsgTransport(Protocol[MsgType]):
+
+    stream: trio.SocketStream
+    drained: list[MsgType]
+
+    def __init__(self, stream: trio.SocketStream) -> None:
+        ...
+
+    # XXX: should this instead be called `.sendall()`?
+    async def send(self, msg: MsgType) -> None:
+        ...
+
+    async def recv(self) -> MsgType:
+        ...
+
+    def __aiter__(self) -> MsgType:
+        ...
+
+    def connected(self) -> bool:
+        ...
+
+    # defining this sync otherwise it causes a mypy error because it
+    # can't figure out it's a generator i guess?..?
+    def drain(self) -> AsyncIterator[dict]:
+        ...
+
+    @property
+    def laddr(self) -> tuple[str, int]:
+        ...
+
+    @property
+    def raddr(self) -> tuple[str, int]:
+        ...
+
+
+# TODO: not sure why we have to inherit here, but it seems to be an
+# issue with ``get_msg_transport()`` returning a ``Type[Protocol]``;
+# probably should make a `mypy` issue?
+class MsgpackTCPStream(MsgTransport):
+    '''
+    A ``trio.SocketStream`` delivering ``msgpack`` formatted data
+    using the ``msgspec`` codec lib.
+
+    '''
+    layer_key: int = 4
+    name_key: str = 'tcp'
+
+    # TODO: better naming for this?
+    # -[ ] check how libp2p does naming for such things?
+    codec_key: str = 'msgpack'
+
+    def __init__(
+        self,
+        stream: trio.SocketStream,
+        prefix_size: int = 4,
+
+    ) -> None:
+
+        self.stream = stream
+        assert self.stream.socket
+
+        # should both be IP sockets
+        self._laddr, self._raddr = get_stream_addrs(stream)
+
+        # create read loop instance
+        self._agen = self._iter_packets()
+        self._send_lock = trio.StrictFIFOLock()
+
+        # public i guess?
+        self.drained: list[dict] = []
+
+        self.recv_stream = BufferedReceiveStream(transport_stream=stream)
+        self.prefix_size = prefix_size
+
+        # TODO: struct aware messaging coders
+        self.encode = msgspec.msgpack.Encoder().encode
+        self.decode = msgspec.msgpack.Decoder().decode  # dict[str, Any])
+
+    async def _iter_packets(self) -> AsyncGenerator[dict, None]:
+        '''Yield packets from the underlying stream.
+
+        '''
+        import msgspec  # noqa
+        decodes_failed: int = 0
+
+        while True:
+            try:
+                header = await self.recv_stream.receive_exactly(4)
+
+            except (
+                ValueError,
+                ConnectionResetError,
+
+                # not sure entirely why we need this but without it we
+                # seem to be getting racy failures here on
+                # arbiter/registry name subs..
+                trio.BrokenResourceError,
+            ):
+                raise TransportClosed(
+                    f'transport {self} was already closed prior ro read'
+                )
+
+            if header == b'':
+                raise TransportClosed(
+                    f'transport {self} was already closed prior ro read'
+                )
+
+            size, = struct.unpack("<I", header)
+
+            log.transport(f'received header {size}')  # type: ignore
+
+            msg_bytes = await self.recv_stream.receive_exactly(size)
+
+            log.transport(f"received {msg_bytes}")  # type: ignore
+            try:
+                yield self.decode(msg_bytes)
+            except (
+                msgspec.DecodeError,
+                UnicodeDecodeError,
+            ):
+                if decodes_failed < 4:
+                    # ignore decoding errors for now and assume they have to
+                    # do with a channel drop - hope that receiving from the
+                    # channel will raise an expected error and bubble up.
+                    try:
+                        msg_str: str | bytes = msg_bytes.decode()
+                    except UnicodeDecodeError:
+                        msg_str = msg_bytes
+
+                    log.error(
+                        '`msgspec` failed to decode!?\n'
+                        'dumping bytes:\n'
+                        f'{msg_str!r}'
+                    )
+                    decodes_failed += 1
+                else:
+                    raise
+
+    async def send(
+        self,
+        msg: Any,
+
+        # hide_tb: bool = False,
+    ) -> None:
+        '''
+        Send a msgpack coded blob-as-msg over TCP.
+
+        '''
+        # __tracebackhide__: bool = hide_tb
+        async with self._send_lock:
+
+            bytes_data: bytes = self.encode(msg)
+
+            # supposedly the fastest says,
+            # https://stackoverflow.com/a/54027962
+            size: bytes = struct.pack("<I", len(bytes_data))
+
+            return await self.stream.send_all(size + bytes_data)
+
+    @property
+    def laddr(self) -> tuple[str, int]:
+        return self._laddr
+
+    @property
+    def raddr(self) -> tuple[str, int]:
+        return self._raddr
+
+    async def recv(self) -> Any:
+        return await self._agen.asend(None)
+
+    async def drain(self) -> AsyncIterator[dict]:
+        '''
+        Drain the stream's remaining messages sent from
+        the far end until the connection is closed by
+        the peer.
+
+        '''
+        try:
+            async for msg in self._iter_packets():
+                self.drained.append(msg)
+        except TransportClosed:
+            for msg in self.drained:
+                yield msg
+
+    def __aiter__(self):
+        return self._agen
+
+    def connected(self) -> bool:
+        return self.stream.socket.fileno() != -1
+
+
+def get_msg_transport(
+
+    key: tuple[str, str],
+
+) -> Type[MsgTransport]:
+
+    return {
+        ('msgpack', 'tcp'): MsgpackTCPStream,
+    }[key]
+
+
+class Channel:
+    '''
+    An inter-process channel for communication between (remote) actors.
+
+    Wraps a ``MsgStream``: transport + encoding IPC connection.
+
+    Currently we only support ``trio.SocketStream`` for transport
+    (aka TCP) and the ``msgpack`` interchange format via the ``msgspec``
+    codec libary.
+
+    '''
+    def __init__(
+
+        self,
+        destaddr: tuple[str, int]|None,
+
+        msg_transport_type_key: tuple[str, str] = ('msgpack', 'tcp'),
+
+        # TODO: optional reconnection support?
+        # auto_reconnect: bool = False,
+        # on_reconnect: typing.Callable[..., typing.Awaitable] = None,
+
+    ) -> None:
+
+        # self._recon_seq = on_reconnect
+        # self._autorecon = auto_reconnect
+
+        self._destaddr = destaddr
+        self._transport_key = msg_transport_type_key
+
+        # Either created in ``.connect()`` or passed in by
+        # user in ``.from_stream()``.
+        self._stream: trio.SocketStream|None = None
+        self._transport: MsgTransport|None = None
+
+        # set after handshake - always uid of far end
+        self.uid: tuple[str, str]|None = None
+
+        self._agen = self._aiter_recv()
+        self._exc: Exception|None = None  # set if far end actor errors
+        self._closed: bool = False
+
+        # flag set by ``Portal.cancel_actor()`` indicating remote
+        # (possibly peer) cancellation of the far end actor
+        # runtime.
+        self._cancel_called: bool = False
+
+    @property
+    def msgstream(self) -> MsgTransport:
+        log.info('`Channel.msgstream` is an old name, use `._transport`')
+        return self._transport
+
+    @property
+    def transport(self) -> MsgTransport:
+        return self._transport
+
+    @classmethod
+    def from_stream(
+        cls,
+        stream: trio.SocketStream,
+        **kwargs,
+
+    ) -> Channel:
+
+        src, dst = get_stream_addrs(stream)
+        chan = Channel(
+            destaddr=dst,
+            **kwargs,
+        )
+
+        # set immediately here from provided instance
+        chan._stream: trio.SocketStream = stream
+        chan.set_msg_transport(stream)
+        return chan
+
+    def set_msg_transport(
+        self,
+        stream: trio.SocketStream,
+        type_key: tuple[str, str]|None = None,
+
+    ) -> MsgTransport:
+        type_key = type_key or self._transport_key
+        self._transport = get_msg_transport(type_key)(stream)
+        return self._transport
+
+    def __repr__(self) -> str:
+        if not self._transport:
+            return '<Channel with inactive transport?>'
+
+        return repr(
+            self._transport.stream.socket._sock
+        ).replace(  # type: ignore
+            "socket.socket",
+            "Channel",
+        )
+
+    @property
+    def laddr(self) -> tuple[str, int]|None:
+        return self._transport.laddr if self._transport else None
+
+    @property
+    def raddr(self) -> tuple[str, int]|None:
+        return self._transport.raddr if self._transport else None
+
+    async def connect(
+        self,
+        destaddr: tuple[Any, ...] | None = None,
+        **kwargs
+
+    ) -> MsgTransport:
+
+        if self.connected():
+            raise RuntimeError("channel is already connected?")
+
+        destaddr = destaddr or self._destaddr
+        assert isinstance(destaddr, tuple)
+
+        stream = await trio.open_tcp_stream(
+            *destaddr,
+            **kwargs
+        )
+        transport = self.set_msg_transport(stream)
+
+        log.transport(
+            f'Opened channel[{type(transport)}]: {self.laddr} -> {self.raddr}'
+        )
+        return transport
+
+    async def send(
+        self,
+        payload: Any,
+
+        # hide_tb: bool = False,
+
+    ) -> None:
+        '''
+        Send a coded msg-blob over the transport.
+
+        '''
+        # __tracebackhide__: bool = hide_tb
+        log.transport(
+            '=> send IPC msg:\n\n'
+            f'{pformat(payload)}\n'
+        )  # type: ignore
+        assert self._transport
+
+        await self._transport.send(
+            payload,
+            # hide_tb=hide_tb,
+        )
+
+    async def recv(self) -> Any:
+        assert self._transport
+        return await self._transport.recv()
+
+        # try:
+        #     return await self._transport.recv()
+        # except trio.BrokenResourceError:
+        #     if self._autorecon:
+        #         await self._reconnect()
+        #         return await self.recv()
+        #     raise
+
+    async def aclose(self) -> None:
+
+        log.transport(
+            f'Closing channel to {self.uid} '
+            f'{self.laddr} -> {self.raddr}'
+        )
+        assert self._transport
+        await self._transport.stream.aclose()
+        self._closed = True
+
+    async def __aenter__(self):
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *args):
+        await self.aclose(*args)
+
+    def __aiter__(self):
+        return self._agen
+
+    # async def _reconnect(self) -> None:
+    #     """Handle connection failures by polling until a reconnect can be
+    #     established.
+    #     """
+    #     down = False
+    #     while True:
+    #         try:
+    #             with trio.move_on_after(3) as cancel_scope:
+    #                 await self.connect()
+    #             cancelled = cancel_scope.cancelled_caught
+    #             if cancelled:
+    #                 log.transport(
+    #                     "Reconnect timed out after 3 seconds, retrying...")
+    #                 continue
+    #             else:
+    #                 log.transport("Stream connection re-established!")
+
+    #                 # TODO: run any reconnection sequence
+    #                 # on_recon = self._recon_seq
+    #                 # if on_recon:
+    #                 #     await on_recon(self)
+
+    #                 break
+    #         except (OSError, ConnectionRefusedError):
+    #             if not down:
+    #                 down = True
+    #                 log.transport(
+    #                     f"Connection to {self.raddr} went down, waiting"
+    #                     " for re-establishment")
+    #             await trio.sleep(1)
+
+    async def _aiter_recv(
+        self
+    ) -> AsyncGenerator[Any, None]:
+        '''
+        Async iterate items from underlying stream.
+
+        '''
+        assert self._transport
+        while True:
+            try:
+                async for item in self._transport:
+                    yield item
+                    # sent = yield item
+                    # if sent is not None:
+                    #     # optimization, passing None through all the
+                    #     # time is pointless
+                    #     await self._transport.send(sent)
+            except trio.BrokenResourceError:
+
+                # if not self._autorecon:
+                raise
+
+            await self.aclose()
+
+            # if self._autorecon:  # attempt reconnect
+            #     await self._reconnect()
+            #     continue
+
+    def connected(self) -> bool:
+        return self._transport.connected() if self._transport else False
+
+
+@acm
+async def _connect_chan(
+    host: str,
+    port: int
+
+) -> typing.AsyncGenerator[Channel, None]:
+    '''
+    Create and connect a channel with disconnect on context manager
+    teardown.
+
+    '''
+    chan = Channel((host, port))
+    await chan.connect()
+    yield chan
+    await chan.aclose()

tractor/_portal.py

@@ -31,7 +31,7 @@ from typing import (
     Any,
     Callable,
     AsyncGenerator,
-    TYPE_CHECKING,
+    # Type,
 )
 from functools import partial
 from dataclasses import dataclass
@@ -43,17 +43,12 @@ from .trionics import maybe_open_nursery
 from ._state import (
     current_actor,
 )
-from .ipc import Channel
+from ._ipc import Channel
 from .log import get_logger
-from .msg import (
-    # Error,
-    PayloadMsg,
-    NamespacePath,
-    Return,
-)
+from .msg import NamespacePath
 from ._exceptions import (
+    unpack_error,
     NoResult,
-    TransportClosed,
 )
 from ._context import (
     Context,
@@ -63,12 +58,41 @@ from ._streaming import (
     MsgStream,
 )
 
-if TYPE_CHECKING:
-    from ._runtime import Actor
 
 log = get_logger(__name__)
 
 
+# TODO: rename to `unwrap_result()` and use
+# `._raise_from_no_key_in_msg()` (after tweak to
+# accept a `chan: Channel` arg) in key block!
+def _unwrap_msg(
+    msg: dict[str, Any],
+    channel: Channel,
+
+    hide_tb: bool = True,
+
+) -> Any:
+    '''
+    Unwrap a final result from a `{return: <Any>}` IPC msg.
+
+    '''
+    __tracebackhide__: bool = hide_tb
+
+    try:
+        return msg['return']
+    except KeyError as ke:
+
+        # internal error should never get here
+        assert msg.get('cid'), (
+            "Received internal error at portal?"
+        )
+
+        raise unpack_error(
+            msg,
+            channel
+        ) from ke
+
+
 class Portal:
     '''
     A 'portal' to a memory-domain-separated `Actor`.
@@ -92,30 +116,17 @@ class Portal:
     # connected (peer) actors.
     cancel_timeout: float = 0.5
 
-    def __init__(
-        self,
-        channel: Channel,
-    ) -> None:
-
-        self._chan: Channel = channel
+    def __init__(self, channel: Channel) -> None:
+        self.chan = channel
         # during the portal's lifetime
-        self._final_result_pld: Any|None = None
-        self._final_result_msg: PayloadMsg|None = None
+        self._result_msg: dict|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._expect_result: Context | None = None
         self._streams: set[MsgStream] = set()
-
-        # TODO, this should be PRIVATE (and never used publicly)! since it's just
-        # a cached ref to the local runtime instead of calling
-        # `current_actor()` everywhere.. XD
-        self.actor: Actor = current_actor()
-
-    @property
-    def chan(self) -> Channel:
-        return self._chan
+        self.actor = current_actor()
 
     @property
     def channel(self) -> Channel:
@@ -129,8 +140,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,
@@ -138,34 +147,32 @@ class Portal:
         **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,
+        assert self._expect_result is None, (
+            "A pending main result has already been submitted"
         )
 
-    # 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._expect_result = await self.actor.start_remote_task(
+            self.channel,
+            nsf=NamespacePath(f'{ns}:{func}'),
+            kwargs=kwargs
+        )
+
+    async def _return_once(
         self,
-        hide_tb: bool = True,
-    ) -> Any:
+        ctx: Context,
+
+    ) -> dict[str, Any]:
+
+        assert ctx._remote_func_type == 'asyncfunc'  # single response
+        msg: dict = await ctx._recv_chan.receive()
+        return msg
+
+    async def result(self) -> Any:
         '''
-        Return the final result delivered by a `Return`-msg from the
-        remote peer actor's "main" task's `return` statement.
+        Return the result(s) from the remote actor's "main" task.
 
         '''
-        __tracebackhide__: bool = hide_tb
+        # __tracebackhide__ = True
         # Check for non-rpc errors slapped on the
         # channel for which we always raise
         exc = self.channel._exc
@@ -173,48 +180,24 @@ class Portal:
             raise exc
 
         # not expecting a "main" result
-        if self._expect_result_ctx is None:
+        if self._expect_result is None:
             log.warning(
-                f"Portal for {self.channel.aid} not expecting a final"
+                f"Portal for {self.channel.uid} not expecting a final"
                 " result?\nresult() should only be called if subactor"
                 " was spawned with `ActorNursery.run_in_actor()`")
             return NoResult
 
         # expecting a "main" result
-        assert self._expect_result_ctx
+        assert self._expect_result
 
-        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
+        if self._result_msg is None:
+            self._result_msg = await self._return_once(
+                self._expect_result
+            )
 
-        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'Use `{typname}.wait_for_result()` instead!\n'
-        )
-        return await self.wait_for_result(
-            *args,
-            **kwargs,
+        return _unwrap_msg(
+            self._result_msg,
+            self.channel,
         )
 
     async def _cancel_streams(self):
@@ -222,7 +205,7 @@ class Portal:
         # IPC calls
         if self._streams:
             log.cancel(
-                f"Cancelling all streams with {self.channel.aid}")
+                f"Cancelling all streams with {self.channel.uid}")
             for stream in self._streams.copy():
                 try:
                     await stream.aclose()
@@ -257,8 +240,6 @@ class Portal:
         purpose.
 
         '''
-        __runtimeframe__: int = 1  # noqa
-
         chan: Channel = self.channel
         if not chan.connected():
             log.runtime(
@@ -267,15 +248,14 @@ class Portal:
             return False
 
         reminfo: str = (
-            f'c)=> {self.channel.aid}\n'
-            f'  |_{chan}\n'
+            f'`Portal.cancel_actor()` => {self.channel.uid}\n'
+            f' |_{chan}\n'
         )
         log.cancel(
-            f'Requesting actor-runtime cancel for peer\n\n'
+            f'Sending runtime `.cancel()` request to peer\n\n'
             f'{reminfo}'
         )
 
-        # XXX the one spot we set it?
         self.channel._cancel_called: bool = True
         try:
             # send cancel cmd - might not get response
@@ -305,38 +285,16 @@ class Portal:
             return False
 
         except (
-            # XXX, should never really get raised unless we aren't
-            # wrapping them in the below type by mistake?
-            #
-            # Leaving the catch here for now until we're very sure
-            # all the cases (for various tpt protos) have indeed been
-            # re-wrapped ;p
             trio.ClosedResourceError,
             trio.BrokenResourceError,
-
-            TransportClosed,
-        ) as tpt_err:
-            report: str = (
-                f'IPC chan for actor already closed or broken?\n\n'
-                f'{self.channel.aid}\n'
+        ):
+            log.debug(
+                'IPC chan for actor already closed or broken?\n\n'
+                f'{self.channel.uid}\n'
                 f' |_{self.channel}\n'
             )
-            match tpt_err:
-                case TransportClosed():
-                    log.debug(report)
-                case _:
-                    report += (
-                        f'\n'
-                        f'Unhandled low-level transport-closed/error during\n'
-                        f'Portal.cancel_actor()` request?\n'
-                        f'<{type(tpt_err).__name__}( {tpt_err} )>\n'
-                    )
-                    log.warning(report)
-
             return False
 
-    # TODO: do we still need this for low level `Actor`-runtime
-    # method calls or can we also remove it?
     async def run_from_ns(
         self,
         namespace_path: str,
@@ -359,23 +317,21 @@ class Portal:
           internals!
 
         '''
-        __runtimeframe__: int = 1  # noqa
         nsf = NamespacePath(
             f'{namespace_path}:{function_name}'
         )
-        ctx: Context = await self.actor.start_remote_task(
+        ctx = await self.actor.start_remote_task(
             chan=self.channel,
             nsf=nsf,
             kwargs=kwargs,
-            portal=self,
         )
-        return await ctx._pld_rx.recv_pld(
-            ipc=ctx,
-            expect_msg=Return,
+        ctx._portal = self
+        msg = await self._return_once(ctx)
+        return _unwrap_msg(
+            msg,
+            self.channel,
         )
 
-    # TODO: factor this out into a `.highlevel` API-wrapper that uses
-    # a single `.open_context()` call underneath.
     async def run(
         self,
         func: str,
@@ -391,8 +347,6 @@ class Portal:
         remote rpc task or a local async generator instance.
 
         '''
-        __runtimeframe__: int = 1  # noqa
-
         if isinstance(func, str):
             warnings.warn(
                 "`Portal.run(namespace: str, funcname: str)` is now"
@@ -423,15 +377,13 @@ class Portal:
             self.channel,
             nsf=nsf,
             kwargs=kwargs,
-            portal=self,
         )
-        return await ctx._pld_rx.recv_pld(
-            ipc=ctx,
-            expect_msg=Return,
+        ctx._portal = self
+        return _unwrap_msg(
+            await self._return_once(ctx),
+            self.channel,
         )
 
-    # TODO: factor this out into a `.highlevel` API-wrapper that uses
-    # a single `.open_context()` call underneath.
     @acm
     async def open_stream_from(
         self,
@@ -439,14 +391,6 @@ class Portal:
         **kwargs,
 
     ) -> AsyncGenerator[MsgStream, None]:
-        '''
-        Legacy one-way streaming API.
-
-        TODO: re-impl on top `Portal.open_context()` + an async gen
-        around `Context.open_stream()`.
-
-        '''
-        __runtimeframe__: int = 1  # noqa
 
         if not inspect.isasyncgenfunction(async_gen_func):
             if not (
@@ -460,8 +404,8 @@ class Portal:
             self.channel,
             nsf=NamespacePath.from_ref(async_gen_func),
             kwargs=kwargs,
-            portal=self,
         )
+        ctx._portal = self
 
         # ensure receive-only stream entrypoint
         assert ctx._remote_func_type == 'asyncgen'
@@ -470,13 +414,13 @@ class Portal:
             # deliver receive only stream
             async with MsgStream(
                 ctx=ctx,
-                rx_chan=ctx._rx_chan,
-            ) as stream:
-                self._streams.add(stream)
-                ctx._stream = stream
-                yield stream
+                rx_chan=ctx._recv_chan,
+            ) as rchan:
+                self._streams.add(rchan)
+                yield rchan
 
         finally:
+
             # cancel the far end task on consumer close
             # NOTE: this is a special case since we assume that if using
             # this ``.open_fream_from()`` api, the stream is one a one
@@ -495,7 +439,7 @@ class Portal:
 
             # XXX: should this always be done?
             # await recv_chan.aclose()
-            self._streams.remove(stream)
+            self._streams.remove(rchan)
 
     # NOTE: impl is found in `._context`` mod to make
     # reading/groking the details simpler code-org-wise. This
@@ -528,12 +472,8 @@ class LocalPortal:
         return it's result.
 
         '''
-        obj = (
-            self.actor
-            if ns == 'self'
-            else importlib.import_module(ns)
-        )
-        func: Callable = getattr(obj, func_name)
+        obj = self.actor if ns == 'self' else importlib.import_module(ns)
+        func = getattr(obj, func_name)
         return await func(**kwargs)
 
 
@@ -541,7 +481,7 @@ class LocalPortal:
 async def open_portal(
 
     channel: Channel,
-    tn: trio.Nursery|None = None,
+    nursery: trio.Nursery|None = None,
     start_msg_loop: bool = True,
     shield: bool = False,
 
@@ -549,40 +489,31 @@ async def open_portal(
     '''
     Open a ``Portal`` through the provided ``channel``.
 
-    Spawns a background task to handle RPC processing, normally
-    done by the actor-runtime implicitly via a call to
-    `._rpc.process_messages()`. just after connection establishment.
+    Spawns a background task to handle message processing (normally
+    done by the actor-runtime implicitly).
 
     '''
     actor = current_actor()
     assert actor
-    was_connected: bool = False
+    was_connected = False
 
-    async with maybe_open_nursery(
-        tn,
-        shield=shield,
-        strict_exception_groups=False,
-        # ^XXX^ TODO? soo roll our own then ??
-        # -> since we kinda want the "if only one `.exception` then
-        # just raise that" interface?
-    ) as tn:
+    async with maybe_open_nursery(nursery, shield=shield) as nursery:
 
         if not channel.connected():
             await channel.connect()
             was_connected = True
 
-        if channel.aid is None:
-            await channel._do_handshake(
-                aid=actor.aid,
-            )
+        if channel.uid is None:
+            await actor._do_handshake(channel)
 
         msg_loop_cs: trio.CancelScope|None = None
         if start_msg_loop:
-            from . import _rpc
-            msg_loop_cs = await tn.start(
+            from ._runtime import process_messages
+            msg_loop_cs = await nursery.start(
                 partial(
-                    _rpc.process_messages,
-                    chan=channel,
+                    process_messages,
+                    actor,
+                    channel,
                     # if the local task is cancelled we want to keep
                     # the msg loop running until our block ends
                     shield=True,
@@ -595,10 +526,12 @@ async def open_portal(
             await portal.aclose()
 
             if was_connected:
-                await channel.aclose()
+                # gracefully signal remote channel-msg loop
+                await channel.send(None)
+                # await channel.aclose()
 
             # cancel background msg loop task
-            if msg_loop_cs is not None:
+            if msg_loop_cs:
                 msg_loop_cs.cancel()
 
-            tn.cancel_scope.cancel()
+            nursery.cancel_scope.cancel()

tractor/_root.py

@@ -18,20 +18,14 @@
 Root actor runtime ignition(s).
 
 '''
-from contextlib import (
-    asynccontextmanager as acm,
-)
+from contextlib import asynccontextmanager
 from functools import partial
 import importlib
-import inspect
 import logging
 import os
 import signal
 import sys
-from typing import (
-    Any,
-    Callable,
-)
+from typing import Callable
 import warnings
 
 
@@ -44,118 +38,37 @@ from ._runtime import (
     # Arbiter as Registry,
     async_main,
 )
-from .devx import (
-    debug,
-    _frame_stack,
-)
+from .devx import _debug
 from . import _spawn
 from . import _state
 from . import log
-from .ipc import (
-    _connect_chan,
-)
-from ._addr import (
-    Address,
-    UnwrappedAddress,
-    default_lo_addrs,
-    mk_uuid,
-    wrap_address,
-)
-from ._exceptions import (
-    RuntimeFailure,
-    is_multi_cancelled,
-)
+from ._ipc import _connect_chan
+from ._exceptions import is_multi_cancelled
+
+
+# set at startup and after forks
+_default_host: str = '127.0.0.1'
+_default_port: int = 1616
+
+# default registry always on localhost
+_default_lo_addrs: list[tuple[str, int]] = [(
+    _default_host,
+    _default_port,
+)]
 
 
 logger = log.get_logger('tractor')
 
 
-# TODO: stick this in a `@acm` defined in `devx.debug`?
-# -[ ] also maybe consider making this a `wrapt`-deco to
-#     save an indent level?
-#
-@acm
-async def maybe_block_bp(
-    debug_mode: bool,
-    maybe_enable_greenback: bool,
-) -> bool:
-    # Override the global debugger hook to make it play nice with
-    # ``trio``, see much discussion in:
-    # https://github.com/python-trio/trio/issues/1155#issuecomment-742964018
-    builtin_bp_handler: Callable = sys.breakpointhook
-    orig_bp_path: str|None = os.environ.get(
-        'PYTHONBREAKPOINT',
-        None,
-    )
-    bp_blocked: bool
-    if (
-        debug_mode
-        and maybe_enable_greenback
-        and (
-            maybe_mod := await debug.maybe_init_greenback(
-                raise_not_found=False,
-            )
-        )
-    ):
-        logger.info(
-            f'Found `greenback` installed @ {maybe_mod}\n'
-            'Enabling `tractor.pause_from_sync()` support!\n'
-        )
-        os.environ['PYTHONBREAKPOINT'] = (
-            'tractor.devx.debug._sync_pause_from_builtin'
-        )
-        _state._runtime_vars['use_greenback'] = True
-        bp_blocked = False
-
-    else:
-        # TODO: disable `breakpoint()` by default (without
-        # `greenback`) since it will break any multi-actor
-        # usage by a clobbered TTY's stdstreams!
-        def block_bps(*args, **kwargs):
-            raise RuntimeError(
-                'Trying to use `breakpoint()` eh?\n\n'
-                'Welp, `tractor` blocks `breakpoint()` built-in calls by default!\n'
-                'If you need to use it please install `greenback` and set '
-                '`debug_mode=True` when opening the runtime '
-                '(either via `.open_nursery()` or `open_root_actor()`)\n'
-            )
-
-        sys.breakpointhook = block_bps
-        # lol ok,
-        # https://docs.python.org/3/library/sys.html#sys.breakpointhook
-        os.environ['PYTHONBREAKPOINT'] = "0"
-        bp_blocked = True
-
-    try:
-        yield bp_blocked
-    finally:
-        # restore any prior built-in `breakpoint()` hook state
-        if builtin_bp_handler is not None:
-            sys.breakpointhook = builtin_bp_handler
-
-        if orig_bp_path is not None:
-            os.environ['PYTHONBREAKPOINT'] = orig_bp_path
-
-        else:
-            # clear env back to having no entry
-            os.environ.pop('PYTHONBREAKPOINT', None)
-
-
-
-@acm
+@asynccontextmanager
 async def open_root_actor(
+
     *,
     # defaults are above
-    registry_addrs: list[UnwrappedAddress]|None = None,
+    registry_addrs: list[tuple[str, int]]|None = None,
 
     # defaults are above
-    arbiter_addr: tuple[UnwrappedAddress]|None = None,
-
-    enable_transports: list[
-        # TODO, this should eventually be the pairs as
-        # defined by (codec, proto) as on `MsgTransport.
-        _state.TransportProtocolKey,
-    ]|None = None,
+    arbiter_addr: tuple[str, int]|None = None,
 
     name: str|None = 'root',
 
@@ -167,8 +80,6 @@ async def open_root_actor(
     # enables the multi-process debugger support
     debug_mode: bool = False,
     maybe_enable_greenback: bool = False,  # `.pause_from_sync()/breakpoint()` support
-    # ^XXX NOTE^ the perf implications of use,
-    # https://greenback.readthedocs.io/en/latest/principle.html#performance
     enable_stack_on_sig: bool = False,
 
     # internal logging
@@ -181,364 +92,316 @@ async def open_root_actor(
     # and that this call creates it.
     ensure_registry: bool = False,
 
-    hide_tb: bool = True,
-
-    # XXX, proxied directly to `.devx.debug._maybe_enter_pm()`
-    # for REPL-entry logic.
-    debug_filter: Callable[
-        [BaseException|BaseExceptionGroup],
-        bool,
-    ] = lambda err: not is_multi_cancelled(err),
-
-    # TODO, a way for actors to augment passing derived
-    # read-only state to sublayers?
-    # extra_rt_vars: dict|None = None,
-
 ) -> Actor:
     '''
     Runtime init entry point for ``tractor``.
 
     '''
-    # XXX NEVER allow nested actor-trees!
-    if already_actor := _state.current_actor(err_on_no_runtime=False):
-        rtvs: dict[str, Any] = _state._runtime_vars
-        root_mailbox: list[str, int] = rtvs['_root_mailbox']
-        registry_addrs: list[list[str, int]] = rtvs['_registry_addrs']
-        raise RuntimeFailure(
-            f'A current actor already exists !?\n'
-            f'({already_actor}\n'
-            f'\n'
-            f'You can NOT open a second root actor from within '
-            f'an existing tree and the current root of this '
-            f'already exists !!\n'
-            f'\n'
-            f'_root_mailbox: {root_mailbox!r}\n'
-            f'_registry_addrs: {registry_addrs!r}\n'
+    # TODO: stick this in a `@cm` defined in `devx._debug`?
+    #
+    # Override the global debugger hook to make it play nice with
+    # ``trio``, see much discussion in:
+    # https://github.com/python-trio/trio/issues/1155#issuecomment-742964018
+    builtin_bp_handler: Callable = sys.breakpointhook
+    orig_bp_path: str|None = os.environ.get(
+        'PYTHONBREAKPOINT',
+        None,
+    )
+    if (
+        debug_mode
+        and maybe_enable_greenback
+        and await _debug.maybe_init_greenback(
+            raise_not_found=False,
         )
-
-    async with maybe_block_bp(
-        debug_mode=debug_mode,
-        maybe_enable_greenback=maybe_enable_greenback,
     ):
-        if enable_transports is None:
-            enable_transports: list[str] = _state.current_ipc_protos()
-        else:
-            _state._runtime_vars['_enable_tpts'] = enable_transports
-
-        # TODO! support multi-tpts per actor!
-        # Bo
-        if not len(enable_transports) == 1:
+        os.environ['PYTHONBREAKPOINT'] = (
+            'tractor.devx._debug.pause_from_sync'
+        )
+    else:
+        # TODO: disable `breakpoint()` by default (without
+        # `greenback`) since it will break any multi-actor
+        # usage by a clobbered TTY's stdstreams!
+        def block_bps(*args, **kwargs):
             raise RuntimeError(
-                f'No multi-tpt support yet!\n'
-                f'enable_transports={enable_transports!r}\n'
+                'Trying to use `breakpoint()` eh?\n'
+                'Welp, `tractor` blocks `breakpoint()` built-in calls by default!\n'
+                'If you need to use it please install `greenback` and set '
+                '`debug_mode=True` when opening the runtime '
+                '(either via `.open_nursery()` or `open_root_actor()`)\n'
             )
 
-        _frame_stack.hide_runtime_frames()
-        __tracebackhide__: bool = hide_tb
+        sys.breakpointhook = block_bps
+        # os.environ['PYTHONBREAKPOINT'] = None
 
-        # attempt to retreive ``trio``'s sigint handler and stash it
-        # on our debugger lock state.
-        debug.DebugStatus._trio_handler = signal.getsignal(signal.SIGINT)
+    # attempt to retreive ``trio``'s sigint handler and stash it
+    # on our debugger lock state.
+    _debug.Lock._trio_handler = signal.getsignal(signal.SIGINT)
 
-        # mark top most level process as root actor
-        _state._runtime_vars['_is_root'] = True
+    # mark top most level process as root actor
+    _state._runtime_vars['_is_root'] = True
 
-        # caps based rpc list
-        enable_modules = (
-            enable_modules
-            or
-            []
+    # caps based rpc list
+    enable_modules = (
+        enable_modules
+        or
+        []
+    )
+
+    if rpc_module_paths:
+        warnings.warn(
+            "`rpc_module_paths` is now deprecated, use "
+            " `enable_modules` instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        enable_modules.extend(rpc_module_paths)
+
+    if start_method is not None:
+        _spawn.try_set_start_method(start_method)
+
+    if arbiter_addr is not None:
+        warnings.warn(
+            '`arbiter_addr` is now deprecated\n'
+            'Use `registry_addrs: list[tuple]` instead..',
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        registry_addrs = [arbiter_addr]
+
+    registry_addrs: list[tuple[str, int]] = (
+        registry_addrs
+        or
+        _default_lo_addrs
+    )
+    assert registry_addrs
+
+    loglevel = (
+        loglevel
+        or log._default_loglevel
+    ).upper()
+
+    if (
+        debug_mode
+        and _spawn._spawn_method == 'trio'
+    ):
+        _state._runtime_vars['_debug_mode'] = True
+
+        # expose internal debug module to every actor allowing for
+        # use of ``await tractor.pause()``
+        enable_modules.append('tractor.devx._debug')
+
+        # if debug mode get's enabled *at least* use that level of
+        # logging for some informative console prompts.
+        if (
+            logging.getLevelName(
+                # lul, need the upper case for the -> int map?
+                # sweet "dynamic function behaviour" stdlib...
+                loglevel,
+            ) > logging.getLevelName('PDB')
+        ):
+            loglevel = 'PDB'
+
+    elif debug_mode:
+        raise RuntimeError(
+            "Debug mode is only supported for the `trio` backend!"
         )
 
-        if rpc_module_paths:
-            warnings.warn(
-                "`rpc_module_paths` is now deprecated, use "
-                " `enable_modules` instead.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-            enable_modules.extend(rpc_module_paths)
+    assert loglevel
+    _log = log.get_console_log(loglevel)
+    assert _log
 
-        if start_method is not None:
-            _spawn.try_set_start_method(start_method)
-
-        # TODO! remove this ASAP!
-        if arbiter_addr is not None:
-            warnings.warn(
-                '`arbiter_addr` is now deprecated\n'
-                'Use `registry_addrs: list[tuple]` instead..',
-                DeprecationWarning,
-                stacklevel=2,
-            )
-            registry_addrs = [arbiter_addr]
-
-        if not registry_addrs:
-            registry_addrs: list[UnwrappedAddress] = default_lo_addrs(
-                enable_transports
-            )
-
-        assert registry_addrs
-
-        loglevel = (
-            loglevel
-            or log._default_loglevel
-        ).upper()
-
-        if (
-            debug_mode
-            and
-            _spawn._spawn_method == 'trio'
-        ):
-            _state._runtime_vars['_debug_mode'] = True
-
-            # expose internal debug module to every actor allowing for
-            # use of ``await tractor.pause()``
-            enable_modules.append('tractor.devx.debug._tty_lock')
-
-            # if debug mode get's enabled *at least* use that level of
-            # logging for some informative console prompts.
-            if (
-                logging.getLevelName(
-                    # lul, need the upper case for the -> int map?
-                    # sweet "dynamic function behaviour" stdlib...
-                    loglevel,
-                ) > logging.getLevelName('PDB')
-            ):
-                loglevel = 'PDB'
-
-
-        elif debug_mode:
-            raise RuntimeError(
-                "Debug mode is only supported for the `trio` backend!"
-            )
-
-        assert loglevel
-        _log = log.get_console_log(loglevel)
-        assert _log
-
-        # TODO: factor this into `.devx._stackscope`!!
-        if (
-            debug_mode
-            and
-            enable_stack_on_sig
-        ):
-            from .devx._stackscope import enable_stack_on_sig
-            enable_stack_on_sig()
-
-        # closed into below ping task-func
-        ponged_addrs: list[UnwrappedAddress] = []
-
-        async def ping_tpt_socket(
-            addr: UnwrappedAddress,
-            timeout: float = 1,
-        ) -> None:
-            '''
-            Attempt temporary connection to see if a registry is
-            listening at the requested address by a tranport layer
-            ping.
-
-            If a connection can't be made quickly we assume none no
-            server is listening at that addr.
-
-            '''
-            try:
-                # TODO: this connect-and-bail forces us to have to
-                # carefully rewrap TCP 104-connection-reset errors as
-                # EOF so as to avoid propagating cancel-causing errors
-                # to the channel-msg loop machinery. Likely it would
-                # be better to eventually have a "discovery" protocol
-                # with basic handshake instead?
-                with trio.move_on_after(timeout):
-                    async with _connect_chan(addr):
-                        ponged_addrs.append(addr)
-
-            except OSError:
-                # TODO: make this a "discovery" log level?
-                logger.info(
-                    f'No actor registry found @ {addr}\n'
-                )
-
-        async with trio.open_nursery() as tn:
-            for addr in registry_addrs:
-                tn.start_soon(
-                    ping_tpt_socket,
-                    addr,
-                )
-
-        trans_bind_addrs: list[UnwrappedAddress] = []
-
-        # Create a new local root-actor instance which IS NOT THE
-        # REGISTRAR
-        if ponged_addrs:
-            if ensure_registry:
-                raise RuntimeError(
-                     f'Failed to open `{name}`@{ponged_addrs}: '
-                    'registry socket(s) already bound'
-                )
-
-            # we were able to connect to an arbiter
-            logger.info(
-                f'Registry(s) seem(s) to exist @ {ponged_addrs}'
-            )
-
-            actor = Actor(
-                name=name or 'anonymous',
-                uuid=mk_uuid(),
-                registry_addrs=ponged_addrs,
-                loglevel=loglevel,
-                enable_modules=enable_modules,
-            )
-            # DO NOT use the registry_addrs as the transport server
-            # addrs for this new non-registar, root-actor.
-            for addr in ponged_addrs:
-                waddr: Address = wrap_address(addr)
-                trans_bind_addrs.append(
-                    waddr.get_random(bindspace=waddr.bindspace)
-                )
-
-        # Start this local actor as the "registrar", aka a regular
-        # actor who manages the local registry of "mailboxes" of
-        # other process-tree-local sub-actors.
-        else:
-
-            # NOTE that if the current actor IS THE REGISTAR, the
-            # following init steps are taken:
-            # - the tranport layer server is bound to each addr
-            #   pair defined in provided registry_addrs, or the default.
-            trans_bind_addrs = registry_addrs
-
-            # - it is normally desirable for any registrar to stay up
-            #   indefinitely until either all registered (child/sub)
-            #   actors are terminated (via SC supervision) or,
-            #   a re-election process has taken place.
-            # NOTE: all of ^ which is not implemented yet - see:
-            # https://github.com/goodboy/tractor/issues/216
-            # https://github.com/goodboy/tractor/pull/348
-            # https://github.com/goodboy/tractor/issues/296
-
-            actor = Arbiter(
-                name=name or 'registrar',
-                uuid=mk_uuid(),
-                registry_addrs=registry_addrs,
-                loglevel=loglevel,
-                enable_modules=enable_modules,
-            )
-            # XXX, in case the root actor runtime was actually run from
-            # `tractor.to_asyncio.run_as_asyncio_guest()` and NOt
-            # `.trio.run()`.
-            actor._infected_aio = _state._runtime_vars['_is_infected_aio']
-
-        # Start up main task set via core actor-runtime nurseries.
+    # TODO: factor this into `.devx._stackscope`!!
+    if (
+        debug_mode
+        and
+        enable_stack_on_sig
+    ):
         try:
-            # assign process-local actor
-            _state._current_actor = actor
-
-            # start local channel-server and fake the portal API
-            # NOTE: this won't block since we provide the nursery
-            ml_addrs_str: str = '\n'.join(
-                f'@{addr}' for addr in trans_bind_addrs
-            )
-            logger.info(
-                f'Starting local {actor.uid} on the following transport addrs:\n'
-                f'{ml_addrs_str}'
+            logger.info('Enabling `stackscope` traces on SIGUSR1')
+            from .devx import enable_stack_on_sig
+            enable_stack_on_sig()
+        except ImportError:
+            logger.warning(
+                '`stackscope` not installed for use in debug mode!'
             )
 
-            # start the actor runtime in a new task
-            async with trio.open_nursery(
-                strict_exception_groups=False,
-                # ^XXX^ TODO? instead unpack any RAE as per "loose" style?
-            ) as nursery:
+    # closed into below ping task-func
+    ponged_addrs: list[tuple[str, int]] = []
 
-                # ``_runtime.async_main()`` creates an internal nursery
-                # and blocks here until any underlying actor(-process)
-                # tree has terminated thereby conducting so called
-                # "end-to-end" structured concurrency throughout an
-                # entire hierarchical python sub-process set; all
-                # "actor runtime" primitives are SC-compat and thus all
-                # transitively spawned actors/processes must be as
-                # well.
-                await nursery.start(
-                    partial(
-                        async_main,
-                        actor,
-                        accept_addrs=trans_bind_addrs,
-                        parent_addr=None
-                    )
+    async def ping_tpt_socket(
+        addr: tuple[str, int],
+        timeout: float = 1,
+    ) -> None:
+        '''
+        Attempt temporary connection to see if a registry is
+        listening at the requested address by a tranport layer
+        ping.
+
+        If a connection can't be made quickly we assume none no
+        server is listening at that addr.
+
+        '''
+        try:
+            # TODO: this connect-and-bail forces us to have to
+            # carefully rewrap TCP 104-connection-reset errors as
+            # EOF so as to avoid propagating cancel-causing errors
+            # to the channel-msg loop machinery. Likely it would
+            # be better to eventually have a "discovery" protocol
+            # with basic handshake instead?
+            with trio.move_on_after(timeout):
+                async with _connect_chan(*addr):
+                    ponged_addrs.append(addr)
+
+        except OSError:
+            # TODO: make this a "discovery" log level?
+            logger.warning(f'No actor registry found @ {addr}')
+
+    async with trio.open_nursery() as tn:
+        for addr in registry_addrs:
+            tn.start_soon(
+                ping_tpt_socket,
+                tuple(addr),  # TODO: just drop this requirement?
+            )
+
+    trans_bind_addrs: list[tuple[str, int]] = []
+
+    # Create a new local root-actor instance which IS NOT THE
+    # REGISTRAR
+    if ponged_addrs:
+
+        if ensure_registry:
+            raise RuntimeError(
+                 f'Failed to open `{name}`@{ponged_addrs}: '
+                'registry socket(s) already bound'
+            )
+
+        # we were able to connect to an arbiter
+        logger.info(
+            f'Registry(s) seem(s) to exist @ {ponged_addrs}'
+        )
+
+        actor = Actor(
+            name=name or 'anonymous',
+            registry_addrs=ponged_addrs,
+            loglevel=loglevel,
+            enable_modules=enable_modules,
+        )
+        # DO NOT use the registry_addrs as the transport server
+        # addrs for this new non-registar, root-actor.
+        for host, port in ponged_addrs:
+            # NOTE: zero triggers dynamic OS port allocation
+            trans_bind_addrs.append((host, 0))
+
+    # Start this local actor as the "registrar", aka a regular
+    # actor who manages the local registry of "mailboxes" of
+    # other process-tree-local sub-actors.
+    else:
+
+        # NOTE that if the current actor IS THE REGISTAR, the
+        # following init steps are taken:
+        # - the tranport layer server is bound to each (host, port)
+        #   pair defined in provided registry_addrs, or the default.
+        trans_bind_addrs = registry_addrs
+
+        # - it is normally desirable for any registrar to stay up
+        #   indefinitely until either all registered (child/sub)
+        #   actors are terminated (via SC supervision) or,
+        #   a re-election process has taken place. 
+        # NOTE: all of ^ which is not implemented yet - see:
+        # https://github.com/goodboy/tractor/issues/216
+        # https://github.com/goodboy/tractor/pull/348
+        # https://github.com/goodboy/tractor/issues/296
+
+        actor = Arbiter(
+            name or 'registrar',
+            registry_addrs=registry_addrs,
+            loglevel=loglevel,
+            enable_modules=enable_modules,
+        )
+
+    # Start up main task set via core actor-runtime nurseries.
+    try:
+        # assign process-local actor
+        _state._current_actor = actor
+
+        # start local channel-server and fake the portal API
+        # NOTE: this won't block since we provide the nursery
+        ml_addrs_str: str = '\n'.join(
+            f'@{addr}' for addr in trans_bind_addrs
+        )
+        logger.info(
+            f'Starting local {actor.uid} on the following transport addrs:\n'
+            f'{ml_addrs_str}'
+        )
+
+        # start the actor runtime in a new task
+        async with trio.open_nursery() as nursery:
+
+            # ``_runtime.async_main()`` creates an internal nursery
+            # and blocks here until any underlying actor(-process)
+            # tree has terminated thereby conducting so called
+            # "end-to-end" structured concurrency throughout an
+            # entire hierarchical python sub-process set; all
+            # "actor runtime" primitives are SC-compat and thus all
+            # transitively spawned actors/processes must be as
+            # well.
+            await nursery.start(
+                partial(
+                    async_main,
+                    actor,
+                    accept_addrs=trans_bind_addrs,
+                    parent_addr=None
                 )
-                try:
-                    yield actor
-                except (
-                    Exception,
-                    BaseExceptionGroup,
-                ) as err:
-
-                    # TODO, in beginning to handle the subsubactor with
-                    # crashed grandparent cases..
-                    #
-                    # was_locked: bool = await debug.maybe_wait_for_debugger(
-                    #     child_in_debug=True,
-                    # )
-                    # XXX NOTE XXX see equiv note inside
-                    # `._runtime.Actor._stream_handler()` where in the
-                    # non-root or root-that-opened-this-mahually case we
-                    # wait for the local actor-nursery to exit before
-                    # exiting the transport channel handler.
-                    entered: bool = await debug._maybe_enter_pm(
-                        err,
-                        api_frame=inspect.currentframe(),
-                        debug_filter=debug_filter,
-                    )
-
-                    if (
-                        not entered
-                        and
-                        not is_multi_cancelled(
-                            err,
-                        )
-                    ):
-                        logger.exception(
-                            'Root actor crashed\n'
-                            f'>x)\n'
-                            f' |_{actor}\n'
-                        )
-
-                    # ALWAYS re-raise any error bubbled up from the
-                    # runtime!
-                    raise
-
-                finally:
-                    # NOTE: not sure if we'll ever need this but it's
-                    # possibly better for even more determinism?
-                    # logger.cancel(
-                    #     f'Waiting on {len(nurseries)} nurseries in root..')
-                    # nurseries = actor._actoruid2nursery.values()
-                    # async with trio.open_nursery() as tempn:
-                    #     for an in nurseries:
-                    #         tempn.start_soon(an.exited.wait)
-
-                    logger.info(
-                        f'Closing down root actor\n'
-                        f'>)\n'
-                        f'|_{actor}\n'
-                    )
-                    await actor.cancel(None)  # self cancel
-        finally:
-            # revert all process-global runtime state
-            if (
-                debug_mode
-                and
-                _spawn._spawn_method == 'trio'
-            ):
-                _state._runtime_vars['_debug_mode'] = False
-
-            _state._current_actor = None
-            _state._last_actor_terminated = actor
-
-            logger.runtime(
-                f'Root actor terminated\n'
-                f')>\n'
-                f' |_{actor}\n'
             )
+            try:
+                yield actor
+
+            except (
+                Exception,
+                BaseExceptionGroup,
+            ) as err:
+
+                entered: bool = await _debug._maybe_enter_pm(err)
+                if (
+                    not entered
+                    and
+                    not is_multi_cancelled(err)
+                ):
+                    logger.exception('Root actor crashed:\n')
+
+                # ALWAYS re-raise any error bubbled up from the
+                # runtime!
+                raise
+
+            finally:
+                # NOTE: not sure if we'll ever need this but it's
+                # possibly better for even more determinism?
+                # logger.cancel(
+                #     f'Waiting on {len(nurseries)} nurseries in root..')
+                # nurseries = actor._actoruid2nursery.values()
+                # async with trio.open_nursery() as tempn:
+                #     for an in nurseries:
+                #         tempn.start_soon(an.exited.wait)
+
+                logger.info(
+                    'Closing down root actor'
+                )
+                await actor.cancel(None)  # self cancel
+    finally:
+        _state._current_actor = None
+        _state._last_actor_terminated = actor
+
+        # restore built-in `breakpoint()` hook state
+        if debug_mode:
+            if builtin_bp_handler is not None:
+                sys.breakpointhook = builtin_bp_handler
+            if orig_bp_path is not None:
+                os.environ['PYTHONBREAKPOINT'] = orig_bp_path
+            else:
+                # clear env back to having no entry
+                os.environ.pop('PYTHONBREAKPOINT')
+
+        logger.runtime("Root actor terminated")
 
 
 def run_daemon(
@@ -546,23 +409,16 @@ def run_daemon(
 
     # runtime kwargs
     name: str | None = 'root',
-    registry_addrs: list[UnwrappedAddress]|None = None,
+    registry_addrs: list[tuple[str, int]] = _default_lo_addrs,
 
     start_method: str | None = None,
     debug_mode: bool = False,
-
-    # TODO, support `infected_aio=True` mode by,
-    # - calling the appropriate entrypoint-func from `.to_asyncio`
-    # - maybe init-ing `greenback` as done above in
-    #   `open_root_actor()`.
-
     **kwargs
 
 ) -> None:
     '''
-    Spawn a root (daemon) actor which will respond to RPC; the main
-    task simply starts the runtime and then blocks via embedded
-    `trio.sleep_forever()`.
+    Spawn daemon actor which will respond to RPC; the main task simply
+    starts the runtime and then sleeps forever.
 
     This is a very minimal convenience wrapper around starting
     a "run-until-cancelled" root actor which can be started with a set
@@ -575,6 +431,7 @@ def run_daemon(
         importlib.import_module(path)
 
     async def _main():
+
         async with open_root_actor(
             registry_addrs=registry_addrs,
             name=name,

tractor/_spawn.py

@@ -34,7 +34,7 @@ from typing import (
 import trio
 from trio import TaskStatus
 
-from .devx.debug import (
+from .devx._debug import (
     maybe_wait_for_debugger,
     acquire_debug_lock,
 )
@@ -43,26 +43,18 @@ from tractor._state import (
     is_main_process,
     is_root_process,
     debug_mode,
-    _runtime_vars,
 )
 from tractor.log import get_logger
-from tractor._addr import UnwrappedAddress
 from tractor._portal import Portal
 from tractor._runtime import Actor
 from tractor._entry import _mp_main
 from tractor._exceptions import ActorFailure
-from tractor.msg.types import (
-    Aid,
-    SpawnSpec,
-)
 
 
 if TYPE_CHECKING:
-    from ipc import IPCServer
     from ._supervise import ActorNursery
     ProcessType = TypeVar('ProcessType', mp.Process, trio.Process)
 
-
 log = get_logger('tractor')
 
 # placeholder for an mp start context if so using that backend
@@ -147,13 +139,11 @@ async def exhaust_portal(
     '''
     __tracebackhide__ = True
     try:
-        log.debug(
-            f'Waiting on final result from {actor.uid}'
-        )
+        log.debug(f"Waiting on final result from {actor.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()
+        final: Any = await portal.result()
 
     except (
         Exception,
@@ -167,7 +157,7 @@ async def exhaust_portal(
         # TODO: merge with above?
         log.warning(
             'Cancelled portal result waiter task:\n'
-            f'uid: {portal.channel.aid}\n'
+            f'uid: {portal.channel.uid}\n'
             f'error: {err}\n'
         )
         return err
@@ -175,7 +165,7 @@ async def exhaust_portal(
     else:
         log.debug(
             f'Returning final result from portal:\n'
-            f'uid: {portal.channel.aid}\n'
+            f'uid: {portal.channel.uid}\n'
             f'result: {final}\n'
         )
         return final
@@ -202,10 +192,7 @@ async def cancel_on_completion(
     # 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,
-    )
+    result: Any|Exception = await exhaust_portal(portal, actor)
     if isinstance(result, Exception):
         errors[actor.uid]: Exception = result
         log.cancel(
@@ -227,8 +214,8 @@ async def cancel_on_completion(
 
 async def hard_kill(
     proc: trio.Process,
-
     terminate_after: int = 1.6,
+
     # NOTE: for mucking with `.pause()`-ing inside the runtime
     # whilst also hacking on it XD
     # terminate_after: int = 99999,
@@ -254,9 +241,8 @@ async def hard_kill(
 
     '''
     log.cancel(
-        'Terminating sub-proc\n'
-        f'>x)\n'
-        f' |_{proc}\n'
+        'Terminating sub-proc:\n'
+        f'|_{proc}\n'
     )
     # NOTE: this timeout used to do nothing since we were shielding
     # the ``.wait()`` inside ``new_proc()`` which will pretty much
@@ -302,13 +288,14 @@ async def hard_kill(
         log.critical(
             # 'Well, the #ZOMBIE_LORD_IS_HERE# to collect\n'
             '#T-800 deployed to collect zombie B0\n'
-            f'>x)\n'
-            f' |_{proc}\n'
+            f'|\n'
+            f'|_{proc}\n'
         )
         proc.kill()
 
 
 async def soft_kill(
+
     proc: ProcessType,
     wait_func: Callable[
         [ProcessType],
@@ -328,30 +315,16 @@ async def soft_kill(
     see `.hard_kill()`).
 
     '''
-    peer_aid: Aid = portal.channel.aid
+    uid: tuple[str, str] = portal.channel.uid
     try:
         log.cancel(
-            f'Soft killing sub-actor via portal request\n'
-            f'\n'
-            f'(c=> {peer_aid}\n'
-            f'  |_{proc}\n'
+            'Soft killing sub-actor via `Portal.cancel_actor()`\n'
+            f'|_{proc}\n'
         )
         # wait on sub-proc to signal termination
         await wait_func(proc)
 
     except trio.Cancelled:
-        with trio.CancelScope(shield=True):
-            await maybe_wait_for_debugger(
-                child_in_debug=_runtime_vars.get(
-                    '_debug_mode', False
-                ),
-                header_msg=(
-                    'Delaying `soft_kill()` subproc reaper while debugger locked..\n'
-                ),
-                # TODO: need a diff value then default?
-                # poll_steps=9999999,
-            )
-
         # if cancelled during a soft wait, cancel the child
         # actor before entering the hard reap sequence
         # below. This means we try to do a graceful teardown
@@ -382,7 +355,7 @@ async def soft_kill(
             if proc.poll() is None:  # type: ignore
                 log.warning(
                     'Subactor still alive after cancel request?\n\n'
-                    f'uid: {peer_aid}\n'
+                    f'uid: {uid}\n'
                     f'|_{proc}\n'
                 )
                 n.cancel_scope.cancel()
@@ -396,15 +369,14 @@ async def new_proc(
     errors: dict[tuple[str, str], Exception],
 
     # passed through to actor main
-    bind_addrs: list[UnwrappedAddress],
-    parent_addr: UnwrappedAddress,
+    bind_addrs: list[tuple[str, int]],
+    parent_addr: tuple[str, int],
     _runtime_vars: dict[str, Any],  # serialized and sent to _child
 
     *,
 
     infect_asyncio: bool = False,
-    task_status: TaskStatus[Portal] = trio.TASK_STATUS_IGNORED,
-    proc_kwargs: dict[str, any] = {}
+    task_status: TaskStatus[Portal] = trio.TASK_STATUS_IGNORED
 
 ) -> None:
 
@@ -424,7 +396,6 @@ async def new_proc(
         _runtime_vars,  # run time vars
         infect_asyncio=infect_asyncio,
         task_status=task_status,
-        proc_kwargs=proc_kwargs
     )
 
 
@@ -435,13 +406,12 @@ async def trio_proc(
     errors: dict[tuple[str, str], Exception],
 
     # passed through to actor main
-    bind_addrs: list[UnwrappedAddress],
-    parent_addr: UnwrappedAddress,
+    bind_addrs: list[tuple[str, int]],
+    parent_addr: tuple[str, int],
     _runtime_vars: dict[str, Any],  # serialized and sent to _child
     *,
     infect_asyncio: bool = False,
-    task_status: TaskStatus[Portal] = trio.TASK_STATUS_IGNORED,
-    proc_kwargs: dict[str, any] = {}
+    task_status: TaskStatus[Portal] = trio.TASK_STATUS_IGNORED
 
 ) -> None:
     '''
@@ -463,9 +433,6 @@ async def trio_proc(
         # the OS; it otherwise can be passed via the parent channel if
         # we prefer in the future (for privacy).
         "--uid",
-        # TODO, how to pass this over "wire" encodings like
-        # cmdline args?
-        # -[ ] maybe we can add an `Aid.min_tuple()` ?
         str(subactor.uid),
         # Address the child must connect to on startup
         "--parent_addr",
@@ -483,19 +450,19 @@ async def trio_proc(
 
     cancelled_during_spawn: bool = False
     proc: trio.Process|None = None
-    ipc_server: IPCServer = actor_nursery._actor.ipc_server
     try:
         try:
-            proc: trio.Process = await trio.lowlevel.open_process(spawn_cmd, **proc_kwargs)
+            # TODO: needs ``trio_typing`` patch?
+            proc = await trio.lowlevel.open_process(spawn_cmd)
             log.runtime(
-                'Started new child\n'
+                'Started new sub-proc\n'
                 f'|_{proc}\n'
             )
 
             # wait for actor to spawn and connect back to us
             # channel should have handshake completed by the
             # local actor by the time we get a ref to it
-            event, chan = await ipc_server.wait_for_peer(
+            event, chan = await actor_nursery._actor.wait_for_peer(
                 subactor.uid
             )
 
@@ -526,17 +493,14 @@ async def trio_proc(
             portal,
         )
 
-        # send a "spawning specification" which configures the
-        # initial runtime state of the child.
-        sspec = SpawnSpec(
-            _parent_main_data=subactor._parent_main_data,
-            enable_modules=subactor.enable_modules,
-            reg_addrs=subactor.reg_addrs,
-            bind_addrs=bind_addrs,
-            _runtime_vars=_runtime_vars,
-        )
-        log.runtime(f'Sending spawn spec: {str(sspec)}')
-        await chan.send(sspec)
+        # send additional init params
+        await chan.send({
+            '_parent_main_data': subactor._parent_main_data,
+            'enable_modules': subactor.enable_modules,
+            'reg_addrs': subactor.reg_addrs,
+            'bind_addrs': bind_addrs,
+            '_runtime_vars': _runtime_vars,
+        })
 
         # track subactor in current nursery
         curr_actor: Actor = current_actor()
@@ -570,9 +534,8 @@ async def trio_proc(
             # cancel result waiter that may have been spawned in
             # tandem if not done already
             log.cancel(
-                'Cancelling portal result reaper task\n'
-                f'>c)\n'
-                f' |_{subactor.uid}\n'
+                'Cancelling existing result waiter task for '
+                f'{subactor.uid}'
             )
             nursery.cancel_scope.cancel()
 
@@ -581,13 +544,9 @@ async def trio_proc(
         # allowed! Do this **after** cancellation/teardown to avoid
         # killing the process too early.
         if proc:
-            log.cancel(
-                f'Hard reap sequence starting for subactor\n'
-                f'>x)\n'
-                f' |_{subactor}@{subactor.uid}\n'
-            )
-
+            log.cancel(f'Hard reap sequence starting for {subactor.uid}')
             with trio.CancelScope(shield=True):
+
                 # don't clobber an ongoing pdb
                 if cancelled_during_spawn:
                     # Try again to avoid TTY clobbering.
@@ -646,13 +605,12 @@ async def mp_proc(
     subactor: Actor,
     errors: dict[tuple[str, str], Exception],
     # passed through to actor main
-    bind_addrs: list[UnwrappedAddress],
-    parent_addr: UnwrappedAddress,
+    bind_addrs: list[tuple[str, int]],
+    parent_addr: tuple[str, int],
     _runtime_vars: dict[str, Any],  # serialized and sent to _child
     *,
     infect_asyncio: bool = False,
-    task_status: TaskStatus[Portal] = trio.TASK_STATUS_IGNORED,
-    proc_kwargs: dict[str, any] = {}
+    task_status: TaskStatus[Portal] = trio.TASK_STATUS_IGNORED
 
 ) -> None:
 
@@ -727,14 +685,12 @@ async def mp_proc(
 
     log.runtime(f"Started {proc}")
 
-    ipc_server: IPCServer = actor_nursery._actor.ipc_server
     try:
         # wait for actor to spawn and connect back to us
         # channel should have handshake completed by the
         # local actor by the time we get a ref to it
-        event, chan = await ipc_server.wait_for_peer(
-            subactor.uid,
-        )
+        event, chan = await actor_nursery._actor.wait_for_peer(
+            subactor.uid)
 
         # XXX: monkey patch poll API to match the ``subprocess`` API..
         # not sure why they don't expose this but kk.

tractor/_state.py

@@ -14,62 +14,32 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-'''
-Per actor-process runtime state mgmt APIs.
+"""
+Per process state
 
-'''
+"""
 from __future__ import annotations
-from contextvars import (
-    ContextVar,
-)
-import os
-from pathlib import Path
 from typing import (
     Any,
-    Literal,
     TYPE_CHECKING,
 )
 
-from trio.lowlevel import current_task
-
 if TYPE_CHECKING:
     from ._runtime import Actor
-    from ._context import Context
 
 
-# default IPC transport protocol settings
-TransportProtocolKey = Literal[
-    'tcp',
-    'uds',
-]
-_def_tpt_proto: TransportProtocolKey = 'tcp'
-
 _current_actor: Actor|None = None  # type: ignore # noqa
 _last_actor_terminated: Actor|None = None
 
 # TODO: mk this a `msgspec.Struct`!
-# -[ ] type out all fields obvi!
-# -[ ] (eventually) mk wire-ready for monitoring?
 _runtime_vars: dict[str, Any] = {
-    # root of actor-process tree info
-    '_is_root': False,  # bool
-    '_root_mailbox': (None, None),  # tuple[str|None, str|None]
-    '_root_addrs': [],  # tuple[str|None, str|None]
-
-    # parent->chld ipc protocol caps
-    '_enable_tpts': [_def_tpt_proto],
-
-    # registrar info
+    '_debug_mode': False,
+    '_is_root': False,
+    '_root_mailbox': (None, None),
     '_registry_addrs': [],
 
-    # `debug_mode: bool` settings
-    '_debug_mode': False,  # bool
-    'repl_fixture': False,  # |AbstractContextManager[bool]
-    # for `tractor.pause_from_sync()` & `breakpoint()` support
+    # for `breakpoint()` support
     'use_greenback': False,
-
-    # infected-`asyncio`-mode: `trio` running as guest.
-    '_is_infected_aio': False,
 }
 
 
@@ -94,10 +64,9 @@ def current_actor(
     '''
     if (
         err_on_no_runtime
-        and
-        _current_actor is None
+        and _current_actor is None
     ):
-        msg: str = 'No local actor has been initialized yet?\n'
+        msg: str = 'No local actor has been initialized yet'
         from ._exceptions import NoRuntime
 
         if last := last_actor():
@@ -110,8 +79,8 @@ def current_actor(
         # this process.
         else:
             msg += (
-                # 'No last actor found?\n'
-                '\nDid you forget to call one of,\n'
+                'No last actor found?\n'
+                'Did you forget to open one of:\n\n'
                 '- `tractor.open_root_actor()`\n'
                 '- `tractor.open_nursery()`\n'
             )
@@ -121,7 +90,7 @@ def current_actor(
     return _current_actor
 
 
-def is_root_process() -> bool:
+def is_main_process() -> bool:
     '''
     Bool determining if this actor is running in the top-most process.
 
@@ -130,10 +99,7 @@ def is_root_process() -> bool:
     return mp.current_process().name == 'MainProcess'
 
 
-is_main_process = is_root_process
-
-
-def is_debug_mode() -> bool:
+def debug_mode() -> bool:
     '''
     Bool determining if "debug mode" is on which enables
     remote subactor pdb entry on crashes.
@@ -142,62 +108,5 @@ def is_debug_mode() -> bool:
     return bool(_runtime_vars['_debug_mode'])
 
 
-debug_mode = is_debug_mode
-
-
 def is_root_process() -> bool:
     return _runtime_vars['_is_root']
-
-
-_ctxvar_Context: ContextVar[Context] = ContextVar(
-    'ipc_context',
-    default=None,
-)
-
-
-def current_ipc_ctx(
-    error_on_not_set: bool = False,
-) -> Context|None:
-    ctx: Context = _ctxvar_Context.get()
-
-    if (
-        not ctx
-        and error_on_not_set
-    ):
-        from ._exceptions import InternalError
-        raise InternalError(
-            'No IPC context has been allocated for this task yet?\n'
-            f'|_{current_task()}\n'
-        )
-    return ctx
-
-
-# std ODE (mutable) app state location
-_rtdir: Path = Path(os.environ['XDG_RUNTIME_DIR'])
-
-
-def get_rt_dir(
-    subdir: str = 'tractor'
-) -> Path:
-    '''
-    Return the user "runtime dir" where most userspace apps stick
-    their IPC and cache related system util-files; we take hold
-    of a `'XDG_RUNTIME_DIR'/tractor/` subdir by default.
-
-    '''
-    rtdir: Path = _rtdir / subdir
-    if not rtdir.is_dir():
-        rtdir.mkdir()
-    return rtdir
-
-
-def current_ipc_protos() -> list[str]:
-    '''
-    Return the list of IPC transport protocol keys currently
-    in use by this actor.
-
-    The keys are as declared by `MsgTransport` and `Address`
-    concrete-backend sub-types defined throughout `tractor.ipc`.
-
-    '''
-    return _runtime_vars['_enable_tpts']

tractor/_streaming.py

@@ -26,7 +26,6 @@ import inspect
 from pprint import pformat
 from typing import (
     Any,
-    AsyncGenerator,
     Callable,
     AsyncIterator,
     TYPE_CHECKING,
@@ -36,27 +35,17 @@ import warnings
 import trio
 
 from ._exceptions import (
+    _raise_from_no_key_in_msg,
     ContextCancelled,
-    RemoteActorError,
 )
 from .log import get_logger
 from .trionics import (
     broadcast_receiver,
     BroadcastReceiver,
 )
-from tractor.msg import (
-    Error,
-    Return,
-    Stop,
-    MsgType,
-    PayloadT,
-    Yield,
-)
 
 if TYPE_CHECKING:
-    from ._runtime import Actor
     from ._context import Context
-    from .ipc import Channel
 
 
 log = get_logger(__name__)
@@ -70,9 +59,10 @@ log = get_logger(__name__)
 class MsgStream(trio.abc.Channel):
     '''
     A bidirectional message stream for receiving logically sequenced
-    values over an inter-actor IPC `Channel`.
-
+    values over an inter-actor IPC ``Channel``.
 
+    This is the type returned to a local task which entered either
+    ``Portal.open_stream_from()`` or ``Context.open_stream()``.
 
     Termination rules:
 
@@ -88,109 +78,46 @@ class MsgStream(trio.abc.Channel):
         self,
         ctx: Context,  # typing: ignore # noqa
         rx_chan: trio.MemoryReceiveChannel,
-        _broadcaster: BroadcastReceiver|None = None,
+        _broadcaster: BroadcastReceiver | None = None,
 
     ) -> None:
         self._ctx = ctx
         self._rx_chan = rx_chan
         self._broadcaster = _broadcaster
 
-        # any actual IPC msg which is effectively an `EndOfStream`
-        self._stop_msg: bool|Stop = False
-
         # flag to denote end of stream
         self._eoc: bool|trio.EndOfChannel = False
         self._closed: bool|trio.ClosedResourceError = False
 
-    @property
-    def ctx(self) -> Context:
-        '''
-        A read-only ref to this stream's inter-actor-task `Context`.
-
-        '''
-        return self._ctx
-
-    @property
-    def chan(self) -> Channel:
-        '''
-        Ref to the containing `Context`'s transport `Channel`.
-
-        '''
-        return self._ctx.chan
-
-    # TODO: could we make this a direct method bind to `PldRx`?
-    # -> receive_nowait = PldRx.recv_pld
-    # |_ means latter would have to accept `MsgStream`-as-`self`?
-    #  => should be fine as long as,
-    #  -[ ] both define `._rx_chan`
-    #  -[ ] .ctx is bound into `PldRx` using a `@cm`?
-    #
     # delegate directly to underlying mem channel
     def receive_nowait(
         self,
-        expect_msg: MsgType = Yield,
-    ) -> PayloadT:
-        ctx: Context = self._ctx
-        (
-            msg,
-            pld,
-        ) = ctx._pld_rx.recv_msg_nowait(
-            ipc=self,
-            expect_msg=expect_msg,
-        )
+        allow_msg_keys: list[str] = ['yield'],
+    ):
+        msg: dict = self._rx_chan.receive_nowait()
+        for (
+            i,
+            key,
+        ) in enumerate(allow_msg_keys):
+            try:
+                return msg[key]
+            except KeyError as kerr:
+                if i < (len(allow_msg_keys) - 1):
+                    continue
 
-        # ?TODO, maybe factor this into a hyper-common `unwrap_pld()`
-        #
-        match msg:
-
-            # XXX, these never seems to ever hit? cool?
-            case Stop():
-                log.cancel(
-                    f'Msg-stream was ended via stop msg\n'
-                    f'{msg}'
+                _raise_from_no_key_in_msg(
+                    ctx=self._ctx,
+                    msg=msg,
+                    src_err=kerr,
+                    log=log,
+                    expect_key=key,
+                    stream=self,
                 )
-            case Error():
-                log.error(
-                    f'Msg-stream was ended via error msg\n'
-                    f'{msg}'
-                )
-
-            # XXX NOTE, always set any final result on the ctx to
-            # avoid teardown race conditions where previously this msg
-            # would be consumed silently (by `.aclose()` doing its
-            # own "msg drain loop" but WITHOUT those `drained: lists[MsgType]`
-            # being post-close-processed!
-            #
-            # !!TODO, see the equiv todo-comment in `.receive()`
-            # around the `if drained:` where we should prolly
-            # ACTUALLY be doing this post-close processing??
-            #
-            case Return(pld=pld):
-                log.warning(
-                    f'Msg-stream final result msg for IPC ctx?\n'
-                    f'{msg}'
-                )
-                # XXX TODO, this **should be covered** by higher
-                # scoped runtime-side method calls such as
-                # `Context._deliver_msg()`, so you should never
-                # really see the warning above or else something
-                # racy/out-of-order is likely going on between
-                # actor-runtime-side push tasks and the user-app-side
-                # consume tasks!
-                # -[ ] figure out that set of race cases and fix!
-                # -[ ] possibly return the `msg` given an input
-                #     arg-flag is set so we can process the `Return`
-                #     from the `.aclose()` caller?
-                #
-                # breakpoint()  # to debug this RACE CASE!
-                ctx._result = pld
-                ctx._outcome_msg = msg
-
-        return pld
 
     async def receive(
         self,
-        hide_tb: bool = False,
+
+        hide_tb: bool = True,
     ):
         '''
         Receive a single msg from the IPC transport, the next in
@@ -200,8 +127,9 @@ class MsgStream(trio.abc.Channel):
         '''
         __tracebackhide__: bool = hide_tb
 
-        # NOTE FYI: `trio.ReceiveChannel` implements EOC handling as
-        # follows (aka uses it to gracefully exit async for loops):
+        # NOTE: `trio.ReceiveChannel` implements
+        # EOC handling as follows (aka uses it
+        # to gracefully exit async for loops):
         #
         # async def __anext__(self) -> ReceiveType:
         #     try:
@@ -209,7 +137,7 @@ class MsgStream(trio.abc.Channel):
         #     except trio.EndOfChannel:
         #         raise StopAsyncIteration
         #
-        # see `.aclose()` for notes on the old behaviour prior to
+        # see ``.aclose()`` for notes on the old behaviour prior to
         # introducing this
         if self._eoc:
             raise self._eoc
@@ -219,33 +147,62 @@ class MsgStream(trio.abc.Channel):
 
         src_err: Exception|None = None  # orig tb
         try:
-            ctx: Context = self._ctx
-            pld = await ctx._pld_rx.recv_pld(
-                ipc=self,
-                expect_msg=Yield,
-            )
-            return pld
+            try:
+                msg = await self._rx_chan.receive()
+                return msg['yield']
+
+            except KeyError as kerr:
+                src_err = kerr
+
+                # NOTE: may raise any of the below error types
+                # includg EoC when a 'stop' msg is found.
+                _raise_from_no_key_in_msg(
+                    ctx=self._ctx,
+                    msg=msg,
+                    src_err=kerr,
+                    log=log,
+                    expect_key='yield',
+                    stream=self,
+                )
 
         # XXX: the stream terminates on either of:
-        # - `self._rx_chan.receive()` raising  after manual closure
-        #   by the rpc-runtime,
-        #   OR
-        # - via a `Stop`-msg received from remote peer task.
-        #   NOTE
-        #   |_ previously this was triggered by calling
-        #   `._rx_chan.aclose()` on the send side of the channel
-        #   inside `Actor._deliver_ctx_payload()`, but now the 'stop'
-        #   message handling gets delegated to `PldRFx.recv_pld()`
-        #   internals.
-        except trio.EndOfChannel as eoc:
-            # a graceful stream finished signal
-            self._eoc = eoc
+        # - via `self._rx_chan.receive()` raising  after manual closure
+        #   by the rpc-runtime OR,
+        # - via a received `{'stop': ...}` msg from remote side.
+        #   |_ NOTE: previously this was triggered by calling
+        #   ``._rx_chan.aclose()`` on the send side of the channel inside
+        #   `Actor._push_result()`, but now the 'stop' message handling
+        #   has been put just above inside `_raise_from_no_key_in_msg()`.
+        except (
+            trio.EndOfChannel,
+        ) as eoc:
             src_err = eoc
+            self._eoc = eoc
 
-        # a `ClosedResourceError` indicates that the internal feeder
-        # memory receive channel was closed likely by the runtime
-        # after the associated transport-channel disconnected or
-        # broke.
+            # TODO: Locally, we want to close this stream gracefully, by
+            # terminating any local consumers tasks deterministically.
+            # Once we have broadcast support, we **don't** want to be
+            # closing this stream and not flushing a final value to
+            # remaining (clone) consumers who may not have been
+            # scheduled to receive it yet.
+            # try:
+            #     maybe_err_msg_or_res: dict = self._rx_chan.receive_nowait()
+            #     if maybe_err_msg_or_res:
+            #         log.warning(
+            #             'Discarding un-processed msg:\n'
+            #             f'{maybe_err_msg_or_res}'
+            #         )
+            # except trio.WouldBlock:
+            #     # no queued msgs that might be another remote
+            #     # error, so just raise the original EoC
+            #     pass
+
+            # raise eoc
+
+        # a ``ClosedResourceError`` indicates that the internal
+        # feeder memory receive channel was closed likely by the
+        # runtime after the associated transport-channel
+        # disconnected or broke.
         except trio.ClosedResourceError as cre:  # by self._rx_chan.receive()
             src_err = cre
             log.warning(
@@ -257,60 +214,47 @@ class MsgStream(trio.abc.Channel):
         # terminated and signal this local iterator to stop
         drained: list[Exception|dict] = await self.aclose()
         if drained:
-        #  ^^^^^^^^TODO? pass these to the `._ctx._drained_msgs:
-        #  deque` and then iterate them as part of any
-        #  `.wait_for_result()` call?
-        #
-        # -[ ] move the match-case processing from
-        #     `.receive_nowait()` instead to right here, use it from
-        #     a for msg in drained:` post-proc loop?
-        #
+            # from .devx import pause
+            # await pause()
             log.warning(
-                'Drained context msgs during closure\n\n'
+                'Drained context msgs during closure:\n'
                 f'{drained}'
             )
+        # TODO: pass these to the `._ctx._drained_msgs: deque`
+        # and then iterate them as part of any `.result()` call?
 
         # NOTE XXX: if the context was cancelled or remote-errored
         # but we received the stream close msg first, we
         # probably want to instead raise the remote error
         # over the end-of-stream connection error since likely
         # the remote error was the source cause?
-        # ctx: Context = self._ctx
+        ctx: Context = self._ctx
         ctx.maybe_raise(
             raise_ctxc_from_self_call=True,
-            from_src_exc=src_err,
         )
 
-        # propagate any error but hide low-level frame details from
-        # the caller by default for console/debug-REPL noise
-        # reduction.
+        # propagate any error but hide low-level frame details
+        # from the caller by default for debug noise reduction.
         if (
             hide_tb
-            and (
 
-                # XXX NOTE special conditions: don't reraise on
-                # certain stream-specific internal error types like,
-                #
-                # - `trio.EoC` since we want to use the exact instance
-                #   to ensure that it is the error that bubbles upward
-                #   for silent absorption by `Context.open_stream()`.
-                not self._eoc
+            # XXX NOTE XXX don't reraise on certain
+            # stream-specific internal error types like,
+            #
+            # - `trio.EoC` since we want to use the exact instance
+            #   to ensure that it is the error that bubbles upward
+            #   for silent absorption by `Context.open_stream()`.
+            and not self._eoc
 
-                # - `RemoteActorError` (or subtypes like ctxc)
-                #    since we want to present the error as though it is
-                #    "sourced" directly from this `.receive()` call and
-                #    generally NOT include the stack frames raised from
-                #    inside the `PldRx` and/or the transport stack
-                #    layers.
-                or isinstance(src_err, RemoteActorError)
-            )
+            # - `RemoteActorError` (or `ContextCancelled`) if it gets
+            #   raised from `_raise_from_no_key_in_msg()` since we
+            #   want the same (as the above bullet) for any
+            #   `.open_context()` block bubbled error raised by
+            #   any nearby ctx API remote-failures.
+            # and not isinstance(src_err, RemoteActorError)
         ):
             raise type(src_err)(*src_err.args) from src_err
         else:
-            # for any non-graceful-EOC we want to NOT hide this frame
-            if not self._eoc:
-                __tracebackhide__: bool = False
-
             raise src_err
 
     async def aclose(self) -> list[Exception|dict]:
@@ -327,6 +271,9 @@ class MsgStream(trio.abc.Channel):
          - more or less we try to maintain adherance to trio's `.aclose()` semantics:
            https://trio.readthedocs.io/en/stable/reference-io.html#trio.abc.AsyncResource.aclose
         '''
+
+        # rx_chan = self._rx_chan
+
         # XXX NOTE XXX
         # it's SUPER IMPORTANT that we ensure we don't DOUBLE
         # DRAIN msgs on closure so avoid getting stuck handing on
@@ -338,16 +285,14 @@ class MsgStream(trio.abc.Channel):
             # this stream has already been closed so silently succeed as
             # per ``trio.AsyncResource`` semantics.
             # https://trio.readthedocs.io/en/stable/reference-io.html#trio.abc.AsyncResource.aclose
-            # import tractor
-            # await tractor.pause()
             return []
 
         ctx: Context = self._ctx
         drained: list[Exception|dict] = []
         while not drained:
             try:
-                maybe_final_msg: Yield|Return = self.receive_nowait(
-                    expect_msg=Yield|Return,
+                maybe_final_msg = self.receive_nowait(
+                    allow_msg_keys=['yield', 'return'],
                 )
                 if maybe_final_msg:
                     log.debug(
@@ -426,37 +371,23 @@ class MsgStream(trio.abc.Channel):
             self._closed = re
 
         # if caught_eoc:
-        #     # from .devx import debug
-        #     # await debug.pause()
+        #     # from .devx import _debug
+        #     # await _debug.pause()
         #     with trio.CancelScope(shield=True):
         #         await rx_chan.aclose()
 
         if not self._eoc:
-            this_side: str = self._ctx.side
-            peer_side: str = self._ctx.peer_side
-            message: str = (
-                f'Stream self-closed by {this_side!r}-side before EoC from {peer_side!r}\n'
-                # } bc a stream is a "scope"/msging-phase inside an IPC
-                f'c}}>\n'
-                f'  |_{self}\n'
+            log.cancel(
+                'Stream closed before it received an EoC?\n'
+                'Setting eoc manually..\n..'
+            )
+            self._eoc: bool = trio.EndOfChannel(
+                f'Context stream closed by {self._ctx.side}\n'
+                f'|_{self}\n'
             )
-            if (
-                (rx_chan := self._rx_chan)
-                and
-                (stats := rx_chan.statistics()).tasks_waiting_receive
-            ):
-                message += (
-                    f'AND there is still reader tasks,\n'
-                    f'\n'
-                    f'{stats}\n'
-                )
-
-            log.cancel(message)
-            self._eoc = trio.EndOfChannel(message)
-
         # ?XXX WAIT, why do we not close the local mem chan `._rx_chan` XXX?
         # => NO, DEFINITELY NOT! <=
-        # if we're a bi-dir `MsgStream` BECAUSE this same
+        # if we're a bi-dir ``MsgStream`` BECAUSE this same
         # core-msg-loop mem recv-chan is used to deliver the
         # potential final result from the surrounding inter-actor
         # `Context` so we don't want to close it until that
@@ -538,9 +469,6 @@ class MsgStream(trio.abc.Channel):
                 self,
                 # use memory channel size by default
                 self._rx_chan._state.max_buffer_size,  # type: ignore
-
-                # TODO: can remove this kwarg right since
-                # by default behaviour is to do this anyway?
                 receive_afunc=self.receive,
             )
 
@@ -587,249 +515,24 @@ class MsgStream(trio.abc.Channel):
 
         try:
             await self._ctx.chan.send(
-                payload=Yield(
-                    cid=self._ctx.cid,
-                    pld=data,
-                ),
+                payload={
+                    'yield': data,
+                    'cid': self._ctx.cid,
+                },
+                # hide_tb=hide_tb,
             )
         except (
             trio.ClosedResourceError,
             trio.BrokenResourceError,
             BrokenPipeError,
-        ) as _trans_err:
-            trans_err = _trans_err
-            if (
-                hide_tb
-                and
-                self._ctx.chan._exc is trans_err
-                # ^XXX, IOW, only if the channel is marked errored
-                # for the same reason as whatever its underlying
-                # transport raised, do we keep the full low-level tb
-                # suppressed from the user.
-            ):
+        ) as trans_err:
+            if hide_tb:
                 raise type(trans_err)(
                     *trans_err.args
                 ) from trans_err
             else:
                 raise
 
-    # TODO: msg capability context api1
-    # @acm
-    # async def enable_msg_caps(
-    #     self,
-    #     msg_subtypes: Union[
-    #         list[list[Struct]],
-    #         Protocol,   # hypothetical type that wraps a msg set
-    #     ],
-    # ) -> tuple[Callable, Callable]:  # payload enc, dec pair
-    #     ...
-
-
-@acm
-async def open_stream_from_ctx(
-    ctx: Context,
-    allow_overruns: bool|None = False,
-    msg_buffer_size: int|None = None,
-
-) -> AsyncGenerator[MsgStream, None]:
-    '''
-    Open a `MsgStream`, a bi-directional msg transport dialog
-    connected to the cross-actor peer task for an IPC `Context`.
-
-    This context manager must be entered in both the "parent" (task
-    which entered `Portal.open_context()`) and "child" (RPC task
-    which is decorated by `@context`) tasks for the stream to
-    logically be considered "open"; if one side begins sending to an
-    un-opened peer, depending on policy config, msgs will either be
-    queued until the other side opens and/or a `StreamOverrun` will
-    (eventually) be raised.
-
-                         ------ - ------
-
-    Runtime semantics design:
-
-    A `MsgStream` session adheres to "one-shot use" semantics,
-    meaning if you close the scope it **can not** be "re-opened".
-
-    Instead you must re-establish a new surrounding RPC `Context`
-    (RTC: remote task context?) using `Portal.open_context()`.
-
-    In the future this *design choice* may need to be changed but
-    currently there seems to be no obvious reason to support such
-    semantics..
-
-    - "pausing a stream" can be supported with a message implemented
-      by the `tractor` application dev.
-
-    - any remote error will normally require a restart of the entire
-      `trio.Task`'s scope due to the nature of `trio`'s cancellation
-      (`CancelScope`) system and semantics (level triggered).
-
-    '''
-    actor: Actor = ctx._actor
-
-    # If the surrounding context has been cancelled by some
-    # task with a handle to THIS, we error here immediately
-    # since it likely means the surrounding lexical-scope has
-    # errored, been `trio.Cancelled` or at the least
-    # `Context.cancel()` was called by some task.
-    if ctx._cancel_called:
-
-        # XXX NOTE: ALWAYS RAISE any remote error here even if
-        # it's an expected `ContextCancelled` due to a local
-        # task having called `.cancel()`!
-        #
-        # WHY: we expect the error to always bubble up to the
-        # surrounding `Portal.open_context()` call and be
-        # absorbed there (silently) and we DO NOT want to
-        # actually try to stream - a cancel msg was already
-        # sent to the other side!
-        ctx.maybe_raise(
-            raise_ctxc_from_self_call=True,
-        )
-        # NOTE: this is diff then calling
-        # `._maybe_raise_remote_err()` specifically
-        # because we want to raise a ctxc on any task entering this `.open_stream()`
-        # AFTER cancellation was already been requested,
-        # we DO NOT want to absorb any ctxc ACK silently!
-        # if ctx._remote_error:
-        #     raise ctx._remote_error
-
-        # XXX NOTE: if no `ContextCancelled` has been responded
-        # back from the other side (yet), we raise a different
-        # runtime error indicating that this task's usage of
-        # `Context.cancel()` and then `.open_stream()` is WRONG!
-        task: str = trio.lowlevel.current_task().name
-        raise RuntimeError(
-            'Stream opened after `Context.cancel()` called..?\n'
-            f'task: {actor.uid[0]}:{task}\n'
-            f'{ctx}'
-        )
-
-    if (
-        not ctx._portal
-        and not ctx._started_called
-    ):
-        raise RuntimeError(
-            'Context.started()` must be called before opening a stream'
-        )
-
-    # NOTE: in one way streaming this only happens on the
-    # parent-ctx-task side (on the side that calls
-    # `Actor.start_remote_task()`) so if you try to send
-    # a stop from the caller to the callee in the
-    # single-direction-stream case you'll get a lookup error
-    # currently.
-    ctx: Context = actor.get_context(
-        chan=ctx.chan,
-        cid=ctx.cid,
-        nsf=ctx._nsf,
-        # side=ctx.side,
-
-        msg_buffer_size=msg_buffer_size,
-        allow_overruns=allow_overruns,
-    )
-    ctx._allow_overruns: bool = allow_overruns
-    assert ctx is ctx
-
-    # XXX: If the underlying channel feeder receive mem chan has
-    # been closed then likely client code has already exited
-    # a ``.open_stream()`` block prior or there was some other
-    # unanticipated error or cancellation from ``trio``.
-
-    if ctx._rx_chan._closed:
-        raise trio.ClosedResourceError(
-            'The underlying channel for this stream was already closed!\n'
-        )
-
-    # NOTE: implicitly this will call `MsgStream.aclose()` on
-    # `.__aexit__()` due to stream's parent `Channel` type!
-    #
-    # XXX NOTE XXX: ensures the stream is "one-shot use",
-    # which specifically means that on exit,
-    # - signal ``trio.EndOfChannel``/``StopAsyncIteration`` to
-    #   the far end indicating that the caller exited
-    #   the streaming context purposefully by letting
-    #   the exit block exec.
-    # - this is diff from the cancel/error case where
-    #   a cancel request from this side or an error
-    #   should be sent to the far end indicating the
-    #   stream WAS NOT just closed normally/gracefully.
-    async with MsgStream(
-        ctx=ctx,
-        rx_chan=ctx._rx_chan,
-    ) as stream:
-
-        # NOTE: we track all existing streams per portal for
-        # the purposes of attempting graceful closes on runtime
-        # cancel requests.
-        if ctx._portal:
-            ctx._portal._streams.add(stream)
-
-        try:
-            ctx._stream_opened: bool = True
-            ctx._stream = stream
-
-            # XXX: do we need this?
-            # ensure we aren't cancelled before yielding the stream
-            # await trio.lowlevel.checkpoint()
-            yield stream
-
-            # XXX: (MEGA IMPORTANT) if this is a root opened process we
-            # wait for any immediate child in debug before popping the
-            # context from the runtime msg loop otherwise inside
-            # ``Actor._deliver_ctx_payload()`` the msg will be discarded and in
-            # the case where that msg is global debugger unlock (via
-            # a "stop" msg for a stream), this can result in a deadlock
-            # where the root is waiting on the lock to clear but the
-            # child has already cleared it and clobbered IPC.
-            #
-            # await maybe_wait_for_debugger()
-
-            # XXX TODO: pretty sure this isn't needed (see
-            # note above this block) AND will result in
-            # a double `.send_stop()` call. The only reason to
-            # put it here would be to due with "order" in
-            # terms of raising any remote error (as per
-            # directly below) or bc the stream's
-            # `.__aexit__()` block might not get run
-            # (doubtful)? Either way if we did put this back
-            # in we also need a state var to avoid the double
-            # stop-msg send..
-            #
-            # await stream.aclose()
-
-        # NOTE: absorb and do not raise any
-        # EoC received from the other side such that
-        # it is not raised inside the surrounding
-        # context block's scope!
-        except trio.EndOfChannel as eoc:
-            if (
-                eoc
-                and
-                stream.closed
-            ):
-                # sanity, can remove?
-                assert eoc is stream._eoc
-
-                log.runtime(
-                    'Stream was terminated by EoC\n\n'
-                    # NOTE: won't show the error <Type> but
-                    # does show txt followed by IPC msg.
-                    f'{str(eoc)}\n'
-                )
-        finally:
-            if ctx._portal:
-                try:
-                    ctx._portal._streams.remove(stream)
-                except KeyError:
-                    log.warning(
-                        f'Stream was already destroyed?\n'
-                        f'actor: {ctx.chan.uid}\n'
-                        f'ctx id: {ctx.cid}'
-                    )
-
-
 
 def stream(func: Callable) -> Callable:
     '''
@@ -838,7 +541,7 @@ def stream(func: Callable) -> Callable:
     '''
     # TODO: apply whatever solution ``mypy`` ends up picking for this:
     # https://github.com/python/mypy/issues/2087#issuecomment-769266912
-    func._tractor_stream_function: bool = True  # type: ignore
+    func._tractor_stream_function = True  # type: ignore
 
     sig = inspect.signature(func)
     params = sig.parameters

tractor/_supervise.py

@@ -22,20 +22,13 @@ from contextlib import asynccontextmanager as acm
 from functools import partial
 import inspect
 from pprint import pformat
-from typing import (
-    TYPE_CHECKING,
-)
+from typing import TYPE_CHECKING
 import typing
 import warnings
 
 import trio
 
-
-from .devx.debug import maybe_wait_for_debugger
-from ._addr import (
-    UnwrappedAddress,
-    mk_uuid,
-)
+from .devx._debug import maybe_wait_for_debugger
 from ._state import current_actor, is_main_process
 from .log import get_logger, get_loglevel
 from ._runtime import Actor
@@ -44,21 +37,18 @@ from ._exceptions import (
     is_multi_cancelled,
     ContextCancelled,
 )
-from ._root import (
-    open_root_actor,
-)
+from ._root import open_root_actor
 from . import _state
 from . import _spawn
 
 
 if TYPE_CHECKING:
     import multiprocessing as mp
-    # from .ipc._server import IPCServer
-    from .ipc import IPCServer
-
 
 log = get_logger(__name__)
 
+_default_bind_addr: tuple[str, int] = ('127.0.0.1', 0)
+
 
 class ActorNursery:
     '''
@@ -90,19 +80,15 @@ class ActorNursery:
     '''
     def __init__(
         self,
-        # TODO: maybe def these as fields of a struct looking type?
         actor: Actor,
         ria_nursery: trio.Nursery,
         da_nursery: trio.Nursery,
         errors: dict[tuple[str, str], BaseException],
-
     ) -> None:
         # self.supervisor = supervisor  # TODO
         self._actor: Actor = actor
-
-        # TODO: rename to `._tn` for our conventional "task-nursery"
+        self._ria_nursery = ria_nursery
         self._da_nursery = da_nursery
-
         self._children: dict[
             tuple[str, str],
             tuple[
@@ -111,12 +97,13 @@ class ActorNursery:
                 Portal | None,
             ]
         ] = {}
-
+        # portals spawned with ``run_in_actor()`` are
+        # cancelled when their "main" result arrives
+        self._cancel_after_result_on_exit: set = set()
         self.cancelled: bool = False
         self._join_procs = trio.Event()
         self._at_least_one_child_in_debug: bool = False
         self.errors = errors
-        self._scope_error: BaseException|None = None
         self.exited = trio.Event()
 
         # NOTE: when no explicit call is made to
@@ -127,50 +114,28 @@ class ActorNursery:
         # and syncing purposes to any actor opened nurseries.
         self._implicit_runtime_started: bool = False
 
-        # TODO: remove the `.run_in_actor()` API and thus this 2ndary
-        # nursery when that API get's moved outside this primitive!
-        self._ria_nursery = ria_nursery
-        # portals spawned with ``run_in_actor()`` are
-        # cancelled when their "main" result arrives
-        self._cancel_after_result_on_exit: set = set()
-
     async def start_actor(
         self,
         name: str,
-
         *,
-
-        bind_addrs: list[UnwrappedAddress]|None = None,
+        bind_addrs: list[tuple[str, int]] = [_default_bind_addr],
         rpc_module_paths: list[str]|None = None,
-        enable_transports: list[str] = [_state._def_tpt_proto],
         enable_modules: list[str]|None = None,
         loglevel: str|None = None,  # set log level per subactor
+        nursery: trio.Nursery|None = None,
         debug_mode: bool|None = None,
         infect_asyncio: bool = False,
-
-        # TODO: ideally we can rm this once we no longer have
-        # a `._ria_nursery` since the dependent APIs have been
-        # removed!
-        nursery: trio.Nursery|None = None,
-        proc_kwargs: dict[str, any] = {}
-
     ) -> Portal:
         '''
         Start a (daemon) actor: an process that has no designated
         "main task" besides the runtime.
 
         '''
-        __runtimeframe__: int = 1  # noqa
-        loglevel: str = (
-            loglevel
-            or self._actor.loglevel
-            or get_loglevel()
-        )
+        loglevel = loglevel or self._actor.loglevel or get_loglevel()
 
         # configure and pass runtime state
         _rtv = _state._runtime_vars.copy()
         _rtv['_is_root'] = False
-        _rtv['_is_infected_aio'] = infect_asyncio
 
         # allow setting debug policy per actor
         if debug_mode is not None:
@@ -189,9 +154,7 @@ class ActorNursery:
             enable_modules.extend(rpc_module_paths)
 
         subactor = Actor(
-            name=name,
-            uuid=mk_uuid(),
-
+            name,
             # modules allowed to invoked funcs from
             enable_modules=enable_modules,
             loglevel=loglevel,
@@ -199,7 +162,7 @@ class ActorNursery:
             # verbatim relay this actor's registrar addresses
             registry_addrs=current_actor().reg_addrs,
         )
-        parent_addr: UnwrappedAddress = self._actor.accept_addr
+        parent_addr = self._actor.accept_addr
         assert parent_addr
 
         # start a task to spawn a process
@@ -218,18 +181,9 @@ class ActorNursery:
                 parent_addr,
                 _rtv,  # run time vars
                 infect_asyncio=infect_asyncio,
-                proc_kwargs=proc_kwargs
             )
         )
 
-    # TODO: DEPRECATE THIS:
-    # -[ ] impl instead as a hilevel wrapper on
-    #   top of a `@context` style invocation.
-    #  |_ dynamic @context decoration on child side
-    #  |_ implicit `Portal.open_context() as (ctx, first):`
-    #    and `return first` on parent side.
-    #  |_ mention how it's similar to `trio-parallel` API?
-    # -[ ] use @api_frame on the wrapper
     async def run_in_actor(
         self,
 
@@ -237,12 +191,11 @@ class ActorNursery:
         *,
 
         name: str | None = None,
-        bind_addrs: UnwrappedAddress|None = None,
+        bind_addrs: tuple[str, int] = [_default_bind_addr],
         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,
-        proc_kwargs: dict[str, any] = {},
 
         **kwargs,  # explicit args to ``fn``
 
@@ -256,14 +209,13 @@ class ActorNursery:
         the actor is terminated.
 
         '''
-        __runtimeframe__: int = 1  # noqa
         mod_path: str = fn.__module__
 
         if name is None:
             # use the explicit function name if not provided
             name = fn.__name__
 
-        portal: Portal = await self.start_actor(
+        portal = await self.start_actor(
             name,
             enable_modules=[mod_path] + (
                 enable_modules or rpc_module_paths or []
@@ -273,7 +225,6 @@ class ActorNursery:
             # use the run_in_actor nursery
             nursery=self._ria_nursery,
             infect_asyncio=infect_asyncio,
-            proc_kwargs=proc_kwargs
         )
 
         # XXX: don't allow stream funcs
@@ -293,24 +244,19 @@ class ActorNursery:
         )
         return portal
 
-    # @api_frame
     async def cancel(
         self,
         hard_kill: bool = False,
 
     ) -> None:
         '''
-        Cancel this actor-nursery by instructing each subactor's
-        runtime to cancel and wait for all underlying sub-processes
-        to terminate.
+        Cancel this nursery by instructing each subactor to cancel
+        itself and wait for all subactors to terminate.
 
-        If `hard_kill` is set then kill the processes directly using
-        the spawning-backend's API/OS-machinery without any attempt
-        at (graceful) `trio`-style cancellation using our
-        `Actor.cancel()`.
+        If ``hard_killl`` is set to ``True`` then kill the processes
+        directly without any far end graceful ``trio`` cancellation.
 
         '''
-        __runtimeframe__: int = 1  # noqa
         self.cancelled = True
 
         # TODO: impl a repr for spawn more compact
@@ -318,13 +264,8 @@ class ActorNursery:
         children: dict = self._children
         child_count: int = len(children)
         msg: str = f'Cancelling actor nursery with {child_count} children\n'
-
-        server: IPCServer = self._actor.ipc_server
-
         with trio.move_on_after(3) as cs:
-            async with trio.open_nursery(
-                strict_exception_groups=False,
-            ) as tn:
+            async with trio.open_nursery() as tn:
 
                 subactor: Actor
                 proc: trio.Process
@@ -343,7 +284,7 @@ class ActorNursery:
 
                     else:
                         if portal is None:  # actor hasn't fully spawned yet
-                            event: trio.Event = server._peer_connected[subactor.uid]
+                            event = self._actor._peer_connected[subactor.uid]
                             log.warning(
                                 f"{subactor.uid} never 't finished spawning?"
                             )
@@ -359,7 +300,7 @@ class ActorNursery:
                             if portal is None:
                                 # cancelled while waiting on the event
                                 # to arrive
-                                chan = server._peers[subactor.uid][-1]
+                                chan = self._actor._peers[subactor.uid][-1]
                                 if chan:
                                     portal = Portal(chan)
                                 else:  # there's no other choice left
@@ -396,15 +337,11 @@ class ActorNursery:
 @acm
 async def _open_and_supervise_one_cancels_all_nursery(
     actor: Actor,
-    tb_hide: bool = False,
 
 ) -> typing.AsyncGenerator[ActorNursery, None]:
 
-    # normally don't need to show user by default
-    __tracebackhide__: bool = tb_hide
-
-    outer_err: BaseException|None = None
-    inner_err: BaseException|None = None
+    # TODO: yay or nay?
+    __tracebackhide__ = True
 
     # the collection of errors retreived from spawned sub-actors
     errors: dict[tuple[str, str], BaseException] = {}
@@ -414,26 +351,20 @@ async def _open_and_supervise_one_cancels_all_nursery(
     # handling errors that are generated by the inner nursery in
     # a supervisor strategy **before** blocking indefinitely to wait for
     # actors spawned in "daemon mode" (aka started using
-    # `ActorNursery.start_actor()`).
+    # ``ActorNursery.start_actor()``).
 
     # errors from this daemon actor nursery bubble up to caller
-    async with trio.open_nursery(
-        strict_exception_groups=False,
-        # ^XXX^ TODO? instead unpack any RAE as per "loose" style?
-    ) as da_nursery:
+    async with trio.open_nursery() as da_nursery:
         try:
             # This is the inner level "run in actor" nursery. It is
             # awaited first since actors spawned in this way (using
-            # `ActorNusery.run_in_actor()`) are expected to only
+            # ``ActorNusery.run_in_actor()``) are expected to only
             # return a single result and then complete (i.e. be canclled
             # gracefully). Errors collected from these actors are
             # immediately raised for handling by a supervisor strategy.
             # As such if the strategy propagates any error(s) upwards
             # the above "daemon actor" nursery will be notified.
-            async with trio.open_nursery(
-                strict_exception_groups=False,
-                # ^XXX^ TODO? instead unpack any RAE as per "loose" style?
-            ) as ria_nursery:
+            async with trio.open_nursery() as ria_nursery:
 
                 an = ActorNursery(
                     actor,
@@ -455,8 +386,7 @@ async def _open_and_supervise_one_cancels_all_nursery(
                     )
                     an._join_procs.set()
 
-                except BaseException as _inner_err:
-                    inner_err = _inner_err
+                except BaseException as inner_err:
                     errors[actor.uid] = inner_err
 
                     # If we error in the root but the debugger is
@@ -500,8 +430,8 @@ async def _open_and_supervise_one_cancels_all_nursery(
                             ContextCancelled,
                         }:
                             log.cancel(
-                                'Actor-nursery caught remote cancellation\n'
-                                '\n'
+                                'Actor-nursery caught remote cancellation\n\n'
+
                                 f'{inner_err.tb_str}'
                             )
                         else:
@@ -534,10 +464,8 @@ async def _open_and_supervise_one_cancels_all_nursery(
             Exception,
             BaseExceptionGroup,
             trio.Cancelled
-        ) as _outer_err:
-            outer_err = _outer_err
 
-            an._scope_error = outer_err or inner_err
+        ) as err:
 
             # XXX: yet another guard before allowing the cancel
             # sequence in case a (single) child is in debug.
@@ -552,7 +480,7 @@ async def _open_and_supervise_one_cancels_all_nursery(
             if an._children:
                 log.cancel(
                     'Actor-nursery cancelling due error type:\n'
-                    f'{outer_err}\n'
+                    f'{err}\n'
                 )
                 with trio.CancelScope(shield=True):
                     await an.cancel()
@@ -579,23 +507,13 @@ async def _open_and_supervise_one_cancels_all_nursery(
                 else:
                     raise list(errors.values())[0]
 
-            # show frame on any (likely) internal error
-            if (
-                not an.cancelled
-                and an._scope_error
-            ):
-                __tracebackhide__: bool = False
-
         # da_nursery scope end - nursery checkpoint
     # final exit
 
 
 @acm
-# @api_frame
 async def open_nursery(
-    hide_tb: bool = True,
     **kwargs,
-    # ^TODO, paramspec for `open_root_actor()`
 
 ) -> typing.AsyncGenerator[ActorNursery, None]:
     '''
@@ -613,7 +531,6 @@ async def open_nursery(
     which cancellation scopes correspond to each spawned subactor set.
 
     '''
-    __tracebackhide__: bool = hide_tb
     implicit_runtime: bool = False
     actor: Actor = current_actor(err_on_no_runtime=False)
     an: ActorNursery|None = None
@@ -629,10 +546,7 @@ async def open_nursery(
             # mark us for teardown on exit
             implicit_runtime: bool = True
 
-            async with open_root_actor(
-                hide_tb=hide_tb,
-                **kwargs,
-            ) as actor:
+            async with open_root_actor(**kwargs) as actor:
                 assert actor is current_actor()
 
                 try:
@@ -667,27 +581,13 @@ async def open_nursery(
                 an.exited.set()
 
     finally:
-        # show frame on any internal runtime-scope error
-        if (
-            an
-            and
-            not an.cancelled
-            and
-            an._scope_error
-        ):
-            __tracebackhide__: bool = False
-
         msg: str = (
             'Actor-nursery exited\n'
             f'|_{an}\n'
         )
 
+        # shutdown runtime if it was started
         if implicit_runtime:
-            # shutdown runtime if it was started and report noisly
-            # that we're did so.
             msg += '=> Shutting down actor runtime <=\n'
-            log.info(msg)
 
-        else:
-            # keep noise low during std operation.
-            log.runtime(msg)
+        log.info(msg)

tractor/_testing/__init__.py

@@ -19,27 +19,15 @@ Various helpers/utils for auditing your `tractor` app and/or the
 core runtime.
 
 '''
-from contextlib import (
-    asynccontextmanager as acm,
-)
-import os
+from contextlib import asynccontextmanager as acm
 import pathlib
 
 import tractor
-from tractor.devx.debug import (
-    BoxedMaybeException,
-)
 from .pytest import (
     tractor_test as tractor_test
 )
-from .fault_simulation import (
-    break_ipc as break_ipc,
-)
 
 
-# TODO, use dulwhich for this instead?
-# -> we're going to likely need it (or something similar)
-#   for supporting hot-coad reload feats eventually anyway!
 def repodir() -> pathlib.Path:
     '''
     Return the abspath to the repo directory.
@@ -63,35 +51,6 @@ def examples_dir() -> pathlib.Path:
     return repodir() / 'examples'
 
 
-def mk_cmd(
-    ex_name: str,
-    exs_subpath: str = 'debugging',
-) -> str:
-    '''
-    Generate a shell command suitable to pass to `pexpect.spawn()`
-    which runs the script as a python program's entrypoint.
-
-    In particular ensure we disable the new tb coloring via unsetting
-    `$PYTHON_COLORS` so that `pexpect` can pattern match without
-    color-escape-codes.
-
-    '''
-    script_path: pathlib.Path = (
-        examples_dir()
-        / exs_subpath
-        / f'{ex_name}.py'
-    )
-    py_cmd: str = ' '.join([
-        'python',
-        str(script_path)
-    ])
-    # XXX, required for py 3.13+
-    # https://docs.python.org/3/using/cmdline.html#using-on-controlling-color
-    # https://docs.python.org/3/using/cmdline.html#envvar-PYTHON_COLORS
-    os.environ['PYTHON_COLORS'] = '0'
-    return py_cmd
-
-
 @acm
 async def expect_ctxc(
     yay: bool,
@@ -104,13 +63,12 @@ async def expect_ctxc(
     '''
     if yay:
         try:
-            yield (maybe_exc := BoxedMaybeException())
+            yield
             raise RuntimeError('Never raised ctxc?')
-        except tractor.ContextCancelled as ctxc:
-            maybe_exc.value = ctxc
+        except tractor.ContextCancelled:
             if reraise:
                 raise
             else:
                 return
     else:
-        yield (maybe_exc := BoxedMaybeException())
+        yield

tractor/_testing/addr.py

@@ -1,70 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-'''
-Random IPC addr generation for isolating
-the discovery space between test sessions.
-
-Might be eventually useful to expose as a util set from
-our `tractor.discovery` subsys?
-
-'''
-import random
-from typing import (
-    Type,
-)
-from tractor import (
-    _addr,
-)
-
-
-def get_rando_addr(
-    tpt_proto: str,
-    *,
-
-    # choose random port at import time
-    _rando_port: str = random.randint(1000, 9999)
-
-) -> tuple[str, str|int]:
-    '''
-    Used to globally override the runtime to the
-    per-test-session-dynamic addr so that all tests never conflict
-    with any other actor tree using the default.
-
-    '''
-    addr_type: Type[_addr.Addres] = _addr._address_types[tpt_proto]
-    def_reg_addr: tuple[str, int] = _addr._default_lo_addrs[tpt_proto]
-
-    # this is the "unwrapped" form expected to be passed to
-    # `.open_root_actor()` by test body.
-    testrun_reg_addr: tuple[str, int|str]
-    match tpt_proto:
-        case 'tcp':
-            testrun_reg_addr = (
-                addr_type.def_bindspace,
-                _rando_port,
-            )
-
-        # NOTE, file-name uniqueness (no-collisions) will be based on
-        # the runtime-directory and root (pytest-proc's) pid.
-        case 'uds':
-            testrun_reg_addr = addr_type.get_random().unwrap()
-
-    # XXX, as sanity it should never the same as the default for the
-    # host-singleton registry actor.
-    assert def_reg_addr != testrun_reg_addr
-
-    return testrun_reg_addr

tractor/_testing/fault_simulation.py

@@ -1,92 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-'''
-`pytest` utils helpers and plugins for testing `tractor`'s runtime
-and applications.
-
-'''
-
-from tractor import (
-    MsgStream,
-)
-
-async def break_ipc(
-    stream: MsgStream,
-    method: str|None = None,
-    pre_close: bool = False,
-
-    def_method: str = 'socket_close',
-
-) -> None:
-    '''
-    XXX: close the channel right after an error is raised
-    purposely breaking the IPC transport to make sure the parent
-    doesn't get stuck in debug or hang on the connection join.
-    this more or less simulates an infinite msg-receive hang on
-    the other end.
-
-    '''
-    # close channel via IPC prot msging before
-    # any transport breakage
-    if pre_close:
-        await stream.aclose()
-
-    method: str = method or def_method
-    print(
-        '#################################\n'
-        'Simulating CHILD-side IPC BREAK!\n'
-        f'method: {method}\n'
-        f'pre `.aclose()`: {pre_close}\n'
-        '#################################\n'
-    )
-
-    match method:
-        case 'socket_close':
-            await stream._ctx.chan.transport.stream.aclose()
-
-        case 'socket_eof':
-            # NOTE: `trio` does the following underneath this
-            # call in `src/trio/_highlevel_socket.py`:
-            # `Stream.socket.shutdown(tsocket.SHUT_WR)`
-            await stream._ctx.chan.transport.stream.send_eof()
-
-        # TODO: remove since now this will be invalid with our
-        # new typed msg spec?
-        # case 'msg':
-        #     await stream._ctx.chan.send(None)
-
-        # TODO: the actual real-world simulated cases like
-        # transport layer hangs and/or lower layer 2-gens type
-        # scenarios..
-        #
-        # -[ ] already have some issues for this general testing
-        # area:
-        #  - https://github.com/goodboy/tractor/issues/97
-        #  - https://github.com/goodboy/tractor/issues/124
-        #   - PR from @guille:
-        #     https://github.com/goodboy/tractor/pull/149
-        # case 'hang':
-        # TODO: framework research:
-        #
-        # - https://github.com/GuoTengda1993/pynetem
-        # - https://github.com/shopify/toxiproxy
-        # - https://manpages.ubuntu.com/manpages/trusty/man1/wirefilter.1.html
-
-        case _:
-            raise RuntimeError(
-                f'IPC break method unsupported: {method}'
-            )

tractor/_testing/pytest.py

@@ -26,46 +26,29 @@ from functools import (
 import inspect
 import platform
 
-import pytest
 import tractor
 import trio
 
 
 def tractor_test(fn):
     '''
-    Decorator for async test fns to decorator-wrap them as "native"
-    looking sync funcs runnable by `pytest` and auto invoked with
-    `trio.run()` (much like the `pytest-trio` plugin's approach).
+    Decorator for async test funcs to present them as "native"
+    looking sync funcs runnable by `pytest` using `trio.run()`.
 
-    Further the test fn body will be invoked AFTER booting the actor
-    runtime, i.e. from inside a `tractor.open_root_actor()` block AND
-    with various runtime and tooling parameters implicitly passed as
-    requested by by the test session's config; see immediately below.
+    Use:
 
-    Basic deco use:
-    ---------------
+    @tractor_test
+    async def test_whatever():
+        await ...
 
-      @tractor_test
-      async def test_whatever():
-          await ...
+    If fixtures:
 
+        - ``reg_addr`` (a socket addr tuple where arbiter is listening)
+        - ``loglevel`` (logging level passed to tractor internals)
+        - ``start_method`` (subprocess spawning backend)
 
-    Runtime config via special fixtures:
-    ------------------------------------
-    If any of the following fixture are requested by the wrapped test
-    fn (via normal func-args declaration),
-
-    - `reg_addr` (a socket addr tuple where arbiter is listening)
-    - `loglevel` (logging level passed to tractor internals)
-    - `start_method` (subprocess spawning backend)
-
-    (TODO support)
-    - `tpt_proto` (IPC transport protocol key)
-
-    they will be automatically injected to each test as normally
-    expected as well as passed to the initial
-    `tractor.open_root_actor()` funcargs.
-
+    are defined in the `pytest` fixture space they will be automatically
+    injected to tests declaring these funcargs.
     '''
     @wraps(fn)
     def wrapper(
@@ -128,164 +111,3 @@ def tractor_test(fn):
         return trio.run(main)
 
     return wrapper
-
-
-def pytest_addoption(
-    parser: pytest.Parser,
-):
-    # parser.addoption(
-    #     "--ll",
-    #     action="store",
-    #     dest='loglevel',
-    #     default='ERROR', help="logging level to set when testing"
-    # )
-
-    parser.addoption(
-        "--spawn-backend",
-        action="store",
-        dest='spawn_backend',
-        default='trio',
-        help="Processing spawning backend to use for test run",
-    )
-
-    parser.addoption(
-        "--tpdb",
-        "--debug-mode",
-        action="store_true",
-        dest='tractor_debug_mode',
-        # default=False,
-        help=(
-            'Enable a flag that can be used by tests to to set the '
-            '`debug_mode: bool` for engaging the internal '
-            'multi-proc debugger sys.'
-        ),
-    )
-
-    # provide which IPC transport protocols opting-in test suites
-    # should accumulatively run against.
-    parser.addoption(
-        "--tpt-proto",
-        nargs='+',  # accumulate-multiple-args
-        action="store",
-        dest='tpt_protos',
-        default=['tcp'],
-        help="Transport protocol to use under the `tractor.ipc.Channel`",
-    )
-
-
-def pytest_configure(config):
-    backend = config.option.spawn_backend
-    tractor._spawn.try_set_start_method(backend)
-
-
-@pytest.fixture(scope='session')
-def debug_mode(request) -> bool:
-    '''
-    Flag state for whether `--tpdb` (for `tractor`-py-debugger)
-    was passed to the test run.
-
-    Normally tests should pass this directly to `.open_root_actor()`
-    to allow the user to opt into suite-wide crash handling.
-
-    '''
-    debug_mode: bool = request.config.option.tractor_debug_mode
-    return debug_mode
-
-
-@pytest.fixture(scope='session')
-def spawn_backend(request) -> str:
-    return request.config.option.spawn_backend
-
-
-@pytest.fixture(scope='session')
-def tpt_protos(request) -> list[str]:
-
-    # allow quoting on CLI
-    proto_keys: list[str] = [
-        proto_key.replace('"', '').replace("'", "")
-        for proto_key in request.config.option.tpt_protos
-    ]
-
-    # ?TODO, eventually support multiple protos per test-sesh?
-    if len(proto_keys) > 1:
-        pytest.fail(
-            'We only support one `--tpt-proto <key>` atm!\n'
-        )
-
-    # XXX ensure we support the protocol by name via lookup!
-    for proto_key in proto_keys:
-        addr_type = tractor._addr._address_types[proto_key]
-        assert addr_type.proto_key == proto_key
-
-    yield proto_keys
-
-
-@pytest.fixture(
-    scope='session',
-    autouse=True,
-)
-def tpt_proto(
-    tpt_protos: list[str],
-) -> str:
-    proto_key: str = tpt_protos[0]
-
-    from tractor import _state
-    if _state._def_tpt_proto != proto_key:
-        _state._def_tpt_proto = proto_key
-
-    yield proto_key
-
-
-@pytest.fixture(scope='session')
-def reg_addr(
-    tpt_proto: str,
-) -> tuple[str, int|str]:
-    '''
-    Deliver a test-sesh unique registry address such
-    that each run's (tests which use this fixture) will
-    have no conflicts/cross-talk when running simultaneously
-    nor will interfere with other live `tractor` apps active
-    on the same network-host (namespace).
-
-    '''
-    from tractor._testing.addr import get_rando_addr
-    return get_rando_addr(
-        tpt_proto=tpt_proto,
-    )
-
-
-def pytest_generate_tests(
-    metafunc: pytest.Metafunc,
-):
-    spawn_backend: str = metafunc.config.option.spawn_backend
-
-    if not spawn_backend:
-        # XXX some weird windows bug with `pytest`?
-        spawn_backend = 'trio'
-
-    # TODO: maybe just use the literal `._spawn.SpawnMethodKey`?
-    assert spawn_backend in (
-        'mp_spawn',
-        'mp_forkserver',
-        'trio',
-    )
-
-    # NOTE: used-to-be-used-to dyanmically parametrize tests for when
-    # you just passed --spawn-backend=`mp` on the cli, but now we expect
-    # that cli input to be manually specified, BUT, maybe we'll do
-    # something like this again in the future?
-    if 'start_method' in metafunc.fixturenames:
-        metafunc.parametrize(
-            "start_method",
-            [spawn_backend],
-            scope='module',
-        )
-
-    # TODO, parametrize any `tpt_proto: str` declaring tests!
-    # proto_tpts: list[str] = metafunc.config.option.proto_tpts
-    # if 'tpt_proto' in metafunc.fixturenames:
-    #     metafunc.parametrize(
-    #         'tpt_proto',
-    #         proto_tpts,  # TODO, double check this list usage!
-    #         scope='module',
-    #     )

tractor/_testing/samples.py

@@ -1,35 +0,0 @@
-import os
-import random
-
-
-def generate_sample_messages(
-    amount: int,
-    rand_min: int = 0,
-    rand_max: int = 0,
-    silent: bool = False
-) -> tuple[list[bytes], int]:
-
-    msgs = []
-    size = 0
-
-    if not silent:
-        print(f'\ngenerating {amount} messages...')
-
-    for i in range(amount):
-        msg = f'[{i:08}]'.encode('utf-8')
-
-        if rand_max > 0:
-            msg += os.urandom(
-                random.randint(rand_min, rand_max))
-
-        size += len(msg)
-
-        msgs.append(msg)
-
-        if not silent and i and i % 10_000 == 0:
-            print(f'{i} generated')
-
-    if not silent:
-        print(f'done, {size:,} bytes in total')
-
-    return msgs, size

tractor/devx/__init__.py

@@ -20,30 +20,28 @@ Runtime "developer experience" utils and addons to aid our
 and working with/on the actor runtime.
 
 """
-from .debug import (
+from ._debug import (
     maybe_wait_for_debugger as maybe_wait_for_debugger,
     acquire_debug_lock as acquire_debug_lock,
     breakpoint as breakpoint,
     pause as pause,
     pause_from_sync as pause_from_sync,
-    sigint_shield as sigint_shield,
+    shield_sigint_handler as shield_sigint_handler,
+    MultiActorPdb as MultiActorPdb,
     open_crash_handler as open_crash_handler,
     maybe_open_crash_handler as maybe_open_crash_handler,
-    maybe_init_greenback as maybe_init_greenback,
     post_mortem as post_mortem,
-    mk_pdb as mk_pdb,
 )
 from ._stackscope import (
     enable_stack_on_sig as enable_stack_on_sig,
 )
-from .pformat import (
-    add_div as add_div,
-    pformat_caller_frame as pformat_caller_frame,
-    pformat_boxed_tb as pformat_boxed_tb,
-)
+# from .pformat import (
+#     add_div as add_div,
+#     pformat_caller_frame as pformat_caller_frame,
+#     pformat_boxed_tb as pformat_boxed_tb,
+# )
 
 
-# TODO, move this to a new `.devx._pdbp` mod?
 def _enable_readline_feats() -> str:
     '''
     Handle `readline` when compiled with `libedit` to avoid breaking
@@ -75,4 +73,5 @@ def _enable_readline_feats() -> str:
         return 'readline'
 
 
+# TODO, move this to a new `.devx._pdbp` mod?
 _enable_readline_feats()

tractor/devx/_code.py

@@ -0,0 +1,177 @@
+# tractor: structured concurrent "actors".
+# Copyright 2018-eternity Tyler Goodlet.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+'''
+Tools for code-object annotation, introspection and mutation
+as it pertains to improving the grok-ability of our runtime!
+
+'''
+from __future__ import annotations
+import inspect
+# import msgspec
+# from pprint import pformat
+from types import (
+    FrameType,
+    FunctionType,
+    MethodType,
+    # CodeType,
+)
+from typing import (
+    # Any,
+    Callable,
+    # TYPE_CHECKING,
+    Type,
+)
+
+from tractor.msg import (
+    pretty_struct,
+    NamespacePath,
+)
+
+
+# TODO: yeah, i don't love this and we should prolly just
+# write a decorator that actually keeps a stupid ref to the func
+# obj..
+def get_class_from_frame(fr: FrameType) -> (
+    FunctionType
+    |MethodType
+):
+    '''
+    Attempt to get the function (or method) reference
+    from a given `FrameType`.
+
+    Verbatim from an SO:
+    https://stackoverflow.com/a/2220759
+
+    '''
+    args, _, _, value_dict = inspect.getargvalues(fr)
+
+    # we check the first parameter for the frame function is
+    # named 'self'
+    if (
+        len(args)
+        and
+        # TODO: other cases for `@classmethod` etc..?)
+        args[0] == 'self'
+    ):
+        # in that case, 'self' will be referenced in value_dict
+        instance: object = value_dict.get('self')
+        if instance:
+          # return its class
+          return getattr(
+              instance,
+              '__class__',
+              None,
+          )
+
+    # return None otherwise
+    return None
+
+
+def func_ref_from_frame(
+    frame: FrameType,
+) -> Callable:
+    func_name: str = frame.f_code.co_name
+    try:
+        return frame.f_globals[func_name]
+    except KeyError:
+        cls: Type|None = get_class_from_frame(frame)
+        if cls:
+            return getattr(
+                cls,
+                func_name,
+            )
+
+
+# TODO: move all this into new `.devx._code`!
+# -[ ] prolly create a `@runtime_api` dec?
+# -[ ] ^- make it capture and/or accept buncha optional
+#     meta-data like a fancier version of `@pdbp.hideframe`.
+#
+class CallerInfo(pretty_struct.Struct):
+    rt_fi: inspect.FrameInfo
+    call_frame: FrameType
+
+    @property
+    def api_func_ref(self) -> Callable|None:
+        return func_ref_from_frame(self.rt_fi.frame)
+
+    @property
+    def api_nsp(self) -> NamespacePath|None:
+        func: FunctionType = self.api_func_ref
+        if func:
+            return NamespacePath.from_ref(func)
+
+        return '<unknown>'
+
+    @property
+    def caller_func_ref(self) -> Callable|None:
+        return func_ref_from_frame(self.call_frame)
+
+    @property
+    def caller_nsp(self) -> NamespacePath|None:
+        func: FunctionType = self.caller_func_ref
+        if func:
+            return NamespacePath.from_ref(func)
+
+        return '<unknown>'
+
+
+def find_caller_info(
+    dunder_var: str = '__runtimeframe__',
+    iframes:int = 1,
+    check_frame_depth: bool = True,
+
+) -> CallerInfo|None:
+    '''
+    Scan up the callstack for a frame with a `dunder_var: str` variable
+    and return the `iframes` frames above it.
+
+    By default we scan for a `__runtimeframe__` scope var which
+    denotes a `tractor` API above which (one frame up) is "user
+    app code" which "called into" the `tractor` method or func.
+
+    TODO: ex with `Portal.open_context()`
+
+    '''
+    # TODO: use this instead?
+    # https://docs.python.org/3/library/inspect.html#inspect.getouterframes
+    frames: list[inspect.FrameInfo] = inspect.stack()
+    for fi in frames:
+        assert (
+            fi.function
+            ==
+            fi.frame.f_code.co_name
+        )
+        this_frame: FrameType = fi.frame
+        dunder_val: int|None = this_frame.f_locals.get(dunder_var)
+        if dunder_val:
+            go_up_iframes: int = (
+                dunder_val  # could be 0 or `True` i guess?
+                or
+                iframes
+            )
+            rt_frame: FrameType = fi.frame
+            call_frame = rt_frame
+            for i in range(go_up_iframes):
+                call_frame = call_frame.f_back
+
+            return CallerInfo(
+                rt_fi=fi,
+                call_frame=call_frame,
+            )
+
+    return None

tractor/devx/_frame_stack.py

@@ -1,380 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-'''
-Tools for code-object annotation, introspection and mutation
-as it pertains to improving the grok-ability of our runtime!
-
-'''
-from __future__ import annotations
-from contextlib import (
-    _GeneratorContextManager,
-    _AsyncGeneratorContextManager,
-)
-from functools import partial
-import inspect
-import textwrap
-from types import (
-    FrameType,
-    FunctionType,
-    MethodType,
-    CodeType,
-)
-from typing import (
-    Any,
-    Callable,
-    Type,
-)
-
-import pdbp
-from tractor.log import get_logger
-import trio
-from tractor.msg import (
-    pretty_struct,
-    NamespacePath,
-)
-import wrapt
-
-
-log = get_logger(__name__)
-
-# TODO: yeah, i don't love this and we should prolly just
-# write a decorator that actually keeps a stupid ref to the func
-# obj..
-def get_class_from_frame(fr: FrameType) -> (
-    FunctionType
-    |MethodType
-):
-    '''
-    Attempt to get the function (or method) reference
-    from a given `FrameType`.
-
-    Verbatim from an SO:
-    https://stackoverflow.com/a/2220759
-
-    '''
-    args, _, _, value_dict = inspect.getargvalues(fr)
-
-    # we check the first parameter for the frame function is
-    # named 'self'
-    if (
-        len(args)
-        and
-        # TODO: other cases for `@classmethod` etc..?)
-        args[0] == 'self'
-    ):
-        # in that case, 'self' will be referenced in value_dict
-        instance: object = value_dict.get('self')
-        if instance:
-          # return its class
-          return getattr(
-              instance,
-              '__class__',
-              None,
-          )
-
-    # return None otherwise
-    return None
-
-
-def get_ns_and_func_from_frame(
-    frame: FrameType,
-) -> Callable:
-    '''
-    Return the corresponding function object reference from
-    a `FrameType`, and return it and it's parent namespace `dict`.
-
-    '''
-    ns: dict[str, Any]
-
-    # for a method, go up a frame and lookup the name in locals()
-    if '.' in (qualname := frame.f_code.co_qualname):
-        cls_name, _, func_name = qualname.partition('.')
-        ns = frame.f_back.f_locals[cls_name].__dict__
-
-    else:
-        func_name: str = frame.f_code.co_name
-        ns = frame.f_globals
-
-    return (
-        ns,
-        ns[func_name],
-    )
-
-
-def func_ref_from_frame(
-    frame: FrameType,
-) -> Callable:
-    func_name: str = frame.f_code.co_name
-    try:
-        return frame.f_globals[func_name]
-    except KeyError:
-        cls: Type|None = get_class_from_frame(frame)
-        if cls:
-            return getattr(
-                cls,
-                func_name,
-            )
-
-
-class CallerInfo(pretty_struct.Struct):
-    # https://docs.python.org/dev/reference/datamodel.html#frame-objects
-    # https://docs.python.org/dev/library/inspect.html#the-interpreter-stack
-    _api_frame: FrameType
-
-    @property
-    def api_frame(self) -> FrameType:
-        try:
-            self._api_frame.clear()
-        except RuntimeError:
-            # log.warning(
-            print(
-                f'Frame {self._api_frame} for {self.api_func} is still active!'
-            )
-
-        return self._api_frame
-
-    _api_func: Callable
-
-    @property
-    def api_func(self) -> Callable:
-        return self._api_func
-
-    _caller_frames_up: int|None = 1
-    _caller_frame: FrameType|None = None  # cached after first stack scan
-
-    @property
-    def api_nsp(self) -> NamespacePath|None:
-        func: FunctionType = self.api_func
-        if func:
-            return NamespacePath.from_ref(func)
-
-        return '<unknown>'
-
-    @property
-    def caller_frame(self) -> FrameType:
-
-        # if not already cached, scan up stack explicitly by
-        # configured count.
-        if not self._caller_frame:
-            if self._caller_frames_up:
-                for _ in range(self._caller_frames_up):
-                    caller_frame: FrameType|None = self.api_frame.f_back
-
-                if not caller_frame:
-                    raise ValueError(
-                        'No frame exists {self._caller_frames_up} up from\n'
-                        f'{self.api_frame} @ {self.api_nsp}\n'
-                    )
-
-            self._caller_frame = caller_frame
-
-        return self._caller_frame
-
-    @property
-    def caller_nsp(self) -> NamespacePath|None:
-        func: FunctionType = self.api_func
-        if func:
-            return NamespacePath.from_ref(func)
-
-        return '<unknown>'
-
-
-def find_caller_info(
-    dunder_var: str = '__runtimeframe__',
-    iframes:int = 1,
-    check_frame_depth: bool = True,
-
-) -> CallerInfo|None:
-    '''
-    Scan up the callstack for a frame with a `dunder_var: str` variable
-    and return the `iframes` frames above it.
-
-    By default we scan for a `__runtimeframe__` scope var which
-    denotes a `tractor` API above which (one frame up) is "user
-    app code" which "called into" the `tractor` method or func.
-
-    TODO: ex with `Portal.open_context()`
-
-    '''
-    # TODO: use this instead?
-    # https://docs.python.org/3/library/inspect.html#inspect.getouterframes
-    frames: list[inspect.FrameInfo] = inspect.stack()
-    for fi in frames:
-        assert (
-            fi.function
-            ==
-            fi.frame.f_code.co_name
-        )
-        this_frame: FrameType = fi.frame
-        dunder_val: int|None = this_frame.f_locals.get(dunder_var)
-        if dunder_val:
-            go_up_iframes: int = (
-                dunder_val  # could be 0 or `True` i guess?
-                or
-                iframes
-            )
-            rt_frame: FrameType = fi.frame
-            call_frame = rt_frame
-            for i in range(go_up_iframes):
-                call_frame = call_frame.f_back
-
-            return CallerInfo(
-                _api_frame=rt_frame,
-                _api_func=func_ref_from_frame(rt_frame),
-                _caller_frames_up=go_up_iframes,
-            )
-
-    return None
-
-
-_frame2callerinfo_cache: dict[FrameType, CallerInfo] = {}
-
-
-# TODO: -[x] move all this into new `.devx._frame_stack`!
-# -[ ] consider rename to _callstack?
-# -[ ] prolly create a `@runtime_api` dec?
-#   |_ @api_frame seems better?
-# -[ ] ^- make it capture and/or accept buncha optional
-#     meta-data like a fancier version of `@pdbp.hideframe`.
-#
-def api_frame(
-    wrapped: Callable|None = None,
-    *,
-    caller_frames_up: int = 1,
-
-) -> Callable:
-
-    # handle the decorator called WITHOUT () case,
-    # i.e. just @api_frame, NOT @api_frame(extra=<blah>)
-    if wrapped is None:
-        return partial(
-            api_frame,
-            caller_frames_up=caller_frames_up,
-        )
-
-    @wrapt.decorator
-    async def wrapper(
-        wrapped: Callable,
-        instance: object,
-        args: tuple,
-        kwargs: dict,
-    ):
-        # maybe cache the API frame for this call
-        global _frame2callerinfo_cache
-        this_frame: FrameType = inspect.currentframe()
-        api_frame: FrameType = this_frame.f_back
-
-        if not _frame2callerinfo_cache.get(api_frame):
-            _frame2callerinfo_cache[api_frame] = CallerInfo(
-                _api_frame=api_frame,
-                _api_func=wrapped,
-                _caller_frames_up=caller_frames_up,
-            )
-
-        return wrapped(*args, **kwargs)
-
-    # annotate the function as a "api function", meaning it is
-    # a function for which the function above it in the call stack should be
-    # non-`tractor` code aka "user code".
-    #
-    # in the global frame cache for easy lookup from a given
-    # func-instance
-    wrapped._call_infos: dict[FrameType, CallerInfo] = _frame2callerinfo_cache
-    wrapped.__api_func__: bool = True
-    return wrapper(wrapped)
-
-
-# TODO: something like this instead of the adhoc frame-unhiding
-# blocks all over the runtime!! XD
-# -[ ] ideally we can expect a certain error (set) and if something
-#     else is raised then all frames below the wrapped one will be
-#     un-hidden via `__tracebackhide__: bool = False`.
-# |_ might need to dynamically mutate the code objs like
-#    `pdbp.hideframe()` does?
-# -[ ] use this as a `@acm` decorator as introed in 3.10?
-# @acm
-# async def unhide_frame_when_not(
-#     error_set: set[BaseException],
-# ) -> TracebackType:
-#     ...
-
-
-def hide_runtime_frames() -> dict[FunctionType, CodeType]:
-    '''
-    Hide call-stack frames for various std-lib and `trio`-API primitives
-    such that the tracebacks presented from our runtime are as minimized
-    as possible, particularly from inside a `PdbREPL`.
-
-    '''
-    # XXX HACKZONE XXX
-    #  hide exit stack frames on nurseries and cancel-scopes!
-    # |_ so avoid seeing it when the `pdbp` REPL is first engaged from
-    #    inside a `trio.open_nursery()` scope (with no line after it
-    #    in before the block end??).
-    #
-    # TODO: FINALLY got this workin originally with
-    #  `@pdbp.hideframe` around the `wrapper()` def embedded inside
-    #  `_ki_protection_decoratior()`.. which is in the module:
-    #  /home/goodboy/.virtualenvs/tractor311/lib/python3.11/site-packages/trio/_core/_ki.py
-    #
-    # -[ ] make an issue and patch for `trio` core? maybe linked
-    #    to the long outstanding `pdb` one below?
-    #   |_ it's funny that there's frame hiding throughout `._run.py`
-    #      but not where it matters on the below exit funcs..
-    #
-    # -[ ] provide a patchset for the lonstanding
-    #   |_ https://github.com/python-trio/trio/issues/1155
-    #
-    # -[ ] make a linked issue to ^ and propose allowing all the
-    #     `._core._run` code to have their `__tracebackhide__` value
-    #     configurable by a `RunVar` to allow getting scheduler frames
-    #     if desired through configuration?
-    #
-    # -[ ] maybe dig into the core `pdb` issue why the extra frame is shown
-    #      at all?
-    #
-    funcs: list[FunctionType] = [
-        trio._core._run.NurseryManager.__aexit__,
-        trio._core._run.CancelScope.__exit__,
-         _GeneratorContextManager.__exit__,
-         _AsyncGeneratorContextManager.__aexit__,
-         _AsyncGeneratorContextManager.__aenter__,
-         trio.Event.wait,
-    ]
-    func_list_str: str = textwrap.indent(
-        "\n".join(f.__qualname__ for f in funcs),
-        prefix=' |_ ',
-    )
-    log.devx(
-        'Hiding the following runtime frames by default:\n'
-        f'{func_list_str}\n'
-    )
-
-    codes: dict[FunctionType, CodeType] = {}
-    for ref in funcs:
-        # stash a pre-modified version of each ref's code-obj
-        # so it can be reverted later if needed.
-        codes[ref] = ref.__code__
-        pdbp.hideframe(ref)
-    #
-    # pdbp.hideframe(trio._core._run.NurseryManager.__aexit__)
-    # pdbp.hideframe(trio._core._run.CancelScope.__exit__)
-    # pdbp.hideframe(_GeneratorContextManager.__exit__)
-    # pdbp.hideframe(_AsyncGeneratorContextManager.__aexit__)
-    # pdbp.hideframe(_AsyncGeneratorContextManager.__aenter__)
-    # pdbp.hideframe(trio.Event.wait)
-    return codes

tractor/devx/_stackscope.py

@@ -24,32 +24,19 @@ disjoint, parallel executing tasks in separate actors.
 
 '''
 from __future__ import annotations
-# from functools import partial
-from threading import (
-    current_thread,
-    Thread,
-    RLock,
-)
 import multiprocessing as mp
 from signal import (
     signal,
-    getsignal,
     SIGUSR1,
-    SIGINT,
-)
-# import traceback
-from types import ModuleType
-from typing import (
-    Callable,
-    TYPE_CHECKING,
 )
+import traceback
+from typing import TYPE_CHECKING
 
 import trio
 from tractor import (
     _state,
     log as logmod,
 )
-from tractor.devx import debug
 
 log = logmod.get_logger(__name__)
 
@@ -64,68 +51,26 @@ if TYPE_CHECKING:
 
 @trio.lowlevel.disable_ki_protection
 def dump_task_tree() -> None:
-    '''
-    Do a classic `stackscope.extract()` task-tree dump to console at
-    `.devx()` level.
-
-    '''
     import stackscope
+    from tractor.log import get_console_log
+
     tree_str: str = str(
         stackscope.extract(
             trio.lowlevel.current_root_task(),
             recurse_child_tasks=True
         )
     )
+    log = get_console_log(
+        name=__name__,
+        level='cancel',
+    )
     actor: Actor = _state.current_actor()
-    thr: Thread = current_thread()
-    current_sigint_handler: Callable = getsignal(SIGINT)
-    if (
-        current_sigint_handler
-        is not
-        debug.DebugStatus._trio_handler
-    ):
-        sigint_handler_report: str = (
-            'The default `trio` SIGINT handler was replaced?!'
-        )
-    else:
-        sigint_handler_report: str = (
-            'The default `trio` SIGINT handler is in use?!'
-        )
-
-    # sclang symbology
-    # |_<object>
-    # |_(Task/Thread/Process/Actor
-    # |_{Supervisor/Scope
-    # |_[Storage/Memory/IPC-Stream/Data-Struct
-
     log.devx(
         f'Dumping `stackscope` tree for actor\n'
-        f'(>: {actor.uid!r}\n'
-        f' |_{mp.current_process()}\n'
-        f'   |_{thr}\n'
-        f'     |_{actor}\n'
-        f'\n'
-        f'{sigint_handler_report}\n'
-        f'signal.getsignal(SIGINT) -> {current_sigint_handler!r}\n'
-        # f'\n'
-        # start-of-trace-tree delimiter (mostly for testing)
-        # f'------ {actor.uid!r} ------\n'
-        f'\n'
-        f'------ start-of-{actor.uid!r} ------\n'
-        f'|\n'
-        f'{tree_str}'
-        # end-of-trace-tree delimiter (mostly for testing)
-        f'|\n'
-        f'|_____ end-of-{actor.uid!r} ______\n'
+        f'{actor.name}: {actor}\n'
+        f' |_{mp.current_process()}\n\n'
+        f'{tree_str}\n'
     )
-    # TODO: can remove this right?
-    # -[ ] was original code from author
-    #
-    # print(
-    #     'DUMPING FROM PRINT\n'
-    #     +
-    #     content
-    # )
     # import logging
     # try:
     #     with open("/dev/tty", "w") as tty:
@@ -135,131 +80,58 @@ def dump_task_tree() -> None:
     #         "task_tree"
     #     ).exception("Error printing task tree")
 
-_handler_lock = RLock()
-_tree_dumped: bool = False
 
-
-def dump_tree_on_sig(
+def signal_handler(
     sig: int,
     frame: object,
 
     relay_to_subs: bool = True,
 
 ) -> None:
-    global _tree_dumped, _handler_lock
-    with _handler_lock:
-        # if _tree_dumped:
-        #     log.warning(
-        #         'Already dumped for this actor...??'
-        #     )
-        #     return
-
-        _tree_dumped = True
-
-        # actor: Actor = _state.current_actor()
-        log.devx(
-            'Trying to dump `stackscope` tree..\n'
-        )
-        try:
-            dump_task_tree()
-            # await actor._service_n.start_soon(
-            #     partial(
-            #         trio.to_thread.run_sync,
-            #         dump_task_tree,
-            #     )
-            # )
-            # trio.lowlevel.current_trio_token().run_sync_soon(
-            #     dump_task_tree
-            # )
-
-        except RuntimeError:
-            log.exception(
-                'Failed to dump `stackscope` tree..\n'
-            )
-            # not in async context -- print a normal traceback
-            # traceback.print_stack()
-            raise
-
-        except BaseException:
-            log.exception(
-                'Failed to dump `stackscope` tree..\n'
-            )
-            raise
-
-        # log.devx(
-        #     'Supposedly we dumped just fine..?'
-        # )
+    try:
+        trio.lowlevel.current_trio_token(
+        ).run_sync_soon(dump_task_tree)
+    except RuntimeError:
+        # not in async context -- print a normal traceback
+        traceback.print_stack()
 
     if not relay_to_subs:
         return
 
     an: ActorNursery
     for an in _state.current_actor()._actoruid2nursery.values():
+
         subproc: ProcessType
         subactor: Actor
         for subactor, subproc, _ in an._children.values():
-            log.warning(
+            log.devx(
                 f'Relaying `SIGUSR1`[{sig}] to sub-actor\n'
                 f'{subactor}\n'
                 f' |_{subproc}\n'
             )
 
-            # bc of course stdlib can't have a std API.. XD
-            match subproc:
-                case trio.Process():
-                    subproc.send_signal(sig)
+            if isinstance(subproc, trio.Process):
+                subproc.send_signal(sig)
 
-                case mp.Process():
-                    subproc._send_signal(sig)
+            elif isinstance(subproc, mp.Process):
+                subproc._send_signal(sig)
 
 
 def enable_stack_on_sig(
-    sig: int = SIGUSR1,
-) -> ModuleType:
+    sig: int = SIGUSR1
+) -> None:
     '''
     Enable `stackscope` tracing on reception of a signal; by
     default this is SIGUSR1.
 
-    HOT TIP: a task/ctx-tree dump can be triggered from a shell with
-    fancy cmds.
-
-    For ex. from `bash` using `pgrep` and cmd-sustitution
-    (https://www.gnu.org/software/bash/manual/bash.html#Command-Substitution)
-    you could use:
-
-    >> kill -SIGUSR1 $(pgrep -f <part-of-cmd: str>)
-
-    OR without a sub-shell,
-
-    >> pkill --signal SIGUSR1 -f <part-of-cmd: str>
-
     '''
-    try:
-        import stackscope
-    except ImportError:
-        log.error(
-            '`stackscope` not installed for use in debug mode!\n'
-            '`Ignoring {enable_stack_on_sig!r} call!\n'
-        )
-        return None
-
-    handler: Callable|int = getsignal(sig)
-    if handler is dump_tree_on_sig:
-        log.devx(
-            'A `SIGUSR1` handler already exists?\n'
-            f'|_ {handler!r}\n'
-        )
-        return
-
     signal(
         sig,
-        dump_tree_on_sig,
+        signal_handler,
     )
-    log.devx(
-        f'Enabling trace-trees on `SIGUSR1` '
-        f'since `stackscope` is installed @ \n'
-        f'{stackscope!r}\n\n'
-        f'With `SIGUSR1` handler\n'
-        f'|_{dump_tree_on_sig}\n'
-    )
-    return stackscope
+    # NOTE: not the above can be triggered from
+    # a (xonsh) shell using:
+    # kill -SIGUSR1 @$(pgrep -f '<cmd>')
+    #
+    # for example if you were looking to trace a `pytest` run
+    # kill -SIGUSR1 @$(pgrep -f 'pytest')

tractor/devx/debug/__init__.py

@@ -1,100 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or
-# modify it under the terms of the GNU Affero General Public License
-# as published by the Free Software Foundation, either version 3 of
-# the License, or (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful, but
-# WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public
-# License along with this program.  If not, see
-# <https://www.gnu.org/licenses/>.
-
-'''
-Multi-actor debugging for da peeps!
-
-'''
-from __future__ import annotations
-from tractor.log import get_logger
-from ._repl import (
-    PdbREPL as PdbREPL,
-    mk_pdb as mk_pdb,
-    TractorConfig as TractorConfig,
-)
-from ._tty_lock import (
-    DebugStatus as DebugStatus,
-    DebugStateError as DebugStateError,
-)
-from ._trace import (
-    Lock as Lock,
-    _pause_msg as _pause_msg,
-    _repl_fail_msg as _repl_fail_msg,
-    _set_trace as _set_trace,
-    _sync_pause_from_builtin as _sync_pause_from_builtin,
-    breakpoint as breakpoint,
-    maybe_init_greenback as maybe_init_greenback,
-    maybe_import_greenback as maybe_import_greenback,
-    pause as pause,
-    pause_from_sync as pause_from_sync,
-)
-from ._post_mortem import (
-    BoxedMaybeException as BoxedMaybeException,
-    maybe_open_crash_handler as maybe_open_crash_handler,
-    open_crash_handler as open_crash_handler,
-    post_mortem as post_mortem,
-    _crash_msg as _crash_msg,
-    _maybe_enter_pm as _maybe_enter_pm,
-)
-from ._sync import (
-    maybe_wait_for_debugger as maybe_wait_for_debugger,
-    acquire_debug_lock as acquire_debug_lock,
-)
-from ._sigint import (
-    sigint_shield as sigint_shield,
-    _ctlc_ignore_header as _ctlc_ignore_header
-)
-
-log = get_logger(__name__)
-
-# ----------------
-# XXX PKG TODO XXX
-# ----------------
-# refine the internal impl and APIs!
-#
-# -[ ] rework `._pause()` and it's branch-cases for root vs.
-#     subactor:
-#  -[ ] `._pause_from_root()` + `_pause_from_subactor()`?
-#  -[ ]  do the de-factor based on bg-thread usage in
-#    `.pause_from_sync()` & `_pause_from_bg_root_thread()`.
-#  -[ ] drop `debug_func == None` case which is confusing af..
-#  -[ ]  factor out `_enter_repl_sync()` into a util func for calling
-#    the `_set_trace()` / `_post_mortem()` APIs?
-#
-# -[ ] figure out if we need `acquire_debug_lock()` and/or re-implement
-#    it as part of the `.pause_from_sync()` rework per above?
-#
-# -[ ] pair the `._pause_from_subactor()` impl with a "debug nursery"
-#   that's dynamically allocated inside the `._rpc` task thus
-#   avoiding the `._service_n.start()` usage for the IPC request?
-#  -[ ] see the TODO inside `._rpc._errors_relayed_via_ipc()`
-#
-# -[ ] impl a `open_debug_request()` which encaps all
-#   `request_root_stdio_lock()` task scheduling deats
-#   + `DebugStatus` state mgmt; which should prolly be re-branded as
-#   a `DebugRequest` type anyway AND with suppoort for bg-thread
-#   (from root actor) usage?
-#
-# -[ ] handle the `xonsh` case for bg-root-threads in the SIGINT
-#     handler!
-#   -[ ] do we need to do the same for subactors?
-#   -[ ] make the failing tests finally pass XD
-#
-# -[ ] simplify `maybe_wait_for_debugger()` to be a root-task only
-#     API?
-#   -[ ] currently it's implemented as that so might as well make it
-#     formal?

tractor/devx/debug/_post_mortem.py

@@ -1,412 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or
-# modify it under the terms of the GNU Affero General Public License
-# as published by the Free Software Foundation, either version 3 of
-# the License, or (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful, but
-# WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public
-# License along with this program.  If not, see
-# <https://www.gnu.org/licenses/>.
-
-'''
-Post-mortem debugging APIs and surrounding machinery for both
-sync and async contexts.
-
-Generally we maintain the same semantics a `pdb.post.mortem()` but
-with actor-tree-wide sync/cooperation around any (sub)actor's use of
-the root's TTY.
-
-'''
-from __future__ import annotations
-import bdb
-from contextlib import (
-    AbstractContextManager,
-    contextmanager as cm,
-    nullcontext,
-)
-from functools import (
-    partial,
-)
-import inspect
-import sys
-import traceback
-from typing import (
-    Callable,
-    Sequence,
-    Type,
-    TYPE_CHECKING,
-)
-from types import (
-    TracebackType,
-    FrameType,
-)
-
-from msgspec import Struct
-import trio
-from tractor._exceptions import (
-    NoRuntime,
-)
-from tractor import _state
-from tractor._state import (
-    current_actor,
-    debug_mode,
-)
-from tractor.log import get_logger
-from tractor._exceptions import (
-    is_multi_cancelled,
-)
-from ._trace import (
-    _pause,
-)
-from ._tty_lock import (
-    DebugStatus,
-)
-from ._repl import (
-    PdbREPL,
-    mk_pdb,
-    TractorConfig as TractorConfig,
-)
-
-if TYPE_CHECKING:
-    from trio.lowlevel import Task
-    from tractor._runtime import (
-        Actor,
-    )
-
-_crash_msg: str = (
-    'Opening a pdb REPL in crashed actor'
-)
-
-log = get_logger(__package__)
-
-
-class BoxedMaybeException(Struct):
-    '''
-    Box a maybe-exception for post-crash introspection usage
-    from the body of a `open_crash_handler()` scope.
-
-    '''
-    value: BaseException|None = None
-
-    # handler can suppress crashes dynamically
-    raise_on_exit: bool|Sequence[Type[BaseException]] = True
-
-    def pformat(self) -> str:
-        '''
-        Repr the boxed `.value` error in more-than-string
-        repr form.
-
-        '''
-        if not self.value:
-            return f'<{type(self).__name__}( .value=None )>'
-
-        return (
-            f'<{type(self.value).__name__}(\n'
-            f' |_.value = {self.value}\n'
-            f')>\n'
-        )
-
-    __repr__ = pformat
-
-
-def _post_mortem(
-    repl: PdbREPL,  # normally passed by `_pause()`
-
-    # XXX all `partial`-ed in by `post_mortem()` below!
-    tb: TracebackType,
-    api_frame: FrameType,
-
-    shield: bool = False,
-    hide_tb: bool = True,
-
-    # maybe pre/post REPL entry
-    repl_fixture: (
-        AbstractContextManager[bool]
-        |None
-    ) = None,
-
-    boxed_maybe_exc: BoxedMaybeException|None = None,
-
-) -> None:
-    '''
-    Enter the ``pdbpp`` port mortem entrypoint using our custom
-    debugger instance.
-
-    '''
-    __tracebackhide__: bool = hide_tb
-
-    # maybe enter any user fixture
-    enter_repl: bool = DebugStatus.maybe_enter_repl_fixture(
-        repl=repl,
-        repl_fixture=repl_fixture,
-        boxed_maybe_exc=boxed_maybe_exc,
-    )
-    try:
-        if not enter_repl:
-            # XXX, trigger `.release()` below immediately!
-            return
-        try:
-            actor: Actor = current_actor()
-            actor_repr: str = str(actor.uid)
-            # ^TODO, instead a nice runtime-info + maddr + uid?
-            # -[ ] impl a `Actor.__repr()__`??
-            #  |_ <task>:<thread> @ <actor>
-
-        except NoRuntime:
-            actor_repr: str = '<no-actor-runtime?>'
-
-        try:
-            task_repr: Task = trio.lowlevel.current_task()
-        except RuntimeError:
-            task_repr: str = '<unknown-Task>'
-
-        # TODO: print the actor supervion tree up to the root
-        # here! Bo
-        log.pdb(
-            f'{_crash_msg}\n'
-            f'x>(\n'
-            f' |_ {task_repr} @ {actor_repr}\n'
-
-        )
-
-        # XXX NOTE(s) on `pdbp.xpm()` version..
-        #
-        # - seems to lose the up-stack tb-info?
-        # - currently we're (only) replacing this from `pdbp.xpm()`
-        #   to add the `end=''` to the print XD
-        #
-        print(traceback.format_exc(), end='')
-        caller_frame: FrameType = api_frame.f_back
-
-        # NOTE, see the impl details of these in the lib to
-        # understand usage:
-        # - `pdbp.post_mortem()`
-        # - `pdbp.xps()`
-        # - `bdb.interaction()`
-        repl.reset()
-        repl.interaction(
-            frame=caller_frame,
-            # frame=None,
-            traceback=tb,
-        )
-    finally:
-        # XXX NOTE XXX: this is abs required to avoid hangs!
-        #
-        # Since we presume the post-mortem was enaged to
-        # a task-ending error, we MUST release the local REPL request
-        # so that not other local task nor the root remains blocked!
-        DebugStatus.release()
-
-
-async def post_mortem(
-    *,
-    tb: TracebackType|None = None,
-    api_frame: FrameType|None = None,
-    hide_tb: bool = False,
-
-    # TODO: support shield here just like in `pause()`?
-    # shield: bool = False,
-
-    **_pause_kwargs,
-
-) -> None:
-    '''
-    Our builtin async equivalient of `pdb.post_mortem()` which can be
-    used inside exception handlers.
-
-    It's also used for the crash handler when `debug_mode == True` ;)
-
-    '''
-    __tracebackhide__: bool = hide_tb
-
-    tb: TracebackType = tb or sys.exc_info()[2]
-
-    # TODO: do upward stack scan for highest @api_frame and
-    # use its parent frame as the expected user-app code
-    # interact point.
-    api_frame: FrameType = api_frame or inspect.currentframe()
-
-    # TODO, move to submod `._pausing` or ._api? _trace
-    await _pause(
-        debug_func=partial(
-            _post_mortem,
-            api_frame=api_frame,
-            tb=tb,
-        ),
-        hide_tb=hide_tb,
-        **_pause_kwargs
-    )
-
-
-async def _maybe_enter_pm(
-    err: BaseException,
-    *,
-    tb: TracebackType|None = None,
-    api_frame: FrameType|None = None,
-    hide_tb: bool = False,
-
-    # only enter debugger REPL when returns `True`
-    debug_filter: Callable[
-        [BaseException|BaseExceptionGroup],
-        bool,
-    ] = lambda err: not is_multi_cancelled(err),
-    **_pause_kws,
-):
-    if (
-        debug_mode()
-
-        # NOTE: don't enter debug mode recursively after quitting pdb
-        # Iow, don't re-enter the repl if the `quit` command was issued
-        # by the user.
-        and not isinstance(err, bdb.BdbQuit)
-
-        # XXX: if the error is the likely result of runtime-wide
-        # cancellation, we don't want to enter the debugger since
-        # there's races between when the parent actor has killed all
-        # comms and when the child tries to contact said parent to
-        # acquire the tty lock.
-
-        # Really we just want to mostly avoid catching KBIs here so there
-        # might be a simpler check we can do?
-        and
-        debug_filter(err)
-    ):
-        api_frame: FrameType = api_frame or inspect.currentframe()
-        tb: TracebackType = tb or sys.exc_info()[2]
-        await post_mortem(
-            api_frame=api_frame,
-            tb=tb,
-            **_pause_kws,
-        )
-        return True
-
-    else:
-        return False
-
-
-# TODO: better naming and what additionals?
-# - [ ] optional runtime plugging?
-# - [ ] detection for sync vs. async code?
-# - [ ] specialized REPL entry when in distributed mode?
-# -[x] hide tb by def
-# - [x] allow ignoring kbi Bo
-@cm
-def open_crash_handler(
-    catch: set[BaseException] = {
-        BaseException,
-    },
-    ignore: set[BaseException] = {
-        KeyboardInterrupt,
-        trio.Cancelled,
-    },
-    hide_tb: bool = True,
-
-    repl_fixture: (
-        AbstractContextManager[bool]  # pre/post REPL entry
-        |None
-    ) = None,
-    raise_on_exit: bool|Sequence[Type[BaseException]] = True,
-):
-    '''
-    Generic "post mortem" crash handler using `pdbp` REPL debugger.
-
-    We expose this as a CLI framework addon to both `click` and
-    `typer` users so they can quickly wrap cmd endpoints which get
-    automatically wrapped to use the runtime's `debug_mode: bool`
-    AND `pdbp.pm()` around any code that is PRE-runtime entry
-    - any sync code which runs BEFORE the main call to
-      `trio.run()`.
-
-    '''
-    __tracebackhide__: bool = hide_tb
-
-    # TODO, yield a `outcome.Error`-like boxed type?
-    # -[~] use `outcome.Value/Error` X-> frozen!
-    # -[x] write our own..?
-    # -[ ] consider just wtv is used by `pytest.raises()`?
-    #
-    boxed_maybe_exc = BoxedMaybeException(
-        raise_on_exit=raise_on_exit,
-    )
-    err: BaseException
-    try:
-        yield boxed_maybe_exc
-    except tuple(catch) as err:
-        boxed_maybe_exc.value = err
-        if (
-            type(err) not in ignore
-            and
-            not is_multi_cancelled(
-                err,
-                ignore_nested=ignore
-            )
-        ):
-            try:
-                # use our re-impl-ed version of `pdbp.xpm()`
-                _post_mortem(
-                    repl=mk_pdb(),
-                    tb=sys.exc_info()[2],
-                    api_frame=inspect.currentframe().f_back,
-                    hide_tb=hide_tb,
-
-                    repl_fixture=repl_fixture,
-                    boxed_maybe_exc=boxed_maybe_exc,
-                )
-            except bdb.BdbQuit:
-                __tracebackhide__: bool = False
-                raise err
-
-        if (
-            raise_on_exit is True
-            or (
-                raise_on_exit is not False
-                and (
-                    set(raise_on_exit)
-                    and
-                    type(err) in raise_on_exit
-                )
-            )
-            and
-            boxed_maybe_exc.raise_on_exit == raise_on_exit
-        ):
-            raise err
-
-
-@cm
-def maybe_open_crash_handler(
-    pdb: bool|None = None,
-    hide_tb: bool = True,
-
-    **kwargs,
-):
-    '''
-    Same as `open_crash_handler()` but with bool input flag
-    to allow conditional handling.
-
-    Normally this is used with CLI endpoints such that if the --pdb
-    flag is passed the pdb REPL is engaed on any crashes B)
-
-    '''
-    __tracebackhide__: bool = hide_tb
-
-    if pdb is None:
-        pdb: bool = _state.is_debug_mode()
-
-    rtctx = nullcontext(
-        enter_result=BoxedMaybeException()
-    )
-    if pdb:
-        rtctx = open_crash_handler(
-            hide_tb=hide_tb,
-            **kwargs,
-        )
-
-    with rtctx as boxed_maybe_exc:
-        yield boxed_maybe_exc

tractor/devx/debug/_repl.py

@@ -1,207 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or
-# modify it under the terms of the GNU Affero General Public License
-# as published by the Free Software Foundation, either version 3 of
-# the License, or (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful, but
-# WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public
-# License along with this program.  If not, see
-# <https://www.gnu.org/licenses/>.
-
-'''
-`pdpp.Pdb` extentions/customization and other delegate usage.
-
-'''
-from functools import (
-    cached_property,
-)
-import os
-
-import pdbp
-from tractor._state import (
-    is_root_process,
-)
-
-from ._tty_lock import (
-    Lock,
-    DebugStatus,
-)
-
-
-class TractorConfig(pdbp.DefaultConfig):
-    '''
-    Custom `pdbp` config which tries to use the best tradeoff
-    between pretty and minimal.
-
-    '''
-    use_pygments: bool = True
-    sticky_by_default: bool = False
-    enable_hidden_frames: bool = True
-
-    # much thanks @mdmintz for the hot tip!
-    # fixes line spacing issue when resizing terminal B)
-    truncate_long_lines: bool = False
-
-    # ------ - ------
-    # our own custom config vars mostly
-    # for syncing with the actor tree's singleton
-    # TTY `Lock`.
-
-
-class PdbREPL(pdbp.Pdb):
-    '''
-    Add teardown hooks and local state describing any
-    ongoing TTY `Lock` request dialog.
-
-    '''
-    # override the pdbp config with our coolio one
-    # NOTE: this is only loaded when no `~/.pdbrc` exists
-    # so we should prolly pass it into the .__init__() instead?
-    # i dunno, see the `DefaultFactory` and `pdb.Pdb` impls.
-    DefaultConfig = TractorConfig
-
-    status = DebugStatus
-
-    # NOTE: see details in stdlib's `bdb.py`
-    # def user_exception(self, frame, exc_info):
-    #     '''
-    #     Called when we stop on an exception.
-    #     '''
-    #     log.warning(
-    #         'Exception during REPL sesh\n\n'
-    #         f'{frame}\n\n'
-    #         f'{exc_info}\n\n'
-    #     )
-
-    # NOTE: this actually hooks but i don't see anyway to detect
-    # if an error was caught.. this is why currently we just always
-    # call `DebugStatus.release` inside `_post_mortem()`.
-    # def preloop(self):
-    #     print('IN PRELOOP')
-    #     super().preloop()
-
-    # TODO: cleaner re-wrapping of all this?
-    # -[ ] figure out how to disallow recursive .set_trace() entry
-    #     since that'll cause deadlock for us.
-    # -[ ] maybe a `@cm` to call `super().<same_meth_name>()`?
-    # -[ ] look at hooking into the `pp` hook specially with our
-    #     own set of pretty-printers?
-    #    * `.pretty_struct.Struct.pformat()`
-    #    * `.pformat(MsgType.pld)`
-    #    * `.pformat(Error.tb_str)`?
-    #    * .. maybe more?
-    #
-    def set_continue(self):
-        try:
-            super().set_continue()
-        finally:
-            # NOTE: for subactors the stdio lock is released via the
-            # allocated RPC locker task, so for root we have to do it
-            # manually.
-            if (
-                is_root_process()
-                and
-                Lock._debug_lock.locked()
-                and
-                DebugStatus.is_main_trio_thread()
-            ):
-                # Lock.release(raise_on_thread=False)
-                Lock.release()
-
-            # XXX AFTER `Lock.release()` for root local repl usage
-            DebugStatus.release()
-
-    def set_quit(self):
-        try:
-            super().set_quit()
-        finally:
-            if (
-                is_root_process()
-                and
-                Lock._debug_lock.locked()
-                and
-                DebugStatus.is_main_trio_thread()
-            ):
-                # Lock.release(raise_on_thread=False)
-                Lock.release()
-
-            # XXX after `Lock.release()` for root local repl usage
-            DebugStatus.release()
-
-    # XXX NOTE: we only override this because apparently the stdlib pdb
-    # bois likes to touch the SIGINT handler as much as i like to touch
-    # my d$%&.
-    def _cmdloop(self):
-        self.cmdloop()
-
-    @cached_property
-    def shname(self) -> str | None:
-        '''
-        Attempt to return the login shell name with a special check for
-        the infamous `xonsh` since it seems to have some issues much
-        different from std shells when it comes to flushing the prompt?
-
-        '''
-        # SUPER HACKY and only really works if `xonsh` is not used
-        # before spawning further sub-shells..
-        shpath = os.getenv('SHELL', None)
-
-        if shpath:
-            if (
-                os.getenv('XONSH_LOGIN', default=False)
-                or 'xonsh' in shpath
-            ):
-                return 'xonsh'
-
-            return os.path.basename(shpath)
-
-        return None
-
-
-def mk_pdb() -> PdbREPL:
-    '''
-    Deliver a new `PdbREPL`: a multi-process safe `pdbp.Pdb`-variant
-    using the magic of `tractor`'s SC-safe IPC.
-
-    B)
-
-    Our `pdb.Pdb` subtype accomplishes multi-process safe debugging
-    by:
-
-    - mutexing access to the root process' std-streams (& thus parent
-      process TTY) via an IPC managed `Lock` singleton per
-      actor-process tree.
-
-    - temporarily overriding any subactor's SIGINT handler to shield
-      during live REPL sessions in sub-actors such that cancellation
-      is never (mistakenly) triggered by a ctrl-c and instead only by
-      explicit runtime API requests or after the
-      `pdb.Pdb.interaction()` call has returned.
-
-    FURTHER, the `pdbp.Pdb` instance is configured to be `trio`
-    "compatible" from a SIGINT handling perspective; we mask out
-    the default `pdb` handler and instead apply `trio`s default
-    which mostly addresses all issues described in:
-
-     - https://github.com/python-trio/trio/issues/1155
-
-    The instance returned from this factory should always be
-    preferred over the default `pdb[p].set_trace()` whenever using
-    a `pdb` REPL inside a `trio` based runtime.
-
-    '''
-    pdb = PdbREPL()
-
-    # XXX: These are the important flags mentioned in
-    # https://github.com/python-trio/trio/issues/1155
-    # which resolve the traceback spews to console.
-    pdb.allow_kbdint = True
-    pdb.nosigint = True
-    return pdb

tractor/devx/debug/_sigint.py

@@ -1,333 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or
-# modify it under the terms of the GNU Affero General Public License
-# as published by the Free Software Foundation, either version 3 of
-# the License, or (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful, but
-# WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public
-# License along with this program.  If not, see
-# <https://www.gnu.org/licenses/>.
-
-'''
-A custom SIGINT handler which mainly shields actor (task)
-cancellation during REPL interaction.
-
-'''
-from __future__ import annotations
-from typing import (
-    TYPE_CHECKING,
-)
-import trio
-from tractor.log import get_logger
-from tractor._state import (
-    current_actor,
-    is_root_process,
-)
-from ._repl import (
-    PdbREPL,
-)
-from ._tty_lock import (
-    any_connected_locker_child,
-    DebugStatus,
-    Lock,
-)
-
-if TYPE_CHECKING:
-    from tractor.ipc import (
-        Channel,
-    )
-    from tractor._runtime import (
-        Actor,
-    )
-
-log = get_logger(__name__)
-
-_ctlc_ignore_header: str = (
-    'Ignoring SIGINT while debug REPL in use'
-)
-
-
-def sigint_shield(
-    signum: int,
-    frame: 'frame',  # type: ignore # noqa
-    *args,
-
-) -> None:
-    '''
-    Specialized, debugger-aware SIGINT handler.
-
-    In childred we always ignore/shield for SIGINT to avoid
-    deadlocks since cancellation should always be managed by the
-    supervising parent actor. The root actor-proces is always
-    cancelled on ctrl-c.
-
-    '''
-    __tracebackhide__: bool = True
-    actor: Actor = current_actor()
-
-    def do_cancel():
-        # If we haven't tried to cancel the runtime then do that instead
-        # of raising a KBI (which may non-gracefully destroy
-        # a ``trio.run()``).
-        if not actor._cancel_called:
-            actor.cancel_soon()
-
-        # If the runtime is already cancelled it likely means the user
-        # hit ctrl-c again because teardown didn't fully take place in
-        # which case we do the "hard" raising of a local KBI.
-        else:
-            raise KeyboardInterrupt
-
-    # only set in the actor actually running the REPL
-    repl: PdbREPL|None = DebugStatus.repl
-
-    # TODO: maybe we should flatten out all these cases using
-    # a match/case?
-    #
-    # root actor branch that reports whether or not a child
-    # has locked debugger.
-    if is_root_process():
-        # log.warning(
-        log.devx(
-            'Handling SIGINT in root actor\n'
-            f'{Lock.repr()}'
-            f'{DebugStatus.repr()}\n'
-        )
-        # try to see if the supposed (sub)actor in debug still
-        # has an active connection to *this* actor, and if not
-        # it's likely they aren't using the TTY lock / debugger
-        # and we should propagate SIGINT normally.
-        any_connected: bool = any_connected_locker_child()
-
-        problem = (
-            f'root {actor.uid} handling SIGINT\n'
-            f'any_connected: {any_connected}\n\n'
-
-            f'{Lock.repr()}\n'
-        )
-
-        if (
-            (ctx := Lock.ctx_in_debug)
-            and
-            (uid_in_debug := ctx.chan.uid) # "someone" is (ostensibly) using debug `Lock`
-        ):
-            name_in_debug: str = uid_in_debug[0]
-            assert not repl
-            # if not repl:  # but it's NOT us, the root actor.
-            # sanity: since no repl ref is set, we def shouldn't
-            # be the lock owner!
-            assert name_in_debug != 'root'
-
-            # IDEAL CASE: child has REPL as expected
-            if any_connected:  # there are subactors we can contact
-                # XXX: only if there is an existing connection to the
-                # (sub-)actor in debug do we ignore SIGINT in this
-                # parent! Otherwise we may hang waiting for an actor
-                # which has already terminated to unlock.
-                #
-                # NOTE: don't emit this with `.pdb()` level in
-                # root without a higher level.
-                log.runtime(
-                    _ctlc_ignore_header
-                    +
-                    f' by child '
-                    f'{uid_in_debug}\n'
-                )
-                problem = None
-
-            else:
-                problem += (
-                    '\n'
-                    f'A `pdb` REPL is SUPPOSEDLY in use by child {uid_in_debug}\n'
-                    f'BUT, no child actors are IPC contactable!?!?\n'
-                )
-
-        # IDEAL CASE: root has REPL as expected
-        else:
-            # root actor still has this SIGINT handler active without
-            # an actor using the `Lock` (a bug state) ??
-            # => so immediately cancel any stale lock cs and revert
-            # the handler!
-            if not DebugStatus.repl:
-                # TODO: WHEN should we revert back to ``trio``
-                # handler if this one is stale?
-                # -[ ] maybe after a counts work of ctl-c mashes?
-                # -[ ] use a state var like `stale_handler: bool`?
-                problem += (
-                    'No subactor is using a `pdb` REPL according `Lock.ctx_in_debug`?\n'
-                    'BUT, the root should be using it, WHY this handler ??\n\n'
-                    'So either..\n'
-                    '- some root-thread is using it but has no `.repl` set?, OR\n'
-                    '- something else weird is going on outside the runtime!?\n'
-                )
-            else:
-                # NOTE: since we emit this msg on ctl-c, we should
-                # also always re-print the prompt the tail block!
-                log.pdb(
-                    _ctlc_ignore_header
-                    +
-                    f' by root actor..\n'
-                    f'{DebugStatus.repl_task}\n'
-                    f' |_{repl}\n'
-                )
-                problem = None
-
-        # XXX if one is set it means we ARE NOT operating an ideal
-        # case where a child subactor or us (the root) has the
-        # lock without any other detected problems.
-        if problem:
-
-            # detect, report and maybe clear a stale lock request
-            # cancel scope.
-            lock_cs: trio.CancelScope = Lock.get_locking_task_cs()
-            maybe_stale_lock_cs: bool = (
-                lock_cs is not None
-                and not lock_cs.cancel_called
-            )
-            if maybe_stale_lock_cs:
-                problem += (
-                    '\n'
-                    'Stale `Lock.ctx_in_debug._scope: CancelScope` detected?\n'
-                    f'{Lock.ctx_in_debug}\n\n'
-
-                    '-> Calling ctx._scope.cancel()!\n'
-                )
-                lock_cs.cancel()
-
-            # TODO: wen do we actually want/need this, see above.
-            # DebugStatus.unshield_sigint()
-            log.warning(problem)
-
-    # child actor that has locked the debugger
-    elif not is_root_process():
-        log.debug(
-            f'Subactor {actor.uid} handling SIGINT\n\n'
-            f'{Lock.repr()}\n'
-        )
-
-        rent_chan: Channel = actor._parent_chan
-        if (
-            rent_chan is None
-            or
-            not rent_chan.connected()
-        ):
-            log.warning(
-                'This sub-actor thinks it is debugging '
-                'but it has no connection to its parent ??\n'
-                f'{actor.uid}\n'
-                'Allowing SIGINT propagation..'
-            )
-            DebugStatus.unshield_sigint()
-
-        repl_task: str|None = DebugStatus.repl_task
-        req_task: str|None = DebugStatus.req_task
-        if (
-            repl_task
-            and
-            repl
-        ):
-            log.pdb(
-                _ctlc_ignore_header
-                +
-                f' by local task\n\n'
-                f'{repl_task}\n'
-                f' |_{repl}\n'
-            )
-        elif req_task:
-            log.debug(
-                _ctlc_ignore_header
-                +
-                f' by local request-task and either,\n'
-                f'- someone else is already REPL-in and has the `Lock`, or\n'
-                f'- some other local task already is replin?\n\n'
-                f'{req_task}\n'
-            )
-
-        # TODO can we remove this now?
-        # -[ ] does this path ever get hit any more?
-        else:
-            msg: str = (
-                'SIGINT shield handler still active BUT, \n\n'
-            )
-            if repl_task is None:
-                msg += (
-                    '- No local task claims to be in debug?\n'
-                )
-
-            if repl is None:
-                msg += (
-                    '- No local REPL is currently active?\n'
-                )
-
-            if req_task is None:
-                msg += (
-                    '- No debug request task is active?\n'
-                )
-
-            log.warning(
-                msg
-                +
-                'Reverting handler to `trio` default!\n'
-            )
-            DebugStatus.unshield_sigint()
-
-            # XXX ensure that the reverted-to-handler actually is
-            # able to rx what should have been **this** KBI ;)
-            do_cancel()
-
-        # TODO: how to handle the case of an intermediary-child actor
-        # that **is not** marked in debug mode? See oustanding issue:
-        # https://github.com/goodboy/tractor/issues/320
-        # elif debug_mode():
-
-    # maybe redraw/print last REPL output to console since
-    # we want to alert the user that more input is expect since
-    # nothing has been done dur to ignoring sigint.
-    if (
-        DebugStatus.repl  # only when current actor has a REPL engaged
-    ):
-        flush_status: str = (
-            'Flushing stdout to ensure new prompt line!\n'
-        )
-
-        # XXX: yah, mega hack, but how else do we catch this madness XD
-        if (
-            repl.shname == 'xonsh'
-        ):
-            flush_status += (
-                '-> ALSO re-flushing due to `xonsh`..\n'
-            )
-            repl.stdout.write(repl.prompt)
-
-        # log.warning(
-        log.devx(
-            flush_status
-        )
-        repl.stdout.flush()
-
-        # TODO: better console UX to match the current "mode":
-        # -[ ] for example if in sticky mode where if there is output
-        #   detected as written to the tty we redraw this part underneath
-        #   and erase the past draw of this same bit above?
-        # repl.sticky = True
-        # repl._print_if_sticky()
-
-        # also see these links for an approach from `ptk`:
-        # https://github.com/goodboy/tractor/issues/130#issuecomment-663752040
-        # https://github.com/prompt-toolkit/python-prompt-toolkit/blob/c2c6af8a0308f9e5d7c0e28cb8a02963fe0ce07a/prompt_toolkit/patch_stdout.py
-    else:
-        log.devx(
-        # log.warning(
-            'Not flushing stdout since not needed?\n'
-            f'|_{repl}\n'
-        )
-
-    # XXX only for tracing this handler
-    log.devx('exiting SIGINT')

tractor/devx/debug/_sync.py

@@ -1,220 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or
-# modify it under the terms of the GNU Affero General Public License
-# as published by the Free Software Foundation, either version 3 of
-# the License, or (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful, but
-# WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public
-# License along with this program.  If not, see
-# <https://www.gnu.org/licenses/>.
-
-'''
-Debugger synchronization APIs to ensure orderly access and
-non-TTY-clobbering graceful teardown.
-
-
-'''
-from __future__ import annotations
-from contextlib import (
-    asynccontextmanager as acm,
-)
-from functools import (
-    partial,
-)
-from typing import (
-    AsyncGenerator,
-    Callable,
-)
-
-from tractor.log import get_logger
-import trio
-from trio.lowlevel import (
-    current_task,
-    Task,
-)
-from tractor._context import Context
-from tractor._state import (
-    current_actor,
-    debug_mode,
-    is_root_process,
-)
-from ._repl import (
-    TractorConfig as TractorConfig,
-)
-from ._tty_lock import (
-    Lock,
-    request_root_stdio_lock,
-    any_connected_locker_child,
-)
-from ._sigint import (
-    sigint_shield as sigint_shield,
-    _ctlc_ignore_header as _ctlc_ignore_header
-)
-
-log = get_logger(__package__)
-
-
-async def maybe_wait_for_debugger(
-    poll_steps: int = 2,
-    poll_delay: float = 0.1,
-    child_in_debug: bool = False,
-
-    header_msg: str = '',
-    _ll: str = 'devx',
-
-) -> bool:  # was locked and we polled?
-
-    if (
-        not debug_mode()
-        and
-        not child_in_debug
-    ):
-        return False
-
-    logmeth: Callable = getattr(log, _ll)
-
-    msg: str = header_msg
-    if (
-        is_root_process()
-    ):
-        # If we error in the root but the debugger is
-        # engaged we don't want to prematurely kill (and
-        # thus clobber access to) the local tty since it
-        # will make the pdb repl unusable.
-        # Instead try to wait for pdb to be released before
-        # tearing down.
-        ctx_in_debug: Context|None = Lock.ctx_in_debug
-        in_debug: tuple[str, str]|None = (
-            ctx_in_debug.chan.uid
-            if ctx_in_debug
-            else None
-        )
-        if in_debug == current_actor().uid:
-            log.debug(
-                msg
-                +
-                'Root already owns the TTY LOCK'
-            )
-            return True
-
-        elif in_debug:
-            msg += (
-                f'Debug `Lock` in use by subactor\n|\n|_{in_debug}\n'
-            )
-            # TODO: could this make things more deterministic?
-            # wait to see if a sub-actor task will be
-            # scheduled and grab the tty lock on the next
-            # tick?
-            # XXX => but it doesn't seem to work..
-            # await trio.testing.wait_all_tasks_blocked(cushion=0)
-        else:
-            logmeth(
-                msg
-                +
-                'Root immediately acquired debug TTY LOCK'
-            )
-            return False
-
-        for istep in range(poll_steps):
-            if (
-                Lock.req_handler_finished is not None
-                and not Lock.req_handler_finished.is_set()
-                and in_debug is not None
-            ):
-                # caller_frame_info: str = pformat_caller_frame()
-                logmeth(
-                    msg
-                    +
-                    '\n^^ Root is waiting on tty lock release.. ^^\n'
-                    # f'{caller_frame_info}\n'
-                )
-
-                if not any_connected_locker_child():
-                    Lock.get_locking_task_cs().cancel()
-
-                with trio.CancelScope(shield=True):
-                    await Lock.req_handler_finished.wait()
-
-                log.devx(
-                    f'Subactor released debug lock\n'
-                    f'|_{in_debug}\n'
-                )
-                break
-
-            # is no subactor locking debugger currently?
-            if (
-                in_debug is None
-                and (
-                    Lock.req_handler_finished is None
-                    or Lock.req_handler_finished.is_set()
-                )
-            ):
-                logmeth(
-                    msg
-                    +
-                    'Root acquired tty lock!'
-                )
-                break
-
-            else:
-                logmeth(
-                    'Root polling for debug:\n'
-                    f'poll step: {istep}\n'
-                    f'poll delya: {poll_delay}\n\n'
-                    f'{Lock.repr()}\n'
-                )
-                with trio.CancelScope(shield=True):
-                    await trio.sleep(poll_delay)
-                    continue
-
-        return True
-
-    # else:
-    #     # TODO: non-root call for #320?
-    #     this_uid: tuple[str, str] = current_actor().uid
-    #     async with acquire_debug_lock(
-    #         subactor_uid=this_uid,
-    #     ):
-    #         pass
-    return False
-
-
-@acm
-async def acquire_debug_lock(
-    subactor_uid: tuple[str, str],
-) -> AsyncGenerator[
-    trio.CancelScope|None,
-    tuple,
-]:
-    '''
-    Request to acquire the TTY `Lock` in the root actor, release on
-    exit.
-
-    This helper is for actor's who don't actually need to acquired
-    the debugger but want to wait until the lock is free in the
-    process-tree root such that they don't clobber an ongoing pdb
-    REPL session in some peer or child!
-
-    '''
-    if not debug_mode():
-        yield None
-        return
-
-    task: Task = current_task()
-    async with trio.open_nursery() as n:
-        ctx: Context = await n.start(
-            partial(
-                request_root_stdio_lock,
-                actor_uid=subactor_uid,
-                task_uid=(task.name, id(task)),
-            )
-        )
-        yield ctx
-        ctx.cancel()

tractor/devx/pformat.py

@@ -1,527 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-'''
-Pretty formatters for use throughout our internals.
-
-Handy for logging and exception message content but also for `repr()`
-in REPL(s).
-
-'''
-import sys
-import textwrap
-import traceback
-
-from trio import CancelScope
-
-
-def add_div(
-    message: str,
-    div_str: str = '------ - ------',
-
-) -> str:
-    '''
-    Add a "divider string" to the input `message` with
-    a little math to center it underneath.
-
-    '''
-    div_offset: int = (
-        round(len(message)/2)+1
-        -
-        round(len(div_str)/2)+1
-    )
-    div_str: str = (
-        '\n' + ' '*div_offset + f'{div_str}\n'
-    )
-    return div_str
-
-
-def pformat_boxed_tb(
-    tb_str: str,
-    fields_str: str|None = None,
-    field_prefix: str = ' |_',
-
-    tb_box_indent: int|None = None,
-    tb_body_indent: int = 1,
-    boxer_header: str = '-'
-
-) -> str:
-    '''
-    Create a "boxed" looking traceback string.
-
-    Useful for emphasizing traceback text content as being an
-    embedded attribute of some other object (like
-    a `RemoteActorError` or other boxing remote error shuttle
-    container).
-
-    Any other parent/container "fields" can be passed in the
-    `fields_str` input along with other prefix/indent settings.
-
-    '''
-    if (
-        fields_str
-        and
-        field_prefix
-    ):
-        fields: str = textwrap.indent(
-            fields_str,
-            prefix=field_prefix,
-        )
-    else:
-        fields = fields_str or ''
-
-    tb_body = tb_str
-    if tb_body_indent:
-        tb_body: str = textwrap.indent(
-            tb_str,
-            prefix=tb_body_indent * ' ',
-        )
-
-    tb_box: str = (
-        f'|\n'
-        f' ------ {boxer_header} ------\n'
-        f'{tb_body}'
-        f' ------ {boxer_header}- ------\n'
-        f'_|'
-    )
-    tb_box_indent: str = (
-        tb_box_indent
-        or
-        1
-
-        # (len(field_prefix))
-        # ? ^-TODO-^ ? if you wanted another indent level
-    )
-    if tb_box_indent > 0:
-        tb_box: str = textwrap.indent(
-            tb_box,
-            prefix=tb_box_indent * ' ',
-        )
-
-    return (
-        fields
-        +
-        tb_box
-    )
-
-
-def pformat_exc(
-    exc: Exception,
-    header: str = '',
-    message: str = '',
-    body: str = '',
-    with_type_header: bool = True,
-) -> str:
-
-    # XXX when the currently raised exception is this instance,
-    # we do not ever use the "type header" style repr.
-    is_being_raised: bool = False
-    if (
-        (curr_exc := sys.exception())
-        and
-        curr_exc is exc
-    ):
-        is_being_raised: bool = True
-
-    with_type_header: bool = (
-        with_type_header
-        and
-        not is_being_raised
-    )
-
-    # <RemoteActorError( .. )> style
-    if (
-        with_type_header
-        and
-        not header
-    ):
-        header: str = f'<{type(exc).__name__}('
-
-    message: str = (
-        message
-        or
-        exc.message
-    )
-    if message:
-        # split off the first line so, if needed, it isn't
-        # indented the same like the "boxed content" which
-        # since there is no `.tb_str` is just the `.message`.
-        lines: list[str] = message.splitlines()
-        first: str = lines[0]
-        message: str = message.removeprefix(first)
-
-        # with a type-style header we,
-        # - have no special message "first line" extraction/handling
-        # - place the message a space in from the header:
-        #  `MsgTypeError( <message> ..`
-        #                 ^-here
-        # - indent the `.message` inside the type body.
-        if with_type_header:
-            first = f' {first} )>'
-
-        message: str = textwrap.indent(
-            message,
-            prefix=' '*2,
-        )
-        message: str = first + message
-
-    tail: str = ''
-    if (
-        with_type_header
-        and
-        not message
-    ):
-        tail: str = '>'
-
-    return (
-        header
-        +
-        message
-        +
-        f'{body}'
-        +
-        tail
-    )
-
-
-def pformat_caller_frame(
-    stack_limit: int = 1,
-    box_tb: bool = True,
-) -> str:
-    '''
-    Capture and return the traceback text content from
-    `stack_limit` call frames up.
-
-    '''
-    tb_str: str = (
-        '\n'.join(
-            traceback.format_stack(limit=stack_limit)
-        )
-    )
-    if box_tb:
-        tb_str: str = pformat_boxed_tb(
-            tb_str=tb_str,
-            field_prefix='  ',
-            indent='',
-        )
-    return tb_str
-
-
-def pformat_cs(
-    cs: CancelScope,
-    var_name: str = 'cs',
-    field_prefix: str = ' |_',
-) -> str:
-    '''
-    Pretty format info about a `trio.CancelScope` including most of
-    its public state and `._cancel_status`.
-
-    The output can be modified to show a "var name" for the
-    instance as a field prefix, just a simple str before each
-    line more or less.
-
-    '''
-
-    fields: str = textwrap.indent(
-        (
-            f'cancel_called = {cs.cancel_called}\n'
-            f'cancelled_caught = {cs.cancelled_caught}\n'
-            f'_cancel_status = {cs._cancel_status}\n'
-            f'shield = {cs.shield}\n'
-        ),
-        prefix=field_prefix,
-    )
-    return (
-        f'{var_name}: {cs}\n'
-        +
-        fields
-    )
-
-
-def nest_from_op(
-    input_op: str,  # TODO, Literal of all op-"symbols" from below?
-    text: str,
-    prefix_op: bool = True,  # unset is to suffix the first line
-    # optionally suffix `text`, by def on a newline
-    op_suffix='\n',
-
-    nest_prefix: str = '|_',
-    nest_indent: int|None = None,
-    # XXX indent `next_prefix` "to-the-right-of" `input_op`
-    # by this count of whitespaces (' ').
-    rm_from_first_ln: str|None = None,
-
-) -> str:
-    '''
-    Depth-increment the input (presumably hierarchy/supervision)
-    input "tree string" below the provided `input_op` execution
-    operator, so injecting a `"\n|_{input_op}\n"`and indenting the
-    `tree_str` to nest content aligned with the ops last char.
-
-    '''
-    # `sclang` "structurred-concurrency-language": an ascii-encoded
-    # symbolic alphabet to describe concurrent systems.
-    #
-    # ?TODO? aa more fomal idea for a syntax to the state of
-    # concurrent systems as a "3-domain" (execution, scope, storage)
-    # model and using a minimal ascii/utf-8 operator-set.
-    #
-    # try not to take any of this seriously yet XD
-    #
-    # > is a "play operator" indicating (CPU bound)
-    #   exec/work/ops required at the "lowest level computing"
-    #
-    # execution primititves (tasks, threads, actors..) denote their
-    # lifetime with '(' and ')' since parentheses normally are used
-    # in many langs to denote function calls.
-    #
-    # starting = (
-    # >(  opening/starting; beginning of the thread-of-exec (toe?)
-    # (>  opened/started,  (finished spawning toe)
-    # |_<Task: blah blah..>  repr of toe, in py these look like <objs>
-    #
-    # >) closing/exiting/stopping,
-    # )> closed/exited/stopped,
-    # |_<Task: blah blah..>
-    #   [OR <), )< ?? ]
-    #
-    # ending = )
-    # >c) cancelling to close/exit
-    # c)> cancelled (caused close), OR?
-    #  |_<Actor: ..>
-    #   OR maybe "<c)" which better indicates the cancel being
-    #   "delivered/returned" / returned" to LHS?
-    #
-    # >x)  erroring to eventuall exit
-    # x)>  errored and terminated
-    #  |_<Actor: ...>
-    #
-    # scopes: supers/nurseries, IPC-ctxs, sessions, perms, etc.
-    # >{  opening
-    # {>  opened
-    # }>  closed
-    # >}  closing
-    #
-    # storage: like queues, shm-buffers, files, etc..
-    # >[  opening
-    # [>  opened
-    #  |_<FileObj: ..>
-    #
-    # >]  closing
-    # ]>  closed
-
-    # IPC ops: channels, transports, msging
-    # =>  req msg
-    # <=  resp msg
-    # <=> 2-way streaming (of msgs)
-    # <-  recv 1 msg
-    # ->  send 1 msg
-    #
-    # TODO: still not sure on R/L-HS approach..?
-    # =>(  send-req to exec start (task, actor, thread..)
-    # (<=  recv-req to ^
-    #
-    # (<=  recv-req ^
-    # <=(  recv-resp opened remote exec primitive
-    # <=)  recv-resp closed
-    #
-    # )<=c req to stop due to cancel
-    # c=>) req to stop due to cancel
-    #
-    # =>{  recv-req to open
-    # <={  send-status that it closed
-    #
-    if (
-        nest_prefix
-        and
-        nest_indent != 0
-    ):
-        if nest_indent is not None:
-            nest_prefix: str = textwrap.indent(
-                nest_prefix,
-                prefix=nest_indent*' ',
-            )
-        nest_indent: int = len(nest_prefix)
-
-    # determine body-text indent either by,
-    # - using wtv explicit indent value is provided,
-    # OR
-    # - auto-calcing the indent to embed `text` under
-    #   the `nest_prefix` if provided, **IFF** `nest_indent=None`.
-    tree_str_indent: int = 0
-    if nest_indent not in {0, None}:
-        tree_str_indent = nest_indent
-    elif (
-        nest_prefix
-        and
-        nest_indent != 0
-    ):
-        tree_str_indent = len(nest_prefix)
-
-    indented_tree_str: str = text
-    if tree_str_indent:
-        indented_tree_str: str = textwrap.indent(
-            text,
-            prefix=' '*tree_str_indent,
-        )
-
-    # inject any provided nesting-prefix chars
-    # into the head of the first line.
-    if nest_prefix:
-        indented_tree_str: str = (
-            f'{nest_prefix}{indented_tree_str[tree_str_indent:]}'
-        )
-
-    if (
-        not prefix_op
-        or
-        rm_from_first_ln
-    ):
-        tree_lns: list[str] = indented_tree_str.splitlines()
-        first: str = tree_lns[0]
-        if rm_from_first_ln:
-            first = first.strip().replace(
-                rm_from_first_ln,
-                '',
-            )
-        indented_tree_str: str = '\n'.join(tree_lns[1:])
-
-        if prefix_op:
-            indented_tree_str = (
-                f'{first}\n'
-                f'{indented_tree_str}'
-            )
-
-    if prefix_op:
-        return (
-            f'{input_op}{op_suffix}'
-            f'{indented_tree_str}'
-        )
-    else:
-        return (
-            f'{first}{input_op}{op_suffix}'
-            f'{indented_tree_str}'
-        )
-
-
-# ------ modden.repr ------
-# XXX originally taken verbaatim from `modden.repr`
-'''
-More "multi-line" representation then the stdlib's `pprint` equivs.
-
-'''
-from inspect import (
-    FrameInfo,
-    stack,
-)
-import pprint
-import reprlib
-from typing import (
-    Callable,
-)
-
-
-def mk_repr(
-    **repr_kws,
-) -> Callable[[str], str]:
-    '''
-    Allocate and deliver a `repr.Repr` instance with provided input
-    settings using the std-lib's `reprlib` mod,
-     * https://docs.python.org/3/library/reprlib.html
-
-    ------ Ex. ------
-    An up to 6-layer-nested `dict` as multi-line:
-    - https://stackoverflow.com/a/79102479
-    - https://docs.python.org/3/library/reprlib.html#reprlib.Repr.maxlevel
-
-    '''
-    def_kws: dict[str, int] = dict(
-        indent=3,  # indent used for repr of recursive objects
-        maxlevel=616,  # recursion levels
-        maxdict=616,  # max items shown for `dict`
-        maxlist=616,  # max items shown for `dict`
-        maxstring=616,  # match editor line-len limit
-        maxtuple=616,  # match editor line-len limit
-        maxother=616,  # match editor line-len limit
-    )
-    def_kws |= repr_kws
-    reprr = reprlib.Repr(**def_kws)
-    return reprr.repr
-
-
-def ppfmt(
-    obj: object,
-    do_print: bool = False,
-) -> str:
-    '''
-    The `pprint.pformat()` version of `pprint.pp()`, namely
-    a default `sort_dicts=False`.. (which i think should be
-    the normal default in the stdlib).
-
-    '''
-    pprepr: Callable = mk_repr()
-    repr_str: str = pprepr(obj)
-
-    if do_print:
-        return pprint.pp(repr_str)
-
-    return repr_str
-
-
-pformat = ppfmt
-
-
-def pfmt_frame_info(fi: FrameInfo) -> str:
-    '''
-    Like a std `inspect.FrameInfo.__repr__()` but multi-line..
-
-    '''
-    return (
-        'FrameInfo(\n'
-        '  frame={!r},\n'
-        '  filename={!r},\n'
-        '  lineno={!r},\n'
-        '  function={!r},\n'
-        '  code_context={!r},\n'
-        '  index={!r},\n'
-        '  positions={!r})'
-        ).format(
-            fi.frame,
-            fi.filename,
-            fi.lineno,
-            fi.function,
-            fi.code_context,
-            fi.index,
-            fi.positions
-        )
-
-
-def pfmt_callstack(frames: int = 1) -> str:
-    '''
-    Generate a string of nested `inspect.FrameInfo` objects returned
-    from a `inspect.stack()` call such that only the `.frame` field
-    for each  layer is pprinted.
-
-    '''
-    caller_frames: list[FrameInfo] =  stack()[1:1+frames]
-    frames_str: str = ''
-    for i, frame_info in enumerate(caller_frames):
-        frames_str += textwrap.indent(
-            f'{frame_info.frame!r}\n',
-            prefix=' '*i,
-
-        )
-    return frames_str

tractor/experimental/_pubsub.py

@@ -45,8 +45,6 @@ __all__ = ['pub']
 log = get_logger('messaging')
 
 
-# TODO! this needs to reworked to use the modern
-# `Context`/`MsgStream` APIs!!
 async def fan_out_to_ctxs(
     pub_async_gen_func: typing.Callable,  # it's an async gen ... gd mypy
     topics2ctxs: dict[str, list],

tractor/ipc/__init__.py

@@ -1,24 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-'''
-A modular IPC layer supporting the power of cross-process SC!
-
-'''
-from ._chan import (
-    _connect_chan as _connect_chan,
-    Channel as Channel
-)

tractor/ipc/_chan.py

@@ -1,457 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-"""
-Inter-process comms abstractions
-
-"""
-from __future__ import annotations
-from collections.abc import AsyncGenerator
-from contextlib import (
-    asynccontextmanager as acm,
-    contextmanager as cm,
-)
-import platform
-from pprint import pformat
-import typing
-from typing import (
-    Any,
-    TYPE_CHECKING,
-)
-import warnings
-
-import trio
-
-from ._types import (
-    transport_from_addr,
-    transport_from_stream,
-)
-from tractor._addr import (
-    is_wrapped_addr,
-    wrap_address,
-    Address,
-    UnwrappedAddress,
-)
-from tractor.log import get_logger
-from tractor._exceptions import (
-    MsgTypeError,
-    pack_from_raise,
-    TransportClosed,
-)
-from tractor.msg import (
-    Aid,
-    MsgCodec,
-)
-
-if TYPE_CHECKING:
-    from ._transport import MsgTransport
-
-
-log = get_logger(__name__)
-
-_is_windows = platform.system() == 'Windows'
-
-
-class Channel:
-    '''
-    An inter-process channel for communication between (remote) actors.
-
-    Wraps a ``MsgStream``: transport + encoding IPC connection.
-
-    Currently we only support ``trio.SocketStream`` for transport
-    (aka TCP) and the ``msgpack`` interchange format via the ``msgspec``
-    codec libary.
-
-    '''
-    def __init__(
-
-        self,
-        transport: MsgTransport|None = None,
-        # TODO: optional reconnection support?
-        # auto_reconnect: bool = False,
-        # on_reconnect: typing.Callable[..., typing.Awaitable] = None,
-
-    ) -> None:
-
-        # self._recon_seq = on_reconnect
-        # self._autorecon = auto_reconnect
-
-        # Either created in ``.connect()`` or passed in by
-        # user in ``.from_stream()``.
-        self._transport: MsgTransport|None = transport
-
-        # set after handshake - always info from peer end
-        self.aid: Aid|None = None
-
-        self._aiter_msgs = self._iter_msgs()
-        self._exc: Exception|None = None
-        # ^XXX! ONLY set if a remote actor sends an `Error`-msg
-        self._closed: bool = False
-
-        # flag set by ``Portal.cancel_actor()`` indicating remote
-        # (possibly peer) cancellation of the far end actor
-        # runtime.
-        self._cancel_called: bool = False
-
-    @property
-    def uid(self) -> tuple[str, str]:
-        '''
-        Peer actor's unique id.
-
-        '''
-        msg: str = (
-            f'`{type(self).__name__}.uid` is now deprecated.\n'
-            'Use the new `.aid: tractor.msg.Aid` (struct) instead '
-            'which also provides additional named (optional) fields '
-            'beyond just the `.name` and `.uuid`.'
-        )
-        warnings.warn(
-            msg,
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        peer_aid: Aid = self.aid
-        return (
-            peer_aid.name,
-            peer_aid.uuid,
-        )
-
-    @property
-    def stream(self) -> trio.abc.Stream | None:
-        return self._transport.stream if self._transport else None
-
-    @property
-    def msgstream(self) -> MsgTransport:
-        log.info(
-            '`Channel.msgstream` is an old name, use `._transport`'
-        )
-        return self._transport
-
-    @property
-    def transport(self) -> MsgTransport:
-        return self._transport
-
-    @classmethod
-    def from_stream(
-        cls,
-        stream: trio.abc.Stream,
-    ) -> Channel:
-        transport_cls = transport_from_stream(stream)
-        return Channel(
-            transport=transport_cls(stream)
-        )
-
-    @classmethod
-    async def from_addr(
-        cls,
-        addr: UnwrappedAddress,
-        **kwargs
-    ) -> Channel:
-
-        if not is_wrapped_addr(addr):
-            addr: Address = wrap_address(addr)
-
-        transport_cls = transport_from_addr(addr)
-        transport = await transport_cls.connect_to(
-            addr,
-            **kwargs,
-        )
-        assert transport.raddr == addr
-        chan = Channel(transport=transport)
-        log.runtime(
-            f'Connected channel IPC transport\n'
-            f'[>\n'
-            f' |_{chan}\n'
-        )
-        return chan
-
-    @cm
-    def apply_codec(
-        self,
-        codec: MsgCodec,
-    ) -> None:
-        '''
-        Temporarily override the underlying IPC msg codec for
-        dynamic enforcement of messaging schema.
-
-        '''
-        orig: MsgCodec = self._transport.codec
-        try:
-            self._transport.codec = codec
-            yield
-        finally:
-            self._transport.codec = orig
-
-    # TODO: do a .src/.dst: str for maddrs?
-    def pformat(self) -> str:
-        if not self._transport:
-            return '<Channel with inactive transport?>'
-
-        tpt: MsgTransport = self._transport
-        tpt_name: str = type(tpt).__name__
-        tpt_status: str = (
-            'connected' if self.connected()
-            else 'closed'
-        )
-        return (
-            f'<Channel(\n'
-            f' |_status: {tpt_status!r}\n'
-            f'   _closed={self._closed}\n'
-            f'   _cancel_called={self._cancel_called}\n'
-            f'\n'
-            f' |_peer: {self.aid}\n'
-            f'\n'
-            f' |_msgstream: {tpt_name}\n'
-            f'   proto={tpt.laddr.proto_key!r}\n'
-            f'   layer={tpt.layer_key!r}\n'
-            f'   laddr={tpt.laddr}\n'
-            f'   raddr={tpt.raddr}\n'
-            f'   codec={tpt.codec_key!r}\n'
-            f'   stream={tpt.stream}\n'
-            f'   maddr={tpt.maddr!r}\n'
-            f'   drained={tpt.drained}\n'
-            f'   _send_lock={tpt._send_lock.statistics()}\n'
-            f')>\n'
-        )
-
-    # NOTE: making this return a value that can be passed to
-    # `eval()` is entirely **optional** FYI!
-    # https://docs.python.org/3/library/functions.html#repr
-    # https://docs.python.org/3/reference/datamodel.html#object.__repr__
-    #
-    # Currently we target **readability** from a (console)
-    # logging perspective over `eval()`-ability since we do NOT
-    # target serializing non-struct instances!
-    # def __repr__(self) -> str:
-    __str__ = pformat
-    __repr__ = pformat
-
-    @property
-    def laddr(self) -> Address|None:
-        return self._transport.laddr if self._transport else None
-
-    @property
-    def raddr(self) -> Address|None:
-        return self._transport.raddr if self._transport else None
-
-    # TODO: something like,
-    # `pdbp.hideframe_on(errors=[MsgTypeError])`
-    # instead of the `try/except` hack we have rn..
-    # seems like a pretty useful thing to have in general
-    # along with being able to filter certain stack frame(s / sets)
-    # possibly based on the current log-level?
-    async def send(
-        self,
-        payload: Any,
-
-        hide_tb: bool = True,
-
-    ) -> None:
-        '''
-        Send a coded msg-blob over the transport.
-
-        '''
-        __tracebackhide__: bool = hide_tb
-        try:
-            log.transport(
-                '=> send IPC msg:\n\n'
-                f'{pformat(payload)}\n'
-            )
-            # assert self._transport  # but why typing?
-            await self._transport.send(
-                payload,
-                hide_tb=hide_tb,
-            )
-        except (
-            BaseException,
-            MsgTypeError,
-            TransportClosed,
-        )as _err:
-            err = _err  # bind for introspection
-            match err:
-                case MsgTypeError():
-                    try:
-                        assert err.cid
-                    except KeyError:
-                        raise err
-                case TransportClosed():
-                    log.transport(
-                        f'Transport stream closed due to\n'
-                        f'{err.repr_src_exc()}\n'
-                    )
-
-                case _:
-                    # never suppress non-tpt sources
-                    __tracebackhide__: bool = False
-            raise
-
-    async def recv(self) -> Any:
-        assert self._transport
-        return await self._transport.recv()
-
-        # TODO: auto-reconnect features like 0mq/nanomsg?
-        # -[ ] implement it manually with nods to SC prot
-        #      possibly on multiple transport backends?
-        #  -> seems like that might be re-inventing scalability
-        #     prots tho no?
-        # try:
-        #     return await self._transport.recv()
-        # except trio.BrokenResourceError:
-        #     if self._autorecon:
-        #         await self._reconnect()
-        #         return await self.recv()
-        #     raise
-
-    async def aclose(self) -> None:
-
-        log.transport(
-            f'Closing channel to {self.aid} '
-            f'{self.laddr} -> {self.raddr}'
-        )
-        assert self._transport
-        await self._transport.stream.aclose()
-        self._closed = True
-
-    async def __aenter__(self):
-        await self.connect()
-        return self
-
-    async def __aexit__(self, *args):
-        await self.aclose(*args)
-
-    def __aiter__(self):
-        return self._aiter_msgs
-
-    # ?TODO? run any reconnection sequence?
-    # -[ ] prolly should be impl-ed as deco-API?
-    #
-    # async def _reconnect(self) -> None:
-    #     """Handle connection failures by polling until a reconnect can be
-    #     established.
-    #     """
-    #     down = False
-    #     while True:
-    #         try:
-    #             with trio.move_on_after(3) as cancel_scope:
-    #                 await self.connect()
-    #             cancelled = cancel_scope.cancelled_caught
-    #             if cancelled:
-    #                 log.transport(
-    #                     "Reconnect timed out after 3 seconds, retrying...")
-    #                 continue
-    #             else:
-    #                 log.transport("Stream connection re-established!")
-
-    #                 # on_recon = self._recon_seq
-    #                 # if on_recon:
-    #                 #     await on_recon(self)
-
-    #                 break
-    #         except (OSError, ConnectionRefusedError):
-    #             if not down:
-    #                 down = True
-    #                 log.transport(
-    #                     f"Connection to {self.raddr} went down, waiting"
-    #                     " for re-establishment")
-    #             await trio.sleep(1)
-
-    async def _iter_msgs(
-        self
-    ) -> AsyncGenerator[Any, None]:
-        '''
-        Yield `MsgType` IPC msgs decoded and deliverd from
-        an underlying `MsgTransport` protocol.
-
-        This is a streaming routine alo implemented as an async-gen
-        func (same a `MsgTransport._iter_pkts()`) gets allocated by
-        a `.__call__()` inside `.__init__()` where it is assigned to
-        the `._aiter_msgs` attr.
-
-        '''
-        assert self._transport
-        while True:
-            try:
-                async for msg in self._transport:
-                    match msg:
-                        # NOTE: if transport/interchange delivers
-                        # a type error, we pack it with the far
-                        # end peer `Actor.uid` and relay the
-                        # `Error`-msg upward to the `._rpc` stack
-                        # for normal RAE handling.
-                        case MsgTypeError():
-                            yield pack_from_raise(
-                                local_err=msg,
-                                cid=msg.cid,
-
-                                # XXX we pack it here bc lower
-                                # layers have no notion of an
-                                # actor-id ;)
-                                src_uid=self.uid,
-                            )
-                        case _:
-                            yield msg
-
-            except trio.BrokenResourceError:
-
-                # if not self._autorecon:
-                raise
-
-            await self.aclose()
-
-            # if self._autorecon:  # attempt reconnect
-            #     await self._reconnect()
-            #     continue
-
-    def connected(self) -> bool:
-        return self._transport.connected() if self._transport else False
-
-    async def _do_handshake(
-        self,
-        aid: Aid,
-
-    ) -> Aid:
-        '''
-        Exchange `(name, UUIDs)` identifiers as the first
-        communication step with any (peer) remote `Actor`.
-
-        These are essentially the "mailbox addresses" found in
-        "actor model" parlance.
-
-        '''
-        await self.send(aid)
-        peer_aid: Aid = await self.recv()
-        log.runtime(
-            f'Received hanshake with peer actor,\n'
-            f'{peer_aid}\n'
-        )
-        # NOTE, we always are referencing the remote peer!
-        self.aid = peer_aid
-        return peer_aid
-
-
-@acm
-async def _connect_chan(
-    addr: UnwrappedAddress
-) -> typing.AsyncGenerator[Channel, None]:
-    '''
-    Create and connect a channel with disconnect on context manager
-    teardown.
-
-    '''
-    chan = await Channel.from_addr(addr)
-    yield chan
-    with trio.CancelScope(shield=True):
-        await chan.aclose()

tractor/ipc/_fd_share.py

@@ -1,163 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <https://www.gnu.org/licenses/>.
-'''
-File-descriptor-sharing on `linux` by "wilhelm_of_bohemia".
-
-'''
-from __future__ import annotations
-import os
-import array
-import socket
-import tempfile
-from pathlib import Path
-from contextlib import ExitStack
-
-import trio
-import tractor
-from tractor.ipc import RBToken
-
-
-actor_name = 'ringd'
-
-
-_rings: dict[str, dict] = {}
-
-
-async def _attach_to_ring(
-    ring_name: str
-) -> tuple[int, int, int]:
-    actor = tractor.current_actor()
-
-    fd_amount = 3
-    sock_path = (
-        Path(tempfile.gettempdir())
-        /
-        f'{os.getpid()}-pass-ring-fds-{ring_name}-to-{actor.name}.sock'
-    )
-    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
-    sock.bind(sock_path)
-    sock.listen(1)
-
-    async with (
-        tractor.find_actor(actor_name) as ringd,
-        ringd.open_context(
-            _pass_fds,
-            name=ring_name,
-            sock_path=sock_path
-        ) as (ctx, _sent)
-    ):
-        # prepare array to receive FD
-        fds = array.array("i", [0] * fd_amount)
-
-        conn, _ = sock.accept()
-
-        # receive FD
-        msg, ancdata, flags, addr = conn.recvmsg(
-            1024,
-            socket.CMSG_LEN(fds.itemsize * fd_amount)
-        )
-
-        for (
-            cmsg_level,
-            cmsg_type,
-            cmsg_data,
-        ) in ancdata:
-            if (
-                cmsg_level == socket.SOL_SOCKET
-                and
-                cmsg_type == socket.SCM_RIGHTS
-            ):
-                fds.frombytes(cmsg_data[:fds.itemsize * fd_amount])
-                break
-            else:
-                raise RuntimeError("Receiver: No FDs received")
-
-        conn.close()
-        sock.close()
-        sock_path.unlink()
-
-        return RBToken.from_msg(
-            await ctx.wait_for_result()
-        )
-
-
-@tractor.context
-async def _pass_fds(
-    ctx: tractor.Context,
-    name: str,
-    sock_path: str
-) -> RBToken:
-    global _rings
-    token = _rings[name]
-    client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
-    client.connect(sock_path)
-    await ctx.started()
-    fds = array.array('i', token.fds)
-    client.sendmsg([b'FDs'], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, fds)])
-    client.close()
-    return token
-
-
-@tractor.context
-async def _open_ringbuf(
-    ctx: tractor.Context,
-    name: str,
-    buf_size: int
-) -> RBToken:
-    global _rings
-    is_owner = False
-    if name not in _rings:
-        stack = ExitStack()
-        token = stack.enter_context(
-            tractor.open_ringbuf(
-                name,
-                buf_size=buf_size
-            )
-        )
-        _rings[name] = {
-            'token': token,
-            'stack': stack,
-        }
-        is_owner = True
-
-    ring = _rings[name]
-    await ctx.started()
-
-    try:
-        await trio.sleep_forever()
-
-    except tractor.ContextCancelled:
-        ...
-
-    finally:
-        if is_owner:
-            ring['stack'].close()
-
-
-async def open_ringbuf(
-    name: str,
-    buf_size: int
-) -> RBToken:
-    async with (
-        tractor.find_actor(actor_name) as ringd,
-        ringd.open_context(
-            _open_ringbuf,
-            name=name,
-            buf_size=buf_size
-        ) as (rd_ctx, _)
-    ):
-        yield await _attach_to_ring(name)
-        await rd_ctx.cancel()

tractor/ipc/_linux.py

@@ -1,153 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <https://www.gnu.org/licenses/>.
-'''
-Linux specifics, for now we are only exposing EventFD
-
-'''
-import os
-import errno
-
-import cffi
-import trio
-
-ffi = cffi.FFI()
-
-# Declare the C functions and types we plan to use.
-#    - eventfd: for creating the event file descriptor
-#    - write:   for writing to the file descriptor
-#    - read:    for reading from the file descriptor
-#    - close:   for closing the file descriptor
-ffi.cdef(
-    '''
-    int eventfd(unsigned int initval, int flags);
-
-    ssize_t write(int fd, const void *buf, size_t count);
-    ssize_t read(int fd, void *buf, size_t count);
-
-    int close(int fd);
-    '''
-)
-
-
-# Open the default dynamic library (essentially 'libc' in most cases)
-C = ffi.dlopen(None)
-
-
-# Constants from <sys/eventfd.h>, if needed.
-EFD_SEMAPHORE = 1
-EFD_CLOEXEC = 0o2000000
-EFD_NONBLOCK = 0o4000
-
-
-def open_eventfd(initval: int = 0, flags: int = 0) -> int:
-    '''
-    Open an eventfd with the given initial value and flags.
-    Returns the file descriptor on success, otherwise raises OSError.
-
-    '''
-    fd = C.eventfd(initval, flags)
-    if fd < 0:
-        raise OSError(errno.errorcode[ffi.errno], 'eventfd failed')
-    return fd
-
-
-def write_eventfd(fd: int, value: int) -> int:
-    '''
-    Write a 64-bit integer (uint64_t) to the eventfd's counter.
-
-    '''
-    # Create a uint64_t* in C, store `value`
-    data_ptr = ffi.new('uint64_t *', value)
-
-    # Call write(fd, data_ptr, 8)
-    # We expect to write exactly 8 bytes (sizeof(uint64_t))
-    ret = C.write(fd, data_ptr, 8)
-    if ret < 0:
-        raise OSError(errno.errorcode[ffi.errno], 'write to eventfd failed')
-    return ret
-
-
-def read_eventfd(fd: int) -> int:
-    '''
-    Read a 64-bit integer (uint64_t) from the eventfd, returning the value.
-    Reading resets the counter to 0 (unless using EFD_SEMAPHORE).
-
-    '''
-    # Allocate an 8-byte buffer in C for reading
-    buf = ffi.new('char[]', 8)
-
-    ret = C.read(fd, buf, 8)
-    if ret < 0:
-        raise OSError(errno.errorcode[ffi.errno], 'read from eventfd failed')
-    # Convert the 8 bytes we read into a Python integer
-    data_bytes = ffi.unpack(buf, 8)  # returns a Python bytes object of length 8
-    value = int.from_bytes(data_bytes, byteorder='little', signed=False)
-    return value
-
-
-def close_eventfd(fd: int) -> int:
-    '''
-    Close the eventfd.
-
-    '''
-    ret = C.close(fd)
-    if ret < 0:
-        raise OSError(errno.errorcode[ffi.errno], 'close failed')
-
-
-class EventFD:
-    '''
-    Use a previously opened eventfd(2), meant to be used in
-    sub-actors after root actor opens the eventfds then passes
-    them through pass_fds
-
-    '''
-
-    def __init__(
-        self,
-        fd: int,
-        omode: str
-    ):
-        self._fd: int = fd
-        self._omode: str = omode
-        self._fobj = None
-
-    @property
-    def fd(self) -> int | None:
-        return self._fd
-
-    def write(self, value: int) -> int:
-        return write_eventfd(self._fd, value)
-
-    async def read(self) -> int:
-        return await trio.to_thread.run_sync(
-            read_eventfd, self._fd,
-            abandon_on_cancel=True
-        )
-
-    def open(self):
-        self._fobj = os.fdopen(self._fd, self._omode)
-
-    def close(self):
-        if self._fobj:
-            self._fobj.close()
-
-    def __enter__(self):
-        self.open()
-        return self
-
-    def __exit__(self, exc_type, exc_value, traceback):
-        self.close()

tractor/ipc/_mp_bs.py

@@ -1,45 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <https://www.gnu.org/licenses/>.
-'''
-Utils to tame mp non-SC madeness
-
-'''
-def disable_mantracker():
-    '''
-    Disable all ``multiprocessing``` "resource tracking" machinery since
-    it's an absolute multi-threaded mess of non-SC madness.
-
-    '''
-    from multiprocessing import resource_tracker as mantracker
-
-    # Tell the "resource tracker" thing to fuck off.
-    class ManTracker(mantracker.ResourceTracker):
-        def register(self, name, rtype):
-            pass
-
-        def unregister(self, name, rtype):
-            pass
-
-        def ensure_running(self):
-            pass
-
-    # "know your land and know your prey"
-    # https://www.dailymotion.com/video/x6ozzco
-    mantracker._resource_tracker = ManTracker()
-    mantracker.register = mantracker._resource_tracker.register
-    mantracker.ensure_running = mantracker._resource_tracker.ensure_running
-    mantracker.unregister = mantracker._resource_tracker.unregister
-    mantracker.getfd = mantracker._resource_tracker.getfd

tractor/ipc/_ringbuf.py

@@ -1,253 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <https://www.gnu.org/licenses/>.
-'''
-IPC Reliable RingBuffer implementation
-
-'''
-from __future__ import annotations
-from contextlib import contextmanager as cm
-from multiprocessing.shared_memory import SharedMemory
-
-import trio
-from msgspec import (
-    Struct,
-    to_builtins
-)
-
-from ._linux import (
-    EFD_NONBLOCK,
-    open_eventfd,
-    EventFD
-)
-from ._mp_bs import disable_mantracker
-
-
-disable_mantracker()
-
-
-class RBToken(Struct, frozen=True):
-    '''
-    RingBuffer token contains necesary info to open the two
-    eventfds and the shared memory
-
-    '''
-    shm_name: str
-    write_eventfd: int
-    wrap_eventfd: int
-    buf_size: int
-
-    def as_msg(self):
-        return to_builtins(self)
-
-    @classmethod
-    def from_msg(cls, msg: dict) -> RBToken:
-        if isinstance(msg, RBToken):
-            return msg
-
-        return RBToken(**msg)
-
-
-@cm
-def open_ringbuf(
-    shm_name: str,
-    buf_size: int = 10 * 1024,
-    write_efd_flags: int = 0,
-    wrap_efd_flags: int = 0
-) -> RBToken:
-    shm = SharedMemory(
-        name=shm_name,
-        size=buf_size,
-        create=True
-    )
-    try:
-        token = RBToken(
-            shm_name=shm_name,
-            write_eventfd=open_eventfd(flags=write_efd_flags),
-            wrap_eventfd=open_eventfd(flags=wrap_efd_flags),
-            buf_size=buf_size
-        )
-        yield token
-
-    finally:
-        shm.unlink()
-
-
-class RingBuffSender(trio.abc.SendStream):
-    '''
-    IPC Reliable Ring Buffer sender side implementation
-
-    `eventfd(2)` is used for wrap around sync, and also to signal
-    writes to the reader.
-
-    '''
-    def __init__(
-        self,
-        token: RBToken,
-        start_ptr: int = 0,
-    ):
-        token = RBToken.from_msg(token)
-        self._shm = SharedMemory(
-            name=token.shm_name,
-            size=token.buf_size,
-            create=False
-        )
-        self._write_event = EventFD(token.write_eventfd, 'w')
-        self._wrap_event = EventFD(token.wrap_eventfd, 'r')
-        self._ptr = start_ptr
-
-    @property
-    def key(self) -> str:
-        return self._shm.name
-
-    @property
-    def size(self) -> int:
-        return self._shm.size
-
-    @property
-    def ptr(self) -> int:
-        return self._ptr
-
-    @property
-    def write_fd(self) -> int:
-        return self._write_event.fd
-
-    @property
-    def wrap_fd(self) -> int:
-        return self._wrap_event.fd
-
-    async def send_all(self, data: bytes | bytearray | memoryview):
-        # while data is larger than the remaining buf
-        target_ptr = self.ptr + len(data)
-        while target_ptr > self.size:
-            # write all bytes that fit
-            remaining = self.size - self.ptr
-            self._shm.buf[self.ptr:] = data[:remaining]
-            # signal write and wait for reader wrap around
-            self._write_event.write(remaining)
-            await self._wrap_event.read()
-
-            # wrap around and trim already written bytes
-            self._ptr = 0
-            data = data[remaining:]
-            target_ptr = self._ptr + len(data)
-
-        # remaining data fits on buffer
-        self._shm.buf[self.ptr:target_ptr] = data
-        self._write_event.write(len(data))
-        self._ptr = target_ptr
-
-    async def wait_send_all_might_not_block(self):
-        raise NotImplementedError
-
-    async def aclose(self):
-        self._write_event.close()
-        self._wrap_event.close()
-        self._shm.close()
-
-    async def __aenter__(self):
-        self._write_event.open()
-        self._wrap_event.open()
-        return self
-
-
-class RingBuffReceiver(trio.abc.ReceiveStream):
-    '''
-    IPC Reliable Ring Buffer receiver side implementation
-
-    `eventfd(2)` is used for wrap around sync, and also to signal
-    writes to the reader.
-
-    '''
-    def __init__(
-        self,
-        token: RBToken,
-        start_ptr: int = 0,
-        flags: int = 0
-    ):
-        token = RBToken.from_msg(token)
-        self._shm = SharedMemory(
-            name=token.shm_name,
-            size=token.buf_size,
-            create=False
-        )
-        self._write_event = EventFD(token.write_eventfd, 'w')
-        self._wrap_event = EventFD(token.wrap_eventfd, 'r')
-        self._ptr = start_ptr
-        self._flags = flags
-
-    @property
-    def key(self) -> str:
-        return self._shm.name
-
-    @property
-    def size(self) -> int:
-        return self._shm.size
-
-    @property
-    def ptr(self) -> int:
-        return self._ptr
-
-    @property
-    def write_fd(self) -> int:
-        return self._write_event.fd
-
-    @property
-    def wrap_fd(self) -> int:
-        return self._wrap_event.fd
-
-    async def receive_some(
-        self,
-        max_bytes: int | None = None,
-        nb_timeout: float = 0.1
-    ) -> memoryview:
-        # if non blocking eventfd enabled, do polling
-        # until next write, this allows signal handling
-        if self._flags | EFD_NONBLOCK:
-            delta = None
-            while delta is None:
-                try:
-                    delta = await self._write_event.read()
-
-                except OSError as e:
-                    if e.errno == 'EAGAIN':
-                        continue
-
-                    raise e
-
-        else:
-            delta = await self._write_event.read()
-
-        # fetch next segment and advance ptr
-        next_ptr = self._ptr + delta
-        segment = self._shm.buf[self._ptr:next_ptr]
-        self._ptr = next_ptr
-
-        if self.ptr == self.size:
-            # reached the end, signal wrap around
-            self._ptr = 0
-            self._wrap_event.write(1)
-
-        return segment
-
-    async def aclose(self):
-        self._write_event.close()
-        self._wrap_event.close()
-        self._shm.close()
-
-    async def __aenter__(self):
-        self._write_event.open()
-        self._wrap_event.open()
-        return self

tractor/ipc/_shm.py

@@ -1,812 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-"""
-SC friendly shared memory management geared at real-time
-processing.
-
-Support for ``numpy`` compatible array-buffers is provided but is
-considered optional within the context of this runtime-library.
-
-"""
-from __future__ import annotations
-from sys import byteorder
-import time
-from typing import Optional
-from multiprocessing import shared_memory as shm
-from multiprocessing.shared_memory import (
-    SharedMemory,
-    ShareableList,
-)
-
-from msgspec import (
-    Struct,
-    to_builtins
-)
-import tractor
-
-from tractor.ipc._mp_bs import disable_mantracker
-from tractor.log import get_logger
-
-
-_USE_POSIX = getattr(shm, '_USE_POSIX', False)
-if _USE_POSIX:
-    from _posixshmem import shm_unlink
-
-
-try:
-    import numpy as np
-    from numpy.lib import recfunctions as rfn
-    # TODO ruff complains with,
-    # warning| F401: `nptyping` imported but unused; consider using
-    # `importlib.util.find_spec` to test for availability
-    import nptyping  # noqa
-except ImportError:
-    pass
-
-
-log = get_logger(__name__)
-
-
-disable_mantracker()
-
-
-class SharedInt:
-    '''
-    Wrapper around a single entry shared memory array which
-    holds an ``int`` value used as an index counter.
-
-    '''
-    def __init__(
-        self,
-        shm: SharedMemory,
-    ) -> None:
-        self._shm = shm
-
-    @property
-    def value(self) -> int:
-        return int.from_bytes(self._shm.buf, byteorder)
-
-    @value.setter
-    def value(self, value) -> None:
-        self._shm.buf[:] = value.to_bytes(self._shm.size, byteorder)
-
-    def destroy(self) -> None:
-        if _USE_POSIX:
-            # We manually unlink to bypass all the "resource tracker"
-            # nonsense meant for non-SC systems.
-            name = self._shm.name
-            try:
-                shm_unlink(name)
-            except FileNotFoundError:
-                # might be a teardown race here?
-                log.warning(f'Shm for {name} already unlinked?')
-
-
-class NDToken(Struct, frozen=True):
-    '''
-    Internal represenation of a shared memory ``numpy`` array "token"
-    which can be used to key and load a system (OS) wide shm entry
-    and correctly read the array by type signature.
-
-    This type is msg safe.
-
-    '''
-    shm_name: str  # this servers as a "key" value
-    shm_first_index_name: str
-    shm_last_index_name: str
-    dtype_descr: tuple
-    size: int  # in struct-array index / row terms
-
-    # TODO: use nptyping here on dtypes
-    @property
-    def dtype(self) -> list[tuple[str, str, tuple[int, ...]]]:
-        return np.dtype(
-            list(
-                map(tuple, self.dtype_descr)
-            )
-        ).descr
-
-    def as_msg(self):
-        return to_builtins(self)
-
-    @classmethod
-    def from_msg(cls, msg: dict) -> NDToken:
-        if isinstance(msg, NDToken):
-            return msg
-
-        # TODO: native struct decoding
-        # return _token_dec.decode(msg)
-
-        msg['dtype_descr'] = tuple(map(tuple, msg['dtype_descr']))
-        return NDToken(**msg)
-
-
-# _token_dec = msgspec.msgpack.Decoder(NDToken)
-
-# TODO: this api?
-# _known_tokens = tractor.ActorVar('_shm_tokens', {})
-# _known_tokens = tractor.ContextStack('_known_tokens', )
-# _known_tokens = trio.RunVar('shms', {})
-
-# TODO: this should maybe be provided via
-# a `.trionics.maybe_open_context()` wrapper factory?
-# process-local store of keys to tokens
-_known_tokens: dict[str, NDToken] = {}
-
-
-def get_shm_token(key: str) -> NDToken | None:
-    '''
-    Convenience func to check if a token
-    for the provided key is known by this process.
-
-    Returns either the ``numpy`` token or a string for a shared list.
-
-    '''
-    return _known_tokens.get(key)
-
-
-def _make_token(
-    key: str,
-    size: int,
-    dtype: np.dtype,
-
-) -> NDToken:
-    '''
-    Create a serializable token that can be used
-    to access a shared array.
-
-    '''
-    return NDToken(
-        shm_name=key,
-        shm_first_index_name=key + "_first",
-        shm_last_index_name=key + "_last",
-        dtype_descr=tuple(np.dtype(dtype).descr),
-        size=size,
-    )
-
-
-class ShmArray:
-    '''
-    A shared memory ``numpy.ndarray`` API.
-
-    An underlying shared memory buffer is allocated based on
-    a user specified ``numpy.ndarray``. This fixed size array
-    can be read and written to by pushing data both onto the "front"
-    or "back" of a set index range. The indexes for the "first" and
-    "last" index are themselves stored in shared memory (accessed via
-    ``SharedInt`` interfaces) values such that multiple processes can
-    interact with the same array using a synchronized-index.
-
-    '''
-    def __init__(
-        self,
-        shmarr: np.ndarray,
-        first: SharedInt,
-        last: SharedInt,
-        shm: SharedMemory,
-        # readonly: bool = True,
-    ) -> None:
-        self._array = shmarr
-
-        # indexes for first and last indices corresponding
-        # to fille data
-        self._first = first
-        self._last = last
-
-        self._len = len(shmarr)
-        self._shm = shm
-        self._post_init: bool = False
-
-        # pushing data does not write the index (aka primary key)
-        self._write_fields: list[str] | None = None
-        dtype = shmarr.dtype
-        if dtype.fields:
-            self._write_fields = list(shmarr.dtype.fields.keys())[1:]
-
-    # TODO: ringbuf api?
-
-    @property
-    def _token(self) -> NDToken:
-        return NDToken(
-            shm_name=self._shm.name,
-            shm_first_index_name=self._first._shm.name,
-            shm_last_index_name=self._last._shm.name,
-            dtype_descr=tuple(self._array.dtype.descr),
-            size=self._len,
-        )
-
-    @property
-    def token(self) -> dict:
-        """Shared memory token that can be serialized and used by
-        another process to attach to this array.
-        """
-        return self._token.as_msg()
-
-    @property
-    def index(self) -> int:
-        return self._last.value % self._len
-
-    @property
-    def array(self) -> np.ndarray:
-        '''
-        Return an up-to-date ``np.ndarray`` view of the
-        so-far-written data to the underlying shm buffer.
-
-        '''
-        a = self._array[self._first.value:self._last.value]
-
-        # first, last = self._first.value, self._last.value
-        # a = self._array[first:last]
-
-        # TODO: eventually comment this once we've not seen it in the
-        # wild in a long time..
-        # XXX: race where first/last indexes cause a reader
-        # to load an empty array..
-        if len(a) == 0 and self._post_init:
-            raise RuntimeError('Empty array race condition hit!?')
-            # breakpoint()
-
-        return a
-
-    def ustruct(
-        self,
-        fields: Optional[list[str]] = None,
-
-        # type that all field values will be cast to
-        # in the returned view.
-        common_dtype: np.dtype = float,
-
-    ) -> np.ndarray:
-
-        array = self._array
-
-        if fields:
-            selection = array[fields]
-            # fcount = len(fields)
-        else:
-            selection = array
-            # fcount = len(array.dtype.fields)
-
-        # XXX: manual ``.view()`` attempt that also doesn't work.
-        # uview = selection.view(
-        #     dtype='<f16',
-        # ).reshape(-1, 4, order='A')
-
-        # assert len(selection) == len(uview)
-
-        u = rfn.structured_to_unstructured(
-            selection,
-            # dtype=float,
-            copy=True,
-        )
-
-        # unstruct = np.ndarray(u.shape, dtype=a.dtype, buffer=shm.buf)
-        # array[:] = a[:]
-        return u
-        # return ShmArray(
-        #     shmarr=u,
-        #     first=self._first,
-        #     last=self._last,
-        #     shm=self._shm
-        # )
-
-    def last(
-        self,
-        length: int = 1,
-
-    ) -> np.ndarray:
-        '''
-        Return the last ``length``'s worth of ("row") entries from the
-        array.
-
-        '''
-        return self.array[-length:]
-
-    def push(
-        self,
-        data: np.ndarray,
-
-        field_map: Optional[dict[str, str]] = None,
-        prepend: bool = False,
-        update_first: bool = True,
-        start: int | None = None,
-
-    ) -> int:
-        '''
-        Ring buffer like "push" to append data
-        into the buffer and return updated "last" index.
-
-        NB: no actual ring logic yet to give a "loop around" on overflow
-        condition, lel.
-
-        '''
-        length = len(data)
-
-        if prepend:
-            index = (start or self._first.value) - length
-
-            if index < 0:
-                raise ValueError(
-                    f'Array size of {self._len} was overrun during prepend.\n'
-                    f'You have passed {abs(index)} too many datums.'
-                )
-
-        else:
-            index = start if start is not None else self._last.value
-
-        end = index + length
-
-        if field_map:
-            src_names, dst_names = zip(*field_map.items())
-        else:
-            dst_names = src_names = self._write_fields
-
-        try:
-            self._array[
-                list(dst_names)
-            ][index:end] = data[list(src_names)][:]
-
-            # NOTE: there was a race here between updating
-            # the first and last indices and when the next reader
-            # tries to access ``.array`` (which due to the index
-            # overlap will be empty). Pretty sure we've fixed it now
-            # but leaving this here as a reminder.
-            if (
-                prepend
-                and update_first
-                and length
-            ):
-                assert index < self._first.value
-
-            if (
-                index < self._first.value
-                and update_first
-            ):
-                assert prepend, 'prepend=True not passed but index decreased?'
-                self._first.value = index
-
-            elif not prepend:
-                self._last.value = end
-
-            self._post_init = True
-            return end
-
-        except ValueError as err:
-            if field_map:
-                raise
-
-            # should raise if diff detected
-            self.diff_err_fields(data)
-            raise err
-
-    def diff_err_fields(
-        self,
-        data: np.ndarray,
-    ) -> None:
-        # reraise with any field discrepancy
-        our_fields, their_fields = (
-            set(self._array.dtype.fields),
-            set(data.dtype.fields),
-        )
-
-        only_in_ours = our_fields - their_fields
-        only_in_theirs = their_fields - our_fields
-
-        if only_in_ours:
-            raise TypeError(
-                f"Input array is missing field(s): {only_in_ours}"
-            )
-        elif only_in_theirs:
-            raise TypeError(
-                f"Input array has unknown field(s): {only_in_theirs}"
-            )
-
-    # TODO: support "silent" prepends that don't update ._first.value?
-    def prepend(
-        self,
-        data: np.ndarray,
-    ) -> int:
-        end = self.push(data, prepend=True)
-        assert end
-
-    def close(self) -> None:
-        self._first._shm.close()
-        self._last._shm.close()
-        self._shm.close()
-
-    def destroy(self) -> None:
-        if _USE_POSIX:
-            # We manually unlink to bypass all the "resource tracker"
-            # nonsense meant for non-SC systems.
-            shm_unlink(self._shm.name)
-
-        self._first.destroy()
-        self._last.destroy()
-
-    def flush(self) -> None:
-        # TODO: flush to storage backend like markestore?
-        ...
-
-
-def open_shm_ndarray(
-    size: int,
-    key: str | None = None,
-    dtype: np.dtype | None = None,
-    append_start_index: int | None = None,
-    readonly: bool = False,
-
-) -> ShmArray:
-    '''
-    Open a memory shared ``numpy`` using the standard library.
-
-    This call unlinks (aka permanently destroys) the buffer on teardown
-    and thus should be used from the parent-most accessor (process).
-
-    '''
-    # create new shared mem segment for which we
-    # have write permission
-    a = np.zeros(size, dtype=dtype)
-    a['index'] = np.arange(len(a))
-
-    shm = SharedMemory(
-        name=key,
-        create=True,
-        size=a.nbytes
-    )
-    array = np.ndarray(
-        a.shape,
-        dtype=a.dtype,
-        buffer=shm.buf
-    )
-    array[:] = a[:]
-    array.setflags(write=int(not readonly))
-
-    token = _make_token(
-        key=key,
-        size=size,
-        dtype=dtype,
-    )
-
-    # create single entry arrays for storing an first and last indices
-    first = SharedInt(
-        shm=SharedMemory(
-            name=token.shm_first_index_name,
-            create=True,
-            size=4,  # std int
-        )
-    )
-
-    last = SharedInt(
-        shm=SharedMemory(
-            name=token.shm_last_index_name,
-            create=True,
-            size=4,  # std int
-        )
-    )
-
-    # Start the "real-time" append-updated (or "pushed-to") section
-    # after some start index: ``append_start_index``. This allows appending
-    # from a start point in the array which isn't the 0 index and looks
-    # something like,
-    # -------------------------
-    # |              |        i
-    # _________________________
-    # <-------------> <------->
-    #  history         real-time
-    #
-    # Once fully "prepended", the history section will leave the
-    # ``ShmArray._start.value: int = 0`` and the yet-to-be written
-    # real-time section will start at ``ShmArray.index: int``.
-
-    # this sets the index to nearly 2/3rds into the the length of
-    # the buffer leaving at least a "days worth of second samples"
-    # for the real-time section.
-    if append_start_index is None:
-        append_start_index = round(size * 0.616)
-
-    last.value = first.value = append_start_index
-
-    shmarr = ShmArray(
-        array,
-        first,
-        last,
-        shm,
-    )
-
-    assert shmarr._token == token
-    _known_tokens[key] = shmarr.token
-
-    # "unlink" created shm on process teardown by
-    # pushing teardown calls onto actor context stack
-    stack = tractor.current_actor().lifetime_stack
-    stack.callback(shmarr.close)
-    stack.callback(shmarr.destroy)
-
-    return shmarr
-
-
-def attach_shm_ndarray(
-    token: tuple[str, str, tuple[str, str]],
-    readonly: bool = True,
-
-) -> ShmArray:
-    '''
-    Attach to an existing shared memory array previously
-    created by another process using ``open_shared_array``.
-
-    No new shared mem is allocated but wrapper types for read/write
-    access are constructed.
-
-    '''
-    token = NDToken.from_msg(token)
-    key = token.shm_name
-
-    if key in _known_tokens:
-        assert NDToken.from_msg(_known_tokens[key]) == token, "WTF"
-
-    # XXX: ugh, looks like due to the ``shm_open()`` C api we can't
-    # actually place files in a subdir, see discussion here:
-    # https://stackoverflow.com/a/11103289
-
-    # attach to array buffer and view as per dtype
-    _err: Optional[Exception] = None
-    for _ in range(3):
-        try:
-            shm = SharedMemory(
-                name=key,
-                create=False,
-            )
-            break
-        except OSError as oserr:
-            _err = oserr
-            time.sleep(0.1)
-    else:
-        if _err:
-            raise _err
-
-    shmarr = np.ndarray(
-        (token.size,),
-        dtype=token.dtype,
-        buffer=shm.buf
-    )
-    shmarr.setflags(write=int(not readonly))
-
-    first = SharedInt(
-        shm=SharedMemory(
-            name=token.shm_first_index_name,
-            create=False,
-            size=4,  # std int
-        ),
-    )
-    last = SharedInt(
-        shm=SharedMemory(
-            name=token.shm_last_index_name,
-            create=False,
-            size=4,  # std int
-        ),
-    )
-
-    # make sure we can read
-    first.value
-
-    sha = ShmArray(
-        shmarr,
-        first,
-        last,
-        shm,
-    )
-    # read test
-    sha.array
-
-    # Stash key -> token knowledge for future queries
-    # via `maybe_opepn_shm_array()` but only after we know
-    # we can attach.
-    if key not in _known_tokens:
-        _known_tokens[key] = token
-
-    # "close" attached shm on actor teardown
-    tractor.current_actor().lifetime_stack.callback(sha.close)
-
-    return sha
-
-
-def maybe_open_shm_ndarray(
-    key: str,  # unique identifier for segment
-    size: int,
-    dtype: np.dtype | None = None,
-    append_start_index: int = 0,
-    readonly: bool = True,
-
-) -> tuple[ShmArray, bool]:
-    '''
-    Attempt to attach to a shared memory block using a "key" lookup
-    to registered blocks in the users overall "system" registry
-    (presumes you don't have the block's explicit token).
-
-    This function is meant to solve the problem of discovering whether
-    a shared array token has been allocated or discovered by the actor
-    running in **this** process. Systems where multiple actors may seek
-    to access a common block can use this function to attempt to acquire
-    a token as discovered by the actors who have previously stored
-    a "key" -> ``NDToken`` map in an actor local (aka python global)
-    variable.
-
-    If you know the explicit ``NDToken`` for your memory segment instead
-    use ``attach_shm_array``.
-
-    '''
-    try:
-        # see if we already know this key
-        token = _known_tokens[key]
-        return (
-            attach_shm_ndarray(
-                token=token,
-                readonly=readonly,
-            ),
-            False,  # not newly opened
-        )
-    except KeyError:
-        log.warning(f"Could not find {key} in shms cache")
-        if dtype:
-            token = _make_token(
-                key,
-                size=size,
-                dtype=dtype,
-            )
-        else:
-
-            try:
-                return (
-                    attach_shm_ndarray(
-                        token=token,
-                        readonly=readonly,
-                    ),
-                    False,
-                )
-            except FileNotFoundError:
-                log.warning(f"Could not attach to shm with token {token}")
-
-        # This actor does not know about memory
-        # associated with the provided "key".
-        # Attempt to open a block and expect
-        # to fail if a block has been allocated
-        # on the OS by someone else.
-        return (
-            open_shm_ndarray(
-                key=key,
-                size=size,
-                dtype=dtype,
-                append_start_index=append_start_index,
-                readonly=readonly,
-            ),
-            True,
-        )
-
-
-class ShmList(ShareableList):
-    '''
-    Carbon copy of ``.shared_memory.ShareableList`` with a few
-    enhancements:
-
-    - readonly mode via instance var flag  `._readonly: bool`
-    - ``.__getitem__()`` accepts ``slice`` inputs
-    - exposes the underlying buffer "name" as a ``.key: str``
-
-    '''
-    def __init__(
-        self,
-        sequence: list | None = None,
-        *,
-        name: str | None = None,
-        readonly: bool = True
-
-    ) -> None:
-        self._readonly = readonly
-        self._key = name
-        return super().__init__(
-            sequence=sequence,
-            name=name,
-        )
-
-    @property
-    def key(self) -> str:
-        return self._key
-
-    @property
-    def readonly(self) -> bool:
-        return self._readonly
-
-    def __setitem__(
-        self,
-        position,
-        value,
-
-    ) -> None:
-
-        # mimick ``numpy`` error
-        if self._readonly:
-            raise ValueError('assignment destination is read-only')
-
-        return super().__setitem__(position, value)
-
-    def __getitem__(
-        self,
-        indexish,
-    ) -> list:
-
-        # NOTE: this is a non-writeable view (copy?) of the buffer
-        # in a new list instance.
-        if isinstance(indexish, slice):
-            return list(self)[indexish]
-
-        return super().__getitem__(indexish)
-
-    # TODO: should we offer a `.array` and `.push()` equivalent
-    # to the `ShmArray`?
-    # currently we have the following limitations:
-    # - can't write slices of input using traditional slice-assign
-    #   syntax due to the ``ShareableList.__setitem__()`` implementation.
-    # - ``list(shmlist)`` returns a non-mutable copy instead of
-    #   a writeable view which would be handier numpy-style ops.
-
-
-def open_shm_list(
-    key: str,
-    sequence: list | None = None,
-    size: int = int(2 ** 10),
-    dtype: float | int | bool | str | bytes | None = float,
-    readonly: bool = True,
-
-) -> ShmList:
-
-    if sequence is None:
-        default = {
-            float: 0.,
-            int: 0,
-            bool: True,
-            str: 'doggy',
-            None: None,
-        }[dtype]
-        sequence = [default] * size
-
-    shml = ShmList(
-        sequence=sequence,
-        name=key,
-        readonly=readonly,
-    )
-
-    # "close" attached shm on actor teardown
-    try:
-        actor = tractor.current_actor()
-        actor.lifetime_stack.callback(shml.shm.close)
-        actor.lifetime_stack.callback(shml.shm.unlink)
-    except RuntimeError:
-        log.warning('tractor runtime not active, skipping teardown steps')
-
-    return shml
-
-
-def attach_shm_list(
-    key: str,
-    readonly: bool = False,
-
-) -> ShmList:
-
-    return ShmList(
-        name=key,
-        readonly=readonly,
-    )

tractor/ipc/_tcp.py

@@ -1,256 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <https://www.gnu.org/licenses/>.
-'''
-TCP implementation of tractor.ipc._transport.MsgTransport protocol 
-
-'''
-from __future__ import annotations
-import ipaddress
-from typing import (
-    ClassVar,
-)
-# from contextlib import (
-#     asynccontextmanager as acm,
-# )
-
-import msgspec
-import trio
-from trio import (
-    SocketListener,
-    open_tcp_listeners,
-)
-
-from tractor.msg import MsgCodec
-from tractor.log import get_logger
-from tractor.ipc._transport import (
-    MsgTransport,
-    MsgpackTransport,
-)
-
-
-log = get_logger(__name__)
-
-
-class TCPAddress(
-    msgspec.Struct,
-    frozen=True,
-):
-    _host: str
-    _port: int
-
-    def __post_init__(self):
-        try:
-            ipaddress.ip_address(self._host)
-        except ValueError as valerr:
-            raise ValueError(
-                'Invalid {type(self).__name__}._host = {self._host!r}\n'
-            ) from valerr
-
-    proto_key: ClassVar[str] = 'tcp'
-    unwrapped_type: ClassVar[type] = tuple[str, int]
-    def_bindspace: ClassVar[str] = '127.0.0.1'
-
-    # ?TODO, actually validate ipv4/6 with stdlib's `ipaddress`
-    @property
-    def is_valid(self) -> bool:
-        '''
-        Predicate to ensure a valid socket-address pair.
-
-        '''
-        return (
-            self._port != 0
-            and
-            (ipaddr := ipaddress.ip_address(self._host))
-            and not (
-                ipaddr.is_reserved
-                or
-                ipaddr.is_unspecified
-                or
-                ipaddr.is_link_local
-                or
-                ipaddr.is_link_local
-                or
-                ipaddr.is_multicast
-                or
-                ipaddr.is_global
-            )
-        )
-        # ^XXX^ see various properties of invalid addrs here,
-        # https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Address
-
-    @property
-    def bindspace(self) -> str:
-        return self._host
-
-    @property
-    def domain(self) -> str:
-        return self._host
-
-    @classmethod
-    def from_addr(
-        cls,
-        addr: tuple[str, int]
-    ) -> TCPAddress:
-        match addr:
-            case (str(), int()):
-                return TCPAddress(addr[0], addr[1])
-            case _:
-                raise ValueError(
-                    f'Invalid unwrapped address for {cls}\n'
-                    f'{addr}\n'
-                )
-
-    def unwrap(self) -> tuple[str, int]:
-        return (
-            self._host,
-            self._port,
-        )
-
-    @classmethod
-    def get_random(
-        cls,
-        bindspace: str = def_bindspace,
-    ) -> TCPAddress:
-        return TCPAddress(bindspace, 0)
-
-    @classmethod
-    def get_root(cls) -> TCPAddress:
-        return TCPAddress(
-            '127.0.0.1',
-            1616,
-        )
-
-    def __repr__(self) -> str:
-        return (
-            f'{type(self).__name__}[{self.unwrap()}]'
-        )
-
-    @classmethod
-    def get_transport(
-        cls,
-        codec: str = 'msgpack',
-    ) -> MsgTransport:
-        match codec:
-            case 'msgspack':
-                return MsgpackTCPStream
-            case _:
-                raise ValueError(
-                    f'No IPC transport with {codec!r} supported !'
-                )
-
-
-async def start_listener(
-    addr: TCPAddress,
-    **kwargs,
-) -> SocketListener:
-    '''
-    Start a TCP socket listener on the given `TCPAddress`.
-
-    '''
-    log.info(
-        f'Attempting to bind TCP socket\n'
-        f'>[\n'
-        f'|_{addr}\n'
-    )
-    # ?TODO, maybe we should just change the lower-level call this is
-    # using internall per-listener?
-    listeners: list[SocketListener] = await open_tcp_listeners(
-        host=addr._host,
-        port=addr._port,
-        **kwargs
-    )
-    # NOTE, for now we don't expect non-singleton-resolving
-    # domain-addresses/multi-homed-hosts.
-    # (though it is supported by `open_tcp_listeners()`)
-    assert len(listeners) == 1
-    listener = listeners[0]
-    host, port = listener.socket.getsockname()[:2]
-
-    log.info(
-        f'Listening on TCP socket\n'
-        f'[>\n'
-        f' |_{addr}\n'
-    )
-    return listener
-
-
-# TODO: typing oddity.. not sure why we have to inherit here, but it
-# seems to be an issue with `get_msg_transport()` returning
-# a `Type[Protocol]`; probably should make a `mypy` issue?
-class MsgpackTCPStream(MsgpackTransport):
-    '''
-    A ``trio.SocketStream`` delivering ``msgpack`` formatted data
-    using the ``msgspec`` codec lib.
-
-    '''
-    address_type = TCPAddress
-    layer_key: int = 4
-
-    @property
-    def maddr(self) -> str:
-        host, port = self.raddr.unwrap()
-        return (
-            # TODO, use `ipaddress` from stdlib to handle
-            # first detecting which of `ipv4/6` before
-            # choosing the routing prefix part.
-            f'/ipv4/{host}'
-
-            f'/{self.address_type.proto_key}/{port}'
-            # f'/{self.chan.uid[0]}'
-            # f'/{self.cid}'
-
-            # f'/cid={cid_head}..{cid_tail}'
-            # TODO: ? not use this ^ right ?
-        )
-
-    def connected(self) -> bool:
-        return self.stream.socket.fileno() != -1
-
-    @classmethod
-    async def connect_to(
-        cls,
-        destaddr: TCPAddress,
-        prefix_size: int = 4,
-        codec: MsgCodec|None = None,
-        **kwargs
-    ) -> MsgpackTCPStream:
-        stream = await trio.open_tcp_stream(
-            *destaddr.unwrap(),
-            **kwargs
-        )
-        return MsgpackTCPStream(
-            stream,
-            prefix_size=prefix_size,
-            codec=codec
-        )
-
-    @classmethod
-    def get_stream_addrs(
-        cls,
-        stream: trio.SocketStream
-    ) -> tuple[
-        TCPAddress,
-        TCPAddress,
-    ]:
-        # TODO, what types are these?
-        lsockname = stream.socket.getsockname()
-        l_sockaddr: tuple[str, int] = tuple(lsockname[:2])
-        rsockname = stream.socket.getpeername()
-        r_sockaddr: tuple[str, int] = tuple(rsockname[:2])
-        return (
-            TCPAddress.from_addr(l_sockaddr),
-            TCPAddress.from_addr(r_sockaddr),
-        )