Important RingBuffBytesSender fix on non batched mode! & downgrade nix-shell python to lowest supported

Catch trio cancellation on RingBuffReceiver bg eof listener task, add batched mode to RingBuffBytesSender
Add direct read method on EventFD
2025-03-27 19:14:21 -03:00 · 2025-03-27 19:14:21 -03:00 · 2025-03-27 19:14:21 -03:00 · 2025-03-27 19:14:21 -03:00 · 2025-03-27 19:14:21 -03:00 · 2025-03-27 19:14:21 -03:00
37 changed files with 4779 additions and 1653 deletions
--- a/default.nix
+++ b/default.nix
@ -0,0 +1,18 @@
 { pkgs ? import <nixpkgs> {} }:
 let
  nativeBuildInputs = with pkgs; [
    stdenv.cc.cc.lib
    uv
  ];
 in
 pkgs.mkShell {
  inherit nativeBuildInputs;
  LD_LIBRARY_PATH = pkgs.lib.makeLibraryPath nativeBuildInputs;
  shellHook = ''
    set -e
    uv venv .venv --python=3.11
  '';
 }
--- a/pyproject.toml
+++ b/pyproject.toml
@ -45,6 +45,7 @@ dependencies = [
  "pdbp>=1.6,<2", # windows only (from `pdbp`)
  # typed IPC msging
  "msgspec>=0.19.0",
  "cffi>=1.17.1",
 ]
 # ------ project ------
--- a/tests/test_caps_based_msging.py
+++ b/tests/test_caps_based_msging.py
@ -1,917 +0,0 @@
 '''
 Low-level functional audits for our
 "capability based messaging"-spec feats.
 B~)
 '''
 import typing
 from typing import (
    Any,
    Type,
    Union,
 )
 from msgspec import (
    structs,
    msgpack,
    Struct,
    ValidationError,
 )
 import pytest
 import tractor
 from tractor import (
    _state,
    MsgTypeError,
    Context,
 )
 from tractor.msg import (
    _codec,
    _ctxvar_MsgCodec,
    NamespacePath,
    MsgCodec,
    mk_codec,
    apply_codec,
    current_codec,
 )
 from tractor.msg.types import (
    _payload_msgs,
    log,
    PayloadMsg,
    Started,
    mk_msg_spec,
 )
 import trio
 def mk_custom_codec(
    pld_spec: Union[Type]|Any,
    add_hooks: bool,
 ) -> MsgCodec:
    '''
    Create custom `msgpack` enc/dec-hooks and set a `Decoder`
    which only loads `pld_spec` (like `NamespacePath`) types.
    '''
    uid: tuple[str, str] = tractor.current_actor().uid
    # 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
    def enc_nsp(obj: Any) -> Any:
        print(f'{uid} ENC HOOK')
        match obj:
            case NamespacePath():
                print(
                    f'{uid}: `NamespacePath`-Only ENCODE?\n'
                    f'obj-> `{obj}`: {type(obj)}\n'
                )
                # if type(obj) != NamespacePath:
                #     breakpoint()
                return str(obj)
        print(
            f'{uid}\n'
            'CUSTOM ENCODE\n'
            f'obj-arg-> `{obj}`: {type(obj)}\n'
        )
        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:
        print(
            f'{uid}\n'
            'CUSTOM DECODE\n'
            f'type-arg-> {obj_type}\n'
            f'obj-arg-> `{obj}`: {type(obj)}\n'
        )
        nsp = None
        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)
    nsp_codec: MsgCodec = mk_codec(
        ipc_pld_spec=pld_spec,
        # 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?
        dec_hook=dec_nsp if add_hooks else None,
    )
    return nsp_codec
 def chk_codec_applied(
    expect_codec: MsgCodec,
    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]
    # 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:
        enter_value is same_codec
 def iter_maybe_sends(
    send_items: dict[Union[Type], Any] | list[tuple],
    ipc_pld_spec: Union[Type] | Any,
    add_codec_hooks: bool,
    codec: MsgCodec|None = None,
 ) -> tuple[Any, bool]:
    if isinstance(send_items, dict):
        send_items = send_items.items()
    for (
        send_type_spec,
        send_value,
    ) in send_items:
        expect_roundtrip: bool = False
        # values-to-typespec santiy
        send_type = type(send_value)
        assert send_type == send_type_spec or (
            (subtypes := getattr(send_type_spec, '__args__', None))
            and send_type in subtypes
        )
        spec_subtypes: set[Union[Type]] = (
             getattr(
                 ipc_pld_spec,
                 '__args__',
                 {ipc_pld_spec,},
             )
        )
        send_in_spec: bool = (
            send_type == ipc_pld_spec
            or (
                ipc_pld_spec != Any
                and  # presume `Union` of types
                send_type in spec_subtypes
            )
            or (
                ipc_pld_spec == Any
                and
                send_type != NamespacePath
            )
        )
        expect_roundtrip = (
            send_in_spec
            # any spec should support all other
            # builtin py values that we send
            # except our custom nsp type which
            # we should be able to send as long
            # as we provide the custom codec hooks.
            or (
                ipc_pld_spec == Any
                and
                send_type == NamespacePath
                and
                add_codec_hooks
            )
        )
        if codec is not None:
            # XXX FIRST XXX ensure roundtripping works
            # before touching any IPC primitives/APIs.
            wire_bytes: bytes = codec.encode(
                Started(
                    cid='blahblah',
                    pld=send_value,
                )
            )
            # NOTE: demonstrates the decoder loading
            # to via our native SCIPP msg-spec
            # (structurred-conc-inter-proc-protocol)
            # implemented as per,
            try:
                msg: Started = codec.decode(wire_bytes)
                if not expect_roundtrip:
                    pytest.fail(
                        f'NOT-EXPECTED able to roundtrip value given spec:\n'
                        f'ipc_pld_spec -> {ipc_pld_spec}\n'
                        f'value -> {send_value}: {send_type}\n'
                    )
                pld = msg.pld
                assert pld == send_value
            except ValidationError:
                if expect_roundtrip:
                    pytest.fail(
                        f'EXPECTED to roundtrip value given spec:\n'
                        f'ipc_pld_spec -> {ipc_pld_spec}\n'
                        f'value -> {send_value}: {send_type}\n'
                    )
        yield (
            str(send_type),
            send_value,
            expect_roundtrip,
        )
 def dec_type_union(
    type_names: list[str],
 ) -> Type:
    '''
    Look up types by name, compile into a list and then create and
    return a `typing.Union` from the full set.
    '''
    import importlib
    types: list[Type] = []
    for type_name in type_names:
        for mod in [
            typing,
            importlib.import_module(__name__),
        ]:
            if type_ref := getattr(
                mod,
                type_name,
                False,
            ):
                types.append(type_ref)
    # special case handling only..
    # ipc_pld_spec: Union[Type] = eval(
    #     pld_spec_str,
    #     {},  # globals
    #     {'typing': typing},  # locals
    # )
    return Union[*types]
 def enc_type_union(
    union_or_type: Union[Type]|Type,
 ) -> list[str]:
    '''
    Encode a type-union or single type to a list of type-name-strings
    ready for IPC interchange.
    '''
    type_strs: list[str] = []
    for typ in getattr(
        union_or_type,
        '__args__',
        {union_or_type,},
    ):
        type_strs.append(typ.__qualname__)
    return type_strs
@tractor.context
 async def send_back_values(
    ctx: Context,
    expect_debug: bool,
    pld_spec_type_strs: list[str],
    add_hooks: bool,
    started_msg_bytes: bytes,
    expect_ipc_send: dict[str, tuple[Any, 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
    # debug mode sanity check (prolly superfluous but, meh)
    assert expect_debug == _state.debug_mode()
    # init state in sub-actor should be default
    chk_codec_applied(
        expect_codec=_codec._def_tractor_codec,
    )
    # load pld spec from input str
    ipc_pld_spec = dec_type_union(
        pld_spec_type_strs,
    )
    pld_spec_str = str(ipc_pld_spec)
    # same as on parent side config.
    nsp_codec: MsgCodec = mk_custom_codec(
        pld_spec=ipc_pld_spec,
        add_hooks=add_hooks,
    )
    with (
        apply_codec(nsp_codec) as codec,
    ):
        chk_codec_applied(
            expect_codec=nsp_codec,
            enter_value=codec,
        )
        print(
            f'{uid}: attempting `Started`-bytes DECODE..\n'
        )
        try:
            msg: Started = nsp_codec.decode(started_msg_bytes)
            expected_pld_spec_str: str = msg.pld
            assert pld_spec_str == expected_pld_spec_str
        # 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 ValidationError:
            # NOTE: only in the `Any` spec case do we expect this to
            # work since otherwise no spec covers a plain-ol'
            # `.pld: str`
            if pld_spec_str == 'Any':
                raise
            else:
                print(
                    f'{uid}: (correctly) unable to DECODE `Started`-bytes\n'
                    f'{started_msg_bytes}\n'
                )
        iter_send_val_items = iter(expect_ipc_send.values())
        sent: list[Any] = []
        for send_value, expect_send in iter_send_val_items:
            try:
                print(
                    f'{uid}: attempting to `.started({send_value})`\n'
                    f'=> expect_send: {expect_send}\n'
                    f'SINCE, ipc_pld_spec: {ipc_pld_spec}\n'
                    f'AND, codec: {codec}\n'
                )
                await ctx.started(send_value)
                sent.append(send_value)
                if not expect_send:
                    # XXX NOTE XXX THIS WON'T WORK WITHOUT SPECIAL
                    # `str` handling! or special debug mode IPC
                    # msgs!
                    await tractor.pause()
                    raise RuntimeError(
                        f'NOT-EXPECTED able to roundtrip value given spec:\n'
                        f'ipc_pld_spec -> {ipc_pld_spec}\n'
                        f'value -> {send_value}: {type(send_value)}\n'
                    )
                break  # move on to streaming block..
            except tractor.MsgTypeError:
                await tractor.pause()
                if expect_send:
                    raise RuntimeError(
                        f'EXPECTED to `.started()` value given spec:\n'
                        f'ipc_pld_spec -> {ipc_pld_spec}\n'
                        f'value -> {send_value}: {type(send_value)}\n'
                    )
        async with ctx.open_stream() as ipc:
            print(
                f'{uid}: Entering streaming block to send remaining values..'
            )
            for send_value, expect_send in iter_send_val_items:
                send_type: Type = type(send_value)
                print(
                    '------ - ------\n'
                    f'{uid}: SENDING NEXT VALUE\n'
                    f'ipc_pld_spec: {ipc_pld_spec}\n'
                    f'expect_send: {expect_send}\n'
                    f'val: {send_value}\n'
                    '------ - ------\n'
                )
                try:
                    await ipc.send(send_value)
                    print(f'***\n{uid}-CHILD sent {send_value!r}\n***\n')
                    sent.append(send_value)
                    # NOTE: should only raise above on
                    # `.started()` or a `Return`
                    # if not expect_send:
                    #     raise RuntimeError(
                    #         f'NOT-EXPECTED able to roundtrip value given spec:\n'
                    #         f'ipc_pld_spec -> {ipc_pld_spec}\n'
                    #         f'value -> {send_value}: {send_type}\n'
                    #     )
                except ValidationError:
                    print(f'{uid} FAILED TO SEND {send_value}!')
                    # await tractor.pause()
                    if expect_send:
                        raise RuntimeError(
                            f'EXPECTED to roundtrip value given spec:\n'
                            f'ipc_pld_spec -> {ipc_pld_spec}\n'
                            f'value -> {send_value}: {send_type}\n'
                        )
                    # continue
            else:
                print(
                    f'{uid}: finished sending all values\n'
                    'Should be exiting stream block!\n'
                )
        print(f'{uid}: exited streaming block!')
        # TODO: this won't be true bc in streaming phase we DO NOT
        # msgspec check outbound msgs!
        # -[ ] once we implement the receiver side `InvalidMsg`
        #   then we can expect it here?
        # assert (
        #     len(sent)
        #     ==
        #     len([val
        #          for val, expect in
        #          expect_ipc_send.values()
        #          if expect is True])
        # )
 def ex_func(*args):
    print(f'ex_func({args})')
@pytest.mark.parametrize(
    'ipc_pld_spec',
    [
        Any,
        NamespacePath,
        NamespacePath|None,  # the "maybe" spec Bo
    ],
    ids=[
        'any_type',
        'nsp_type',
        'maybe_nsp_type',
    ]
 )
@pytest.mark.parametrize(
    'add_codec_hooks',
    [
        True,
        False,
    ],
    ids=['use_codec_hooks', 'no_codec_hooks'],
 )
 def test_codec_hooks_mod(
    debug_mode: bool,
    ipc_pld_spec: Union[Type]|Any,
    # send_value: None|str|NamespacePath,
    add_codec_hooks: bool,
 ):
    '''
    Audit the `.msg.MsgCodec` override apis details given our impl
    uses `contextvars` to accomplish per `trio` task codec
    application around an inter-proc-task-comms context.
    '''
    async def main():
        nsp = NamespacePath.from_ref(ex_func)
        send_items: dict[Union, Any] = {
            Union[None]: None,
            Union[NamespacePath]: nsp,
            Union[str]: str(nsp),
        }
        # init default state for actor
        chk_codec_applied(
            expect_codec=_codec._def_tractor_codec,
        )
        async with tractor.open_nursery(
            debug_mode=debug_mode,
        ) as an:
            p: tractor.Portal = await an.start_actor(
                'sub',
                enable_modules=[__name__],
            )
            # TODO: 2 cases:
            # - codec not modified -> decode nsp as `str`
            # - codec modified with hooks -> decode nsp as
            #   `NamespacePath`
            nsp_codec: MsgCodec = mk_custom_codec(
                pld_spec=ipc_pld_spec,
                add_hooks=add_codec_hooks,
            )
            with apply_codec(nsp_codec) as codec:
                chk_codec_applied(
                    expect_codec=nsp_codec,
                    enter_value=codec,
                )
                expect_ipc_send: dict[str, tuple[Any, bool]] = {}
                report: str = (
                    'Parent report on send values with\n'
                    f'ipc_pld_spec: {ipc_pld_spec}\n'
                    '       ------ - ------\n'
                )
                for val_type_str, val, expect_send in iter_maybe_sends(
                    send_items,
                    ipc_pld_spec,
                    add_codec_hooks=add_codec_hooks,
                ):
                    report += (
                        f'send_value: {val}: {type(val)} '
                        f'=> expect_send: {expect_send}\n'
                    )
                    expect_ipc_send[val_type_str] = (val, expect_send)
                print(
                    report +
                    '       ------ - ------\n'
                )
                assert len(expect_ipc_send) == len(send_items)
                # now try over real IPC with a the subactor
                # expect_ipc_rountrip: bool = True
                expected_started = Started(
                    cid='cid',
                    pld=str(ipc_pld_spec),
                )
                # build list of values we expect to receive from
                # the subactor.
                expect_to_send: list[Any] = [
                    val
                    for val, expect_send in expect_ipc_send.values()
                    if expect_send
                ]
                pld_spec_type_strs: list[str] = enc_type_union(ipc_pld_spec)
                # XXX should raise an mte (`MsgTypeError`)
                # when `add_codec_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?
                if not add_codec_hooks:
                    try:
                        async with p.open_context(
                            send_back_values,
                            expect_debug=debug_mode,
                            pld_spec_type_strs=pld_spec_type_strs,
                            add_hooks=add_codec_hooks,
                            started_msg_bytes=nsp_codec.encode(expected_started),
                            # XXX NOTE bc we send a `NamespacePath` in this kwarg
                            expect_ipc_send=expect_ipc_send,
                        ) as (ctx, first):
                            pytest.fail('ctx should fail to open without custom enc_hook!?')
                    # this test passes bc we can go no further!
                    except MsgTypeError:
                        # teardown nursery
                        await p.cancel_actor()
                        return
                # TODO: send the original nsp here and
                # test with `limit_msg_spec()` above?
                # await tractor.pause()
                print('PARENT opening IPC ctx!\n')
                async with (
                    # XXX should raise an mte (`MsgTypeError`)
                    # when `add_codec_hooks == False`..
                    p.open_context(
                        send_back_values,
                        expect_debug=debug_mode,
                        pld_spec_type_strs=pld_spec_type_strs,
                        add_hooks=add_codec_hooks,
                        started_msg_bytes=nsp_codec.encode(expected_started),
                        expect_ipc_send=expect_ipc_send,
                    ) as (ctx, first),
                    ctx.open_stream() as ipc,
                ):
                    # ensure codec is still applied across
                    # `tractor.Context` + its embedded nursery.
                    chk_codec_applied(
                        expect_codec=nsp_codec,
                        enter_value=codec,
                    )
                    print(
                        'root: ENTERING CONTEXT BLOCK\n'
                        f'type(first): {type(first)}\n'
                        f'first: {first}\n'
                    )
                    expect_to_send.remove(first)
                    # TODO: explicit values we expect depending on
                    # codec config!
                    # assert first == first_val
                    # assert first == f'{__name__}:ex_func'
                    async for next_sent in ipc:
                        print(
                            'Parent: child sent next value\n'
                            f'{next_sent}: {type(next_sent)}\n'
                        )
                        if expect_to_send:
                            expect_to_send.remove(next_sent)
                        else:
                            print('PARENT should terminate stream loop + block!')
                    # all sent values should have arrived!
                    assert not expect_to_send
            await p.cancel_actor()
    trio.run(main)
 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
 def test_limit_msgspec(
    debug_mode: bool,
 ):
    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)
--- a/tests/test_context_stream_semantics.py
+++ b/tests/test_context_stream_semantics.py
@ -38,9 +38,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 caller side.
+#   call ``Context.started()`` to unblock this entry on the parent side.
-#   the callee task executes until complete and returns a final value
+#   the child task executes until complete and returns a final value
-#   which is delivered to the caller side and retreived via
+#   which is delivered to the parent side and retreived via
 #   ``Context.result()``.
 # - cancel termination:
@ -170,9 +170,9 @@ async def assert_state(value: bool):
    [False, ValueError, KeyboardInterrupt],
 )
@pytest.mark.parametrize(
-    'callee_blocks_forever',
+    'child_blocks_forever',
    [False, True],
-    ids=lambda item: f'callee_blocks_forever={item}'
+    ids=lambda item: f'child_blocks_forever={item}'
 )
@pytest.mark.parametrize(
    'pointlessly_open_stream',
@ -181,7 +181,7 @@ async def assert_state(value: bool):
 )
 def test_simple_context(
    error_parent,
-    callee_blocks_forever,
+    child_blocks_forever,
    pointlessly_open_stream,
    debug_mode: bool,
 ):
@ -204,13 +204,13 @@ def test_simple_context(
                        portal.open_context(
                            simple_setup_teardown,
                            data=10,
-                            block_forever=callee_blocks_forever,
+                            block_forever=child_blocks_forever,
                        ) as (ctx, sent),
                    ):
                        assert current_ipc_ctx() is ctx
                        assert sent == 11
-                        if callee_blocks_forever:
+                        if child_blocks_forever:
                            await portal.run(assert_state, value=True)
                        else:
                            assert await ctx.result() == 'yo'
@ -220,7 +220,7 @@ def test_simple_context(
                                if error_parent:
                                    raise error_parent
-                                if callee_blocks_forever:
+                                if child_blocks_forever:
                                    await ctx.cancel()
                                else:
                                    # in this case the stream will send a
@ -259,9 +259,9 @@ def test_simple_context(
@pytest.mark.parametrize(
-    'callee_returns_early',
+    'child_returns_early',
    [True, False],
-    ids=lambda item: f'callee_returns_early={item}'
+    ids=lambda item: f'child_returns_early={item}'
 )
@pytest.mark.parametrize(
    'cancel_method',
@ -273,14 +273,14 @@ def test_simple_context(
    [True, False],
    ids=lambda item: f'chk_ctx_result_before_exit={item}'
 )
-def test_caller_cancels(
+def test_parent_cancels(
    cancel_method: str,
    chk_ctx_result_before_exit: bool,
-    callee_returns_early: bool,
+    child_returns_early: bool,
    debug_mode: bool,
 ):
    '''
-    Verify that when the opening side of a context (aka the caller)
+    Verify that when the opening side of a context (aka the parent)
    cancels that context, the ctx does not raise a cancelled when
    either calling `.result()` or on context exit.
@ -294,7 +294,7 @@ def test_caller_cancels(
        if (
            cancel_method == 'portal'
-            and not callee_returns_early
+            and not child_returns_early
        ):
            try:
                res = await ctx.result()
@ -318,7 +318,7 @@ def test_caller_cancels(
                pytest.fail(f'should not have raised ctxc\n{ctxc}')
        # we actually get a result
-        if callee_returns_early:
+        if child_returns_early:
            assert res == 'yo'
            assert ctx.outcome is res
            assert ctx.maybe_error is None
@ -362,14 +362,14 @@ def test_caller_cancels(
            )
            timeout: float = (
                0.5
-                if not callee_returns_early
+                if not child_returns_early
                else 2
            )
            with trio.fail_after(timeout):
                async with (
                    expect_ctxc(
                        yay=(
-                            not callee_returns_early
+                            not child_returns_early
                            and cancel_method == 'portal'
                        )
                    ),
@ -377,13 +377,13 @@ def test_caller_cancels(
                    portal.open_context(
                        simple_setup_teardown,
                        data=10,
-                        block_forever=not callee_returns_early,
+                        block_forever=not child_returns_early,
                    ) as (ctx, sent),
                ):
-                    if callee_returns_early:
+                    if child_returns_early:
                        # ensure we block long enough before sending
-                        # a cancel such that the callee has already
+                        # a cancel such that the child has already
                        # returned it's result.
                        await trio.sleep(0.5)
@ -421,7 +421,7 @@ def test_caller_cancels(
            #   which should in turn cause `ctx._scope` to
            # catch any cancellation?
            if (
-                not callee_returns_early
+                not child_returns_early
                and cancel_method != 'portal'
            ):
                assert not ctx._scope.cancelled_caught
@ -430,11 +430,11 @@ def test_caller_cancels(
 # basic stream terminations:
-# - callee context closes without using stream
+# - child context closes without using stream
-# - caller context closes without using stream
+# - parent context closes without using stream
-# - caller context calls `Context.cancel()` while streaming
+# - parent context calls `Context.cancel()` while streaming
-#   is ongoing resulting in callee being cancelled
+#   is ongoing resulting in child being cancelled
-# - callee calls `Context.cancel()` while streaming and caller
+# - child calls `Context.cancel()` while streaming and parent
 #   sees stream terminated in `RemoteActorError`
 # TODO: future possible features
@ -443,7 +443,6 @@ def test_caller_cancels(
@tractor.context
 async def close_ctx_immediately(
    ctx: Context,
 ) -> None:
@ -454,13 +453,24 @@ 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_callee_closes_ctx_after_stream_open(
+async def test_child_exits_ctx_after_stream_open(
    debug_mode: bool,
    parent_send_before_receive: bool,
 ):
    '''
-    callee context closes without using stream.
+    child context closes without using stream.
    This should result in a msg sequence
    |_<root>_
@ -474,6 +484,9 @@ async def test_callee_closes_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:
@ -482,7 +495,7 @@ async def test_callee_closes_ctx_after_stream_open(
            enable_modules=[__name__],
        )
-        with trio.fail_after(0.5):
+        with trio.fail_after(timeout):
            async with portal.open_context(
                close_ctx_immediately,
@ -494,41 +507,56 @@ async def test_callee_closes_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__()``
-                        async for _ in stream:
+                        msg = 10
                        async for msg 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(0.5):
+                    with trio.fail_after(timeout):
                        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
@ -538,6 +566,10 @@ 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
@ -564,26 +596,49 @@ async def expect_cancelled(
        raise
    else:
-        assert 0, "callee wasn't cancelled !?"
+        assert 0, "child 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, True],
+    [
        False,
        'pre_stream',
        'post_stream_open',
        'post_stream_close',
    ],
    ids=lambda item: f'use_ctx_cancel_method={item}'
 )
@tractor_test
-async def test_caller_closes_ctx_after_callee_opens_stream(
+async def test_parent_exits_ctx_after_child_enters_stream(
-    use_ctx_cancel_method: bool,
+    use_ctx_cancel_method: bool|str,
    debug_mode: bool,
    rent_wait_for_msg: bool,
    child_send_before_receive: bool,
 ):
    '''
-    caller context closes without using/opening stream
+    Parent-side of IPC context closes without sending on `MsgStream`.
    '''
    async with tractor.open_nursery(
        debug_mode=debug_mode,
    ) as an:
        root: Actor = current_actor()
        portal = await an.start_actor(
            'ctx_cancelled',
@ -592,41 +647,52 @@ async def test_caller_closes_ctx_after_callee_opens_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:
+            if use_ctx_cancel_method == 'pre_stream':
                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.
-                try:
+                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,
                ):
                    async with ctx.open_stream() as stream:
                        async for msg in stream:
                            pass
-                except tractor.ContextCancelled as ctxc:
+                        if rent_wait_for_msg:
-                    # XXX: the cause is US since we call
+                            async for msg in stream:
-                    # `Context.cancel()` just above!
+                                print(f'PARENT rx: {msg!r}\n')
-                    assert (
+                                break
                        ctxc.canceller
                        ==
                        current_actor().uid
                        ==
                        root.uid
                    )
-                    # XXX: must be propagated to __aexit__
+                        if use_ctx_cancel_method == 'post_stream_open':
-                    # and should be silently absorbed there
+                            await ctx.cancel()
                    # since we called `.cancel()` just above ;)
                    raise
-                else:
+                    if use_ctx_cancel_method == 'post_stream_close':
-                    assert 0, "Should have context cancelled?"
+                        await ctx.cancel()
                ctxc: tractor.ContextCancelled = maybe_ctxc.value
                assert (
                    ctxc.canceller
                    ==
                    current_actor().uid
                    ==
                    root.uid
                )
                # channel should still be up
                assert portal.channel.connected()
@ -637,13 +703,20 @@ async def test_caller_closes_ctx_after_callee_opens_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.2):
+                    with trio.fail_after(
-                        await ctx.result()
+                        0.5  # if not debug_mode else 999
                    ):
                        res = await ctx.wait_for_result()
                        assert res is not tractor._context.Unresolved
                        assert 0, "Callee should have blocked!?"
                except trio.TooSlowError:
-                    # NO-OP -> since already called above
+                    # NO-OP -> since already triggered by
                    # `trio.fail_after()` above!
                    await ctx.cancel()
        # NOTE: local scope should have absorbed the cancellation since
@ -683,7 +756,7 @@ async def test_caller_closes_ctx_after_callee_opens_stream(
@tractor_test
-async def test_multitask_caller_cancels_from_nonroot_task(
+async def test_multitask_parent_cancels_from_nonroot_task(
    debug_mode: bool,
 ):
    async with tractor.open_nursery(
@ -735,7 +808,6 @@ async def test_multitask_caller_cancels_from_nonroot_task(
@tractor.context
 async def cancel_self(
    ctx: Context,
 ) -> None:
@ -775,11 +847,11 @@ async def cancel_self(
@tractor_test
-async def test_callee_cancels_before_started(
+async def test_child_cancels_before_started(
    debug_mode: bool,
 ):
    '''
-    Callee calls `Context.cancel()` while streaming and caller
+    Callee calls `Context.cancel()` while streaming and parent
    sees stream terminated in `ContextCancelled`.
    '''
@ -826,14 +898,13 @@ async def never_open_stream(
@tractor.context
-async def keep_sending_from_callee(
+async def keep_sending_from_child(
    ctx:  Context,
    msg_buffer_size: int|None = None,
 ) -> None:
    '''
-    Send endlessly on the calleee stream.
+    Send endlessly on the child stream.
    '''
    await ctx.started()
@ -841,7 +912,7 @@ async def keep_sending_from_callee(
        msg_buffer_size=msg_buffer_size,
    ) as stream:
        for msg in count():
-            print(f'callee sending {msg}')
+            print(f'child sending {msg}')
            await stream.send(msg)
            await trio.sleep(0.01)
@ -849,12 +920,12 @@ async def keep_sending_from_callee(
@pytest.mark.parametrize(
    'overrun_by',
    [
-        ('caller', 1, never_open_stream),
+        ('parent', 1, never_open_stream),
-        ('callee', 0, keep_sending_from_callee),
+        ('child', 0, keep_sending_from_child),
    ],
    ids=[
-         ('caller_1buf_never_open_stream'),
+         ('parent_1buf_never_open_stream'),
-         ('callee_0buf_keep_sending_from_callee'),
+         ('child_0buf_keep_sending_from_child'),
    ]
 )
 def test_one_end_stream_not_opened(
@ -885,8 +956,7 @@ def test_one_end_stream_not_opened(
                ) as (ctx, sent):
                    assert sent is None
-                    if 'caller' in overrunner:
+                    if 'parent' in overrunner:
                        async with ctx.open_stream() as stream:
                            # itersend +1 msg more then the buffer size
@ -901,7 +971,7 @@ def test_one_end_stream_not_opened(
                                await trio.sleep_forever()
                    else:
-                        # callee overruns caller case so we do nothing here
+                        # child overruns parent case so we do nothing here
                        await trio.sleep_forever()
            await portal.cancel_actor()
@ -909,19 +979,19 @@ def test_one_end_stream_not_opened(
    # 2 overrun cases and the no overrun case (which pushes right up to
    # the msg limit)
    if (
-        overrunner == 'caller'
+        overrunner == 'parent'
    ):
        with pytest.raises(tractor.RemoteActorError) as excinfo:
            trio.run(main)
        assert excinfo.value.boxed_type == StreamOverrun
-    elif overrunner == 'callee':
+    elif overrunner == 'child':
        with pytest.raises(tractor.RemoteActorError) as excinfo:
            trio.run(main)
        # TODO: embedded remote errors so that we can verify the source
-        # error? the callee delivers an error which is an overrun
+        # error? the child delivers an error which is an overrun
        # wrapped in a remote actor error.
        assert excinfo.value.boxed_type == tractor.RemoteActorError
@ -931,8 +1001,7 @@ 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,
@ -941,12 +1010,12 @@ async def echo_back_sequence(
 ) -> None:
    '''
-    Send endlessly on the calleee stream using a small buffer size
+    Send endlessly on the child stream using a small buffer size
    setting on the contex to simulate backlogging that would normally
    cause overruns.
    '''
-    # NOTE: ensure that if the caller is expecting to cancel this task
+    # NOTE: ensure that if the parent 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 = (
@ -996,18 +1065,18 @@ async def echo_back_sequence(
                if be_slow:
                    await trio.sleep(0.05)
-                print('callee waiting on next')
+                print('child waiting on next')
-            print(f'callee echoing back latest batch\n{batch}')
+            print(f'child echoing back latest batch\n{batch}')
            for msg in batch:
-                print(f'callee sending msg\n{msg}')
+                print(f'child sending msg\n{msg}')
                await stream.send(msg)
    try:
        return 'yo'
    finally:
        print(
-            'exiting callee with context:\n'
+            'exiting child with context:\n'
            f'{pformat(ctx)}\n'
        )
@ -1061,7 +1130,7 @@ def test_maybe_allow_overruns_stream(
            debug_mode=debug_mode,
        ) as an:
            portal = await an.start_actor(
-                'callee_sends_forever',
+                'child_sends_forever',
                enable_modules=[__name__],
                loglevel=loglevel,
                debug_mode=debug_mode,
--- a/tests/test_eventfd.py
+++ b/tests/test_eventfd.py
@ -0,0 +1,32 @@
 import trio
 import pytest
 from tractor.ipc import (
    open_eventfd,
    EFDReadCancelled,
    EventFD
 )
 def test_eventfd_read_cancellation():
    '''
    Ensure EventFD.read raises EFDReadCancelled if EventFD.close()
    is called.
    '''
    fd = open_eventfd()
    async def _read(event: EventFD):
        with pytest.raises(EFDReadCancelled):
            await event.read()
    async def main():
        async with trio.open_nursery() as n:
            with (
                EventFD(fd, 'w') as event,
                trio.fail_after(3)
            ):
                n.start_soon(_read, event)
                await trio.sleep(0.2)
                event.close()
    trio.run(main)
--- a/tests/test_ext_types_msgspec.py
+++ b/tests/test_ext_types_msgspec.py
@ -0,0 +1,946 @@
 '''
 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)
--- a/tests/test_ringbuf.py
+++ b/tests/test_ringbuf.py
@ -0,0 +1,423 @@
 import time
 import hashlib
 import trio
 import pytest
 import tractor
 from tractor.ipc import (
    open_ringbuf,
    attach_to_ringbuf_receiver,
    attach_to_ringbuf_sender,
    attach_to_ringbuf_stream,
    attach_to_ringbuf_channel,
    RBToken,
 )
 from tractor._testing.samples import (
    generate_single_byte_msgs,
    generate_sample_messages
 )
@tractor.context
 async def child_read_shm(
    ctx: tractor.Context,
    msg_amount: int,
    token: RBToken,
 ) -> str:
    '''
    Sub-actor used in `test_ringbuf`.
    Attach to a ringbuf and receive all messages until end of stream.
    Keep track of how many bytes received and also calculate 
    sha256 of the whole byte stream.
    Calculate and print performance stats, finally return calculated
    hash.
    '''
    await ctx.started()
    print('reader started')
    recvd_bytes = 0
    recvd_hash = hashlib.sha256()
    start_ts = time.time()
    async with attach_to_ringbuf_receiver(token) as receiver:
        async for msg in receiver:
            recvd_hash.update(msg)
            recvd_bytes += len(msg)
    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):,}')
    print(f'\treceived bytes: {recvd_bytes:,}')
    return recvd_hash.hexdigest()
@tractor.context
 async def child_write_shm(
    ctx: tractor.Context,
    msg_amount: int,
    rand_min: int,
    rand_max: int,
    token: RBToken,
 ) -> None:
    '''
    Sub-actor used in `test_ringbuf`
    Generate `msg_amount` payloads with
    `random.randint(rand_min, rand_max)` random bytes at the end,
    Calculate sha256 hash and send it to parent on `ctx.started`.
    Attach to ringbuf and send all generated messages.
    '''
    msgs, _total_bytes = generate_sample_messages(
        msg_amount,
        rand_min=rand_min,
        rand_max=rand_max,
    )
    print('writer hashing payload...')
    sent_hash = hashlib.sha256(b''.join(msgs)).hexdigest()
    print('writer done hashing.')
    await ctx.started(sent_hash)
    print('writer started')
    async with attach_to_ringbuf_sender(token, cleanup=False) as sender:
        for msg in msgs:
            await sender.send_all(msg)
    print('writer exit')
@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
 ):
    '''
    - Open a new ring buf on root actor
    - Open `child_write_shm` ctx in sub-actor which will generate a
    random payload and send its hash on `ctx.started`, finally sending
    the payload through the stream.
    - Open `child_read_shm` ctx in sub-actor which will receive the
    payload, calculate perf stats and return the hash.
    - Compare both hashes
    '''
    async def main():
        with open_ringbuf(
            'test_ringbuf',
            buf_size=buf_size
        ) as token:
            proc_kwargs = {'pass_fds': token.fds}
            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,
                        token=token,
                        msg_amount=msg_amount,
                        rand_min=rand_min,
                        rand_max=rand_max,
                    ) as (_sctx, sent_hash),
                    recv_p.open_context(
                        child_read_shm,
                        token=token,
                        msg_amount=msg_amount
                    ) as (rctx, _sent),
                ):
                    recvd_hash = await rctx.result()
                    assert sent_hash == recvd_hash
                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 attach_to_ringbuf_receiver(token) as receiver:
        await ctx.started()
        await receiver.receive_some()
 def test_reader_cancel():
    '''
    Test that a receiver blocked on eventfd(2) read responds to
    cancellation.
    '''
    async def main():
        with open_ringbuf('test_ring_cancel_reader') as token:
            async with (
                tractor.open_nursery() as an,
                attach_to_ringbuf_sender(token) as _sender,
            ):
                recv_p = await an.start_actor(
                    'ring_blocked_receiver',
                    enable_modules=[__name__],
                    proc_kwargs={
                        'pass_fds': token.fds
                    }
                )
                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 attach_to_ringbuf_sender(token) as sender:
        await ctx.started()
        await sender.send_all(b'this will wrap')
 def test_sender_cancel():
    '''
    Test that a sender blocked on eventfd(2) read responds to
    cancellation.
    '''
    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.fds
                    }
                )
                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)
 def test_receiver_max_bytes():
    '''
    Test that RingBuffReceiver.receive_some's max_bytes optional
    argument works correctly, send a msg of size 100, then
    force receive of messages with max_bytes == 1, wait until
    100 of these messages are received, then compare join of
    msgs with original message
    '''
    msg = generate_single_byte_msgs(100)
    msgs = []
    async def main():
        with open_ringbuf(
            'test_ringbuf_max_bytes',
            buf_size=10
        ) as token:
            async with (
                trio.open_nursery() as n,
                attach_to_ringbuf_sender(token, cleanup=False) as sender,
                attach_to_ringbuf_receiver(token, cleanup=False) as receiver
            ):
                async def _send_and_close():
                    await sender.send_all(msg)
                    await sender.aclose()
                n.start_soon(_send_and_close)
                while len(msgs) < len(msg):
                    msg_part = await receiver.receive_some(max_bytes=1)
                    assert len(msg_part) == 1
                    msgs.append(msg_part)
    trio.run(main)
    assert msg == b''.join(msgs)
 def test_stapled_ringbuf():
    '''
    Open two ringbufs and give tokens to tasks (swap them such that in/out tokens
    are inversed on each task) which will open the streams and use trio.StapledStream
    to have a single bidirectional stream.
    Then take turns to send and receive messages.
    '''
    msg = generate_single_byte_msgs(100)
    pair_0_msgs = []
    pair_1_msgs = []
    pair_0_done = trio.Event()
    pair_1_done = trio.Event()
    async def pair_0(token_in: RBToken, token_out: RBToken):
        async with attach_to_ringbuf_stream(
            token_in,
            token_out,
            cleanup_in=False,
            cleanup_out=False
        ) as stream:
            # first turn to send
            await stream.send_all(msg)
            # second turn to receive
            while len(pair_0_msgs) != len(msg):
                _msg = await stream.receive_some(max_bytes=1)
                pair_0_msgs.append(_msg)
            pair_0_done.set()
            await pair_1_done.wait()
    async def pair_1(token_in: RBToken, token_out: RBToken):
        async with attach_to_ringbuf_stream(
            token_in,
            token_out,
            cleanup_in=False,
            cleanup_out=False
        ) as stream:
            # first turn to receive
            while len(pair_1_msgs) != len(msg):
                _msg = await stream.receive_some(max_bytes=1)
                pair_1_msgs.append(_msg)
            # second turn to send
            await stream.send_all(msg)
            pair_1_done.set()
            await pair_0_done.wait()
    async def main():
        with tractor.ipc.open_ringbuf_pair(
            'test_stapled_ringbuf'
        ) as (token_0, token_1):
            async with trio.open_nursery() as n:
                n.start_soon(pair_0, token_0, token_1)
                n.start_soon(pair_1, token_1, token_0)
    trio.run(main)
    assert msg == b''.join(pair_0_msgs)
    assert msg == b''.join(pair_1_msgs)
@tractor.context
 async def child_channel_sender(
    ctx: tractor.Context,
    msg_amount_min: int,
    msg_amount_max: int,
    token_in: RBToken,
    token_out: RBToken
 ):
    import random
    msgs, _total_bytes = generate_sample_messages(
        random.randint(msg_amount_min, msg_amount_max),
        rand_min=256,
        rand_max=1024,
    )
    async with attach_to_ringbuf_channel(
        token_in,
        token_out
    ) as chan:
        await ctx.started(msgs)
        for msg in msgs:
            await chan.send(msg)
 def test_channel():
    msg_amount_min = 100
    msg_amount_max = 1000
    async def main():
        with tractor.ipc.open_ringbuf_pair(
            'test_ringbuf_transport'
        ) as (token_0, token_1):
            async with (
                attach_to_ringbuf_channel(token_0, token_1) as chan,
                tractor.open_nursery() as an
            ):
                recv_p = await an.start_actor(
                    'test_ringbuf_transport_sender',
                    enable_modules=[__name__],
                    proc_kwargs={
                        'pass_fds': token_0.fds + token_1.fds
                    }
                )
                async with (
                    recv_p.open_context(
                        child_channel_sender,
                        msg_amount_min=msg_amount_min,
                        msg_amount_max=msg_amount_max,
                        token_in=token_1,
                        token_out=token_0
                    ) as (ctx, msgs),
                ):
                    recv_msgs = []
                    async for msg in chan:
                        recv_msgs.append(msg)
                    await recv_p.cancel_actor()
                    assert recv_msgs == msgs
    trio.run(main)
--- a/tests/test_shm.py
+++ b/tests/test_shm.py
@ -0,0 +1,167 @@
 """
 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)
--- a/tractor/init.py
+++ b/tractor/init.py
@ -64,7 +64,7 @@ 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
+# from . import hilevel as hilevel
--- a/tractor/_context.py
+++ b/tractor/_context.py
@ -47,6 +47,9 @@ from functools import partial
 import inspect
 from pprint import pformat
 import textwrap
 from types import (
    UnionType,
 )
 from typing import (
    Any,
    AsyncGenerator,
@ -79,13 +82,14 @@ from .msg import (
    MsgType,
    NamespacePath,
    PayloadT,
    Return,
    Started,
    Stop,
    Yield,
    pretty_struct,
    _ops as msgops,
 )
-from ._ipc import (
+from .ipc import (
    Channel,
 )
 from ._streaming import (
@ -101,7 +105,7 @@ from ._state import (
 if TYPE_CHECKING:
    from ._portal import Portal
    from ._runtime import Actor
-    from ._ipc import MsgTransport
+    from .ipc import MsgTransport
    from .devx._frame_stack import (
        CallerInfo,
    )
@ -242,11 +246,13 @@ class Context:
    # a drain loop?
    # _res_scope: trio.CancelScope|None = None
    _outcome_msg: Return|Error|ContextCancelled = Unresolved
    # on a clean exit there should be a final value
    # delivered from the far end "callee" task, so
    # this value is only set on one side.
    # _result: Any | int = None
-    _result: Any|Unresolved = Unresolved
+    _result: PayloadT|Unresolved = Unresolved
    # if the local "caller"  task errors this value is always set
    # to the error that was captured in the
@ -1196,9 +1202,11 @@ class Context:
        '''
        __tracebackhide__: bool = hide_tb
-        assert self._portal, (
+        if not self._portal:
-            '`Context.wait_for_result()` can not be called from callee side!'
+            raise RuntimeError(
-        )
+                'Invalid usage of `Context.wait_for_result()`!\n'
                'Not valid on child-side IPC ctx!\n'
            )
        if self._final_result_is_set():
            return self._result
@ -1219,6 +1227,8 @@ class Context:
            # since every message should be delivered via the normal
            # `._deliver_msg()` route which will appropriately set
            # any `.maybe_error`.
            outcome_msg: Return|Error|ContextCancelled
            drained_msgs: list[MsgType]
            (
                outcome_msg,
                drained_msgs,
@ -1226,11 +1236,19 @@ class Context:
                ctx=self,
                hide_tb=hide_tb,
            )
            drained_status: str = (
                'Ctx drained to final outcome msg\n\n'
                f'{outcome_msg}\n'
            )
            # ?XXX, should already be set in `._deliver_msg()` right?
            if self._outcome_msg is not Unresolved:
                # from .devx import _debug
                # await _debug.pause()
                assert self._outcome_msg is outcome_msg
            else:
                self._outcome_msg = outcome_msg
            if drained_msgs:
                drained_status += (
                    '\n'
@ -1738,7 +1756,6 @@ class Context:
                f'{structfmt(msg)}\n'
            )
            # NOTE: if an error is deteced we should always still
            # send it through the feeder-mem-chan and expect
            # it to be raised by any context (stream) consumer
@ -1750,6 +1767,21 @@ class Context:
            # normally the task that should get cancelled/error
            # from some remote fault!
            send_chan.send_nowait(msg)
            match msg:
                case Stop():
                    if (stream := self._stream):
                        stream._stop_msg = msg
                case Return():
                    if not self._outcome_msg:
                        log.warning(
                            f'Setting final outcome msg AFTER '
                            f'`._rx_chan.send()`??\n'
                            f'\n'
                            f'{msg}'
                        )
                        self._outcome_msg = msg
            return True
        except trio.BrokenResourceError:
@ -2006,7 +2038,7 @@ async def open_context_from_portal(
            # the dialog, the `Error` msg should be raised from the `msg`
            # handling block below.
            try:
-                started_msg, first = await ctx._pld_rx.recv_msg_w_pld(
+                started_msg, first = await ctx._pld_rx.recv_msg(
                    ipc=ctx,
                    expect_msg=Started,
                    passthrough_non_pld_msgs=False,
@ -2371,7 +2403,8 @@ async def open_context_from_portal(
            # displaying `ContextCancelled` traces where the
            # cause of crash/exit IS due to something in
            # user/app code on either end of the context.
-            and not rxchan._closed
+            and
            not rxchan._closed
        ):
            # XXX NOTE XXX: and again as per above, we mask any
            # `trio.Cancelled` raised here so as to NOT mask
@ -2430,6 +2463,7 @@ async def open_context_from_portal(
        # FINALLY, remove the context from runtime tracking and
        # exit!
        log.runtime(
        # log.cancel(
            f'De-allocating IPC ctx opened with {ctx.side!r} peer \n'
            f'uid: {uid}\n'
            f'cid: {ctx.cid}\n'
@ -2485,7 +2519,6 @@ def mk_context(
        _caller_info=caller_info,
        **kwargs,
    )
    pld_rx._ctx = ctx
    ctx._result = Unresolved
    return ctx
@ -2548,7 +2581,14 @@ def context(
    name: str
    param: Type
    for name, param in annots.items():
-        if param is Context:
+        if (
            param is Context
            or (
                isinstance(param, UnionType)
                and
                Context in param.__args__
            )
        ):
            ctx_var_name: str = name
            break
    else:
--- a/tractor/_discovery.py
+++ b/tractor/_discovery.py
@ -29,7 +29,7 @@ from contextlib import asynccontextmanager as acm
 from tractor.log import get_logger
 from .trionics import gather_contexts
-from ._ipc import _connect_chan, Channel
+from .ipc import _connect_chan, Channel
 from ._portal import (
    Portal,
    open_portal,
--- a/tractor/_exceptions.py
+++ b/tractor/_exceptions.py
@ -65,7 +65,7 @@ if TYPE_CHECKING:
    from ._context import Context
    from .log import StackLevelAdapter
    from ._stream import MsgStream
-    from ._ipc import Channel
+    from .ipc import Channel
 log = get_logger('tractor')
@ -432,9 +432,13 @@ class RemoteActorError(Exception):
        Error type boxed by last actor IPC hop.
        '''
-        if self._boxed_type is None:
+        if (
            self._boxed_type is None
            and
            (ipc_msg := self._ipc_msg)
        ):
            self._boxed_type = get_err_type(
-                self._ipc_msg.boxed_type_str
+                ipc_msg.boxed_type_str
            )
        return self._boxed_type
@ -1143,6 +1147,8 @@ def unpack_error(
    which is the responsibilitiy of the caller.
    '''
    # XXX, apparently we pass all sorts of msgs here?
    # kinda odd but seems like maybe they shouldn't be?
    if not isinstance(msg, Error):
        return None
--- a/tractor/_portal.py
+++ b/tractor/_portal.py
@ -43,7 +43,7 @@ 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,
@ -184,7 +184,7 @@ class Portal:
                (
                    self._final_result_msg,
                    self._final_result_pld,
-                ) = await self._expect_result_ctx._pld_rx.recv_msg_w_pld(
+                ) = await self._expect_result_ctx._pld_rx.recv_msg(
                    ipc=self._expect_result_ctx,
                    expect_msg=Return,
                )
--- a/tractor/_root.py
+++ b/tractor/_root.py
@ -43,7 +43,7 @@ from .devx import _debug
 from . import _spawn
 from . import _state
 from . import log
-from ._ipc import _connect_chan
+from .ipc import _connect_chan
 from ._exceptions import is_multi_cancelled
--- a/tractor/_rpc.py
+++ b/tractor/_rpc.py
@ -42,7 +42,7 @@ from trio import (
    TaskStatus,
 )
-from ._ipc import Channel
+from .ipc import Channel
 from ._context import (
    Context,
 )
@ -649,6 +649,10 @@ async def _invoke(
                )
                # set and shuttle final result to "parent"-side task.
                ctx._result = res
                log.runtime(
                    f'Sending result msg and exiting {ctx.side!r}\n'
                    f'{return_msg}\n'
                )
                await chan.send(return_msg)
            # NOTE: this happens IFF `ctx._scope.cancel()` is
--- a/tractor/_runtime.py
+++ b/tractor/_runtime.py
@ -73,7 +73,7 @@ from tractor.msg import (
    pretty_struct,
    types as msgtypes,
 )
-from ._ipc import Channel
+from .ipc import Channel
 from ._context import (
    mk_context,
    Context,
@ -836,8 +836,10 @@ class Actor:
            )]
        except KeyError:
            report: str = (
-                'Ignoring invalid IPC ctx msg!\n\n'
+                'Ignoring invalid IPC msg!?\n'
-                f'<=? {uid}\n\n'
+                f'Ctx seems to not/no-longer exist??\n'
                f'\n'
                f'<=? {uid}\n'
                f'  |_{pretty_struct.pformat(msg)}\n'
            )
            match msg:
--- a/tractor/_spawn.py
+++ b/tractor/_spawn.py
@ -399,7 +399,8 @@ async def new_proc(
    *,
    infect_asyncio: bool = False,
-    task_status: TaskStatus[Portal] = trio.TASK_STATUS_IGNORED
+    task_status: TaskStatus[Portal] = trio.TASK_STATUS_IGNORED,
    proc_kwargs: dict[str, any] = {}
 ) -> None:
@ -419,6 +420,7 @@ async def new_proc(
        _runtime_vars,  # run time vars
        infect_asyncio=infect_asyncio,
        task_status=task_status,
        proc_kwargs=proc_kwargs
    )
@ -434,7 +436,8 @@ async def trio_proc(
    _runtime_vars: dict[str, Any],  # serialized and sent to _child
    *,
    infect_asyncio: bool = False,
-    task_status: TaskStatus[Portal] = trio.TASK_STATUS_IGNORED
+    task_status: TaskStatus[Portal] = trio.TASK_STATUS_IGNORED,
    proc_kwargs: dict[str, any] = {}
 ) -> None:
    '''
@ -475,7 +478,7 @@ async def trio_proc(
    proc: trio.Process|None = None
    try:
        try:
-            proc: trio.Process = await trio.lowlevel.open_process(spawn_cmd)
+            proc: trio.Process = await trio.lowlevel.open_process(spawn_cmd, **proc_kwargs)
            log.runtime(
                'Started new child\n'
                f'|_{proc}\n'
@ -640,7 +643,8 @@ async def mp_proc(
    _runtime_vars: dict[str, Any],  # serialized and sent to _child
    *,
    infect_asyncio: bool = False,
-    task_status: TaskStatus[Portal] = trio.TASK_STATUS_IGNORED
+    task_status: TaskStatus[Portal] = trio.TASK_STATUS_IGNORED,
    proc_kwargs: dict[str, any] = {}
 ) -> None:
--- a/tractor/_streaming.py
+++ b/tractor/_streaming.py
@ -45,16 +45,18 @@ from .trionics import (
    BroadcastReceiver,
 )
 from tractor.msg import (
-    # Return,
+    Error,
-    # Stop,
+    Return,
    Stop,
    MsgType,
    PayloadT,
    Yield,
 )
 if TYPE_CHECKING:
    from ._runtime import Actor
    from ._context import Context
-    from ._ipc import Channel
+    from .ipc import Channel
 log = get_logger(__name__)
@ -70,8 +72,7 @@ class MsgStream(trio.abc.Channel):
    A bidirectional message stream for receiving logically sequenced
    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:
@ -94,6 +95,9 @@ class MsgStream(trio.abc.Channel):
        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
@ -125,16 +129,67 @@ class MsgStream(trio.abc.Channel):
    def receive_nowait(
        self,
        expect_msg: MsgType = Yield,
-    ):
+    ) -> PayloadT:
        ctx: Context = self._ctx
-        return ctx._pld_rx.recv_pld_nowait(
+        (
            msg,
            pld,
        ) = ctx._pld_rx.recv_msg_nowait(
            ipc=self,
            expect_msg=expect_msg,
        )
        # ?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}'
                )
            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,
    ):
        '''
@ -154,7 +209,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
@ -165,7 +220,11 @@ class MsgStream(trio.abc.Channel):
        src_err: Exception|None = None  # orig tb
        try:
            ctx: Context = self._ctx
-            return await ctx._pld_rx.recv_pld(ipc=self)
+            pld = await ctx._pld_rx.recv_pld(
                ipc=self,
                expect_msg=Yield,
            )
            return pld
        # XXX: the stream terminates on either of:
        # - `self._rx_chan.receive()` raising  after manual closure
@ -174,7 +233,7 @@ class MsgStream(trio.abc.Channel):
        # - 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
+        #   `._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.
@ -198,11 +257,14 @@ 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`
+        #  ^^^^^^^^TODO? pass these to the `._ctx._drained_msgs:
-            # and then iterate them as part of any `.wait_for_result()` call?
+        #  deque` and then iterate them as part of any
-            #
+        #  `.wait_for_result()` call?
-            # from .devx import pause
+        #
-            # await pause()
+        # -[ ] move the match-case processing from
        #     `.receive_nowait()` instead to right here, use it from
        #     a for msg in drained:` post-proc loop?
        #
            log.warning(
                'Drained context msgs during closure\n\n'
                f'{drained}'
@ -265,9 +327,6 @@ 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
@ -279,15 +338,16 @@ 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 = self.receive_nowait(
+                maybe_final_msg: Yield|Return = self.receive_nowait(
-                    # allow_msgs=[Yield, Return],
+                    expect_msg=Yield|Return,
                    expect_msg=Yield,
                )
                if maybe_final_msg:
                    log.debug(
@ -372,8 +432,10 @@ class MsgStream(trio.abc.Channel):
        #         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 {self._ctx.side!r}-side before EoC\n'
+                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'x}}>\n'
                f'  |_{self}\n'
@ -381,9 +443,19 @@ class MsgStream(trio.abc.Channel):
            log.cancel(message)
            self._eoc = trio.EndOfChannel(message)
            if (
                (rx_chan := self._rx_chan)
                and
                (stats := rx_chan.statistics()).tasks_waiting_receive
            ):
                log.cancel(
                    f'Msg-stream is closing but there is still reader tasks,\n'
                    f'{stats}\n'
                )
        # ?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
--- a/tractor/_supervise.py
+++ b/tractor/_supervise.py
@ -141,6 +141,7 @@ class ActorNursery:
        # a `._ria_nursery` since the dependent APIs have been
        # removed!
        nursery: trio.Nursery|None = None,
        proc_kwargs: dict[str, any] = {}
    ) -> Portal:
        '''
@ -204,6 +205,7 @@ class ActorNursery:
                parent_addr,
                _rtv,  # run time vars
                infect_asyncio=infect_asyncio,
                proc_kwargs=proc_kwargs
            )
        )
@ -227,6 +229,7 @@ class ActorNursery:
        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``
@ -257,6 +260,7 @@ 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
--- a/tractor/_testing/init.py
+++ b/tractor/_testing/init.py
@ -26,6 +26,9 @@ import os
 import pathlib
 import tractor
 from tractor.devx._debug import (
    BoxedMaybeException,
 )
 from .pytest import (
    tractor_test as tractor_test
 )
@ -98,12 +101,13 @@ async def expect_ctxc(
    '''
    if yay:
        try:
-            yield
+            yield (maybe_exc := BoxedMaybeException())
            raise RuntimeError('Never raised ctxc?')
-        except tractor.ContextCancelled:
+        except tractor.ContextCancelled as ctxc:
            maybe_exc.value = ctxc
            if reraise:
                raise
            else:
                return
    else:
-        yield
+        yield (maybe_exc := BoxedMaybeException())
--- a/tractor/_testing/samples.py
+++ b/tractor/_testing/samples.py
@ -0,0 +1,81 @@
 import os
 import random
 def generate_single_byte_msgs(amount: int) -> bytes:
    '''
    Generate a byte instance of len `amount` with:
    ```
    byte_at_index(i) = (i % 10).encode()
    ```
    this results in constantly repeating sequences of:
    b'0123456789'
    '''
    return b''.join(str(i % 10).encode() for i in range(amount))
 def generate_sample_messages(
    amount: int,
    rand_min: int = 0,
    rand_max: int = 0,
    silent: bool = False,
 ) -> tuple[list[bytes], int]:
    '''
    Generate bytes msgs for tests.
    Messages will have the following format:
    ```
    b'[{i:08}]' + os.urandom(random.randint(rand_min, rand_max))
    ```
    so for message index 25:
    b'[00000025]' + random_bytes
    '''
    msgs = []
    size = 0
    log_interval = None
    if not silent:
        print(f'\ngenerating {amount} messages...')
        # calculate an apropiate log interval based on
        # max message size
        max_msg_size = 10 + rand_max
        if max_msg_size <= 32 * 1024:
            log_interval = 10_000
        else:
            log_interval = 1000
    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 > 0
            and
            i % log_interval == 0
        ):
            print(f'{i} generated')
    if not silent:
        print(f'done, {size:,} bytes in total')
    return msgs, size
--- a/tractor/devx/_debug.py
+++ b/tractor/devx/_debug.py
@ -91,7 +91,7 @@ from tractor._state import (
 if TYPE_CHECKING:
    from trio.lowlevel import Task
    from threading import Thread
-    from tractor._ipc import Channel
+    from tractor.ipc import Channel
    from tractor._runtime import (
        Actor,
    )
--- a/tractor/ipc/init.py
+++ b/tractor/ipc/init.py
@ -0,0 +1,61 @@
 # 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/>.
 import platform
 from ._transport import MsgTransport as MsgTransport
 from ._tcp import (
    get_stream_addrs as get_stream_addrs,
    MsgpackTCPStream as MsgpackTCPStream
 )
 from ._chan import (
    _connect_chan as _connect_chan,
    get_msg_transport as get_msg_transport,
    Channel as Channel
 )
 if platform.system() == 'Linux':
    from ._linux import (
        EFD_SEMAPHORE as EFD_SEMAPHORE,
        EFD_CLOEXEC as EFD_CLOEXEC,
        EFD_NONBLOCK as EFD_NONBLOCK,
        open_eventfd as open_eventfd,
        write_eventfd as write_eventfd,
        read_eventfd as read_eventfd,
        close_eventfd as close_eventfd,
        EFDReadCancelled as EFDReadCancelled,
        EventFD as EventFD,
    )
    from ._ringbuf import (
        RBToken as RBToken,
        open_ringbuf as open_ringbuf,
        RingBuffSender as RingBuffSender,
        RingBuffReceiver as RingBuffReceiver,
        open_ringbuf_pair as open_ringbuf_pair,
        attach_to_ringbuf_receiver as attach_to_ringbuf_receiver,
        attach_to_ringbuf_sender as attach_to_ringbuf_sender,
        attach_to_ringbuf_stream as attach_to_ringbuf_stream,
        RingBuffBytesSender as RingBuffBytesSender,
        RingBuffBytesReceiver as RingBuffBytesReceiver,
        RingBuffChannel as RingBuffChannel,
        attach_to_ringbuf_schannel as attach_to_ringbuf_schannel,
        attach_to_ringbuf_rchannel as attach_to_ringbuf_rchannel,
        attach_to_ringbuf_channel as attach_to_ringbuf_channel,
    )
--- a/tractor/ipc/_chan.py
+++ b/tractor/ipc/_chan.py
@ -0,0 +1,404 @@
 # 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
 )
 import trio
 from tractor.ipc._transport import MsgTransport
 from tractor.ipc._tcp import (
    MsgpackTCPStream,
    get_stream_addrs
 )
 from tractor.log import get_logger
 from tractor._exceptions import (
    MsgTypeError,
    pack_from_raise,
 )
 from tractor.msg import MsgCodec
 log = get_logger(__name__)
 _is_windows = platform.system() == 'Windows'
 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._aiter_msgs = self._iter_msgs()
        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,
        # XXX optionally provided codec pair for `msgspec`:
        # https://jcristharif.com/msgspec/extending.html#mapping-to-from-native-types
        codec: MsgCodec|None = None,
    ) -> MsgTransport:
        type_key = (
            type_key
            or
            self._transport_key
        )
        # get transport type, then
        self._transport = get_msg_transport(
            type_key
        # instantiate an instance of the msg-transport
        )(
            stream,
            codec=codec,
        )
        return self._transport
    @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 __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
    # 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 = False,
    ) -> 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 as _err:
            err = _err  # bind for introspection
            if not isinstance(_err, MsgTypeError):
                # assert err
                __tracebackhide__: bool = False
            else:
                assert err.cid
            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.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._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
@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
    with trio.CancelScope(shield=True):
        await chan.aclose()
--- a/tractor/ipc/_linux.py
+++ b/tractor/ipc/_linux.py
@ -0,0 +1,187 @@
 # 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 EFDReadCancelled(Exception):
    ...
 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
        self._cscope: trio.CancelScope | None = 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:
        '''
        Async wrapper for `read_eventfd(self.fd)`
        `trio.to_thread.run_sync` is used, need to use a `trio.CancelScope`
        in order to make it cancellable when `self.close()` is called.
        '''
        self._cscope = trio.CancelScope()
        with self._cscope:
            return await trio.to_thread.run_sync(
                read_eventfd, self._fd,
                abandon_on_cancel=True
            )
        if self._cscope.cancelled_caught:
            raise EFDReadCancelled
        self._cscope = None
    def read_direct(self) -> int:
        '''
        Direct call to `read_eventfd(self.fd)`, unless `eventfd` was
        opened with `EFD_NONBLOCK` its gonna block the thread.
        '''
        return read_eventfd(self._fd)
    def open(self):
        self._fobj = os.fdopen(self._fd, self._omode)
    def close(self):
        if self._fobj:
            try:
                self._fobj.close()
            except OSError:
                ...
        if self._cscope:
            self._cscope.cancel()
    def __enter__(self):
        self.open()
        return self
    def __exit__(self, exc_type, exc_value, traceback):
        self.close()
--- a/tractor/ipc/_mp_bs.py
+++ b/tractor/ipc/_mp_bs.py
@ -0,0 +1,45 @@
 # 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
--- a/tractor/ipc/_ringbuf.py
+++ b/tractor/ipc/_ringbuf.py
@ -0,0 +1,651 @@
 # 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
 import struct
 from typing import (
    ContextManager,
    AsyncContextManager
 )
 from contextlib import (
    contextmanager as cm,
    asynccontextmanager as acm
 )
 from multiprocessing.shared_memory import SharedMemory
 import trio
 from msgspec import (
    Struct,
    to_builtins
 )
 from ._linux import (
    open_eventfd,
    EFDReadCancelled,
    EventFD
 )
 from ._mp_bs import disable_mantracker
 from tractor.log import get_logger
 from tractor._exceptions import (
    InternalError
 )
 log = get_logger(__name__)
 disable_mantracker()
 _DEFAULT_RB_SIZE = 10 * 1024
 class RBToken(Struct, frozen=True):
    '''
    RingBuffer token contains necesary info to open the three
    eventfds and the shared memory
    '''
    shm_name: str
    write_eventfd: int  # used to signal writer ptr advance
    wrap_eventfd: int  # used to signal reader ready after wrap around
    eof_eventfd: int  # used to signal writer closed
    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)
    @property
    def fds(self) -> tuple[int, int, int]:
        '''
        Useful for `pass_fds` params
        '''
        return (
            self.write_eventfd,
            self.wrap_eventfd,
            self.eof_eventfd
        )
@cm
 def open_ringbuf(
    shm_name: str,
    buf_size: int = _DEFAULT_RB_SIZE,
 ) -> ContextManager[RBToken]:
    '''
    Handle resources for a ringbuf (shm, eventfd), yield `RBToken` to
    be used with `attach_to_ringbuf_sender` and `attach_to_ringbuf_receiver`
    '''
    shm = SharedMemory(
        name=shm_name,
        size=buf_size,
        create=True
    )
    try:
        with (
            EventFD(open_eventfd(), 'r') as write_event,
            EventFD(open_eventfd(), 'r') as wrap_event,
            EventFD(open_eventfd(), 'r') as eof_event,
        ):
            token = RBToken(
                shm_name=shm_name,
                write_eventfd=write_event.fd,
                wrap_eventfd=wrap_event.fd,
                eof_eventfd=eof_event.fd,
                buf_size=buf_size
            )
            yield token
    finally:
        shm.unlink()
 Buffer = bytes | bytearray | memoryview
 '''
 IPC Reliable Ring Buffer
 `eventfd(2)` is used for wrap around sync, to signal writes to
 the reader and end of stream.
 '''
 class RingBuffSender(trio.abc.SendStream):
    '''
    Ring Buffer sender side implementation
    Do not use directly! manage with `attach_to_ringbuf_sender`
    after having opened a ringbuf context with `open_ringbuf`.
    '''
    def __init__(
        self,
        token: RBToken,
        cleanup: bool = False
    ):
        self._token = RBToken.from_msg(token)
        self._shm: SharedMemory | None = None
        self._write_event = EventFD(self._token.write_eventfd, 'w')
        self._wrap_event = EventFD(self._token.wrap_eventfd, 'r')
        self._eof_event = EventFD(self._token.eof_eventfd, 'w')
        self._ptr = 0
        self._cleanup = cleanup
        self._send_lock = trio.StrictFIFOLock()
    @property
    def name(self) -> str:
        if not self._shm:
            raise ValueError('shared memory not initialized yet!')
        return self._shm.name
    @property
    def size(self) -> int:
        return self._token.buf_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: Buffer):
        async with self._send_lock:
            # 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
    def open(self):
        self._shm = SharedMemory(
            name=self._token.shm_name,
            size=self._token.buf_size,
            create=False
        )
        self._write_event.open()
        self._wrap_event.open()
        self._eof_event.open()
    def close(self):
        self._eof_event.write(
            self._ptr if self._ptr > 0 else self.size
        )
        if self._cleanup:
            self._write_event.close()
            self._wrap_event.close()
            self._eof_event.close()
            self._shm.close()
    async def aclose(self):
        async with self._send_lock:
            self.close()
    async def __aenter__(self):
        self.open()
        return self
 class RingBuffReceiver(trio.abc.ReceiveStream):
    '''
    Ring Buffer receiver side implementation
    Do not use directly! manage with `attach_to_ringbuf_receiver`
    after having opened a ringbuf context with `open_ringbuf`.
    '''
    def __init__(
        self,
        token: RBToken,
        cleanup: bool = True,
    ):
        self._token = RBToken.from_msg(token)
        self._shm: SharedMemory | None = None
        self._write_event = EventFD(self._token.write_eventfd, 'w')
        self._wrap_event = EventFD(self._token.wrap_eventfd, 'r')
        self._eof_event = EventFD(self._token.eof_eventfd, 'r')
        self._ptr: int = 0
        self._write_ptr: int = 0
        self._end_ptr: int = -1
        self._cleanup: bool = cleanup
    @property
    def name(self) -> str:
        if not self._shm:
            raise ValueError('shared memory not initialized yet!')
        return self._shm.name
    @property
    def size(self) -> int:
        return self._token.buf_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 _eof_monitor_task(self):
        '''
        Long running EOF event monitor, automatically run in bg by
        `attach_to_ringbuf_receiver` context manager, if EOF event
        is set its value will be the end pointer (highest valid
        index to be read from buf, after setting the `self._end_ptr`
        we close the write event which should cancel any blocked
        `self._write_event.read()`s on it.
        '''
        try:
            self._end_ptr = await self._eof_event.read()
            self._write_event.close()
        except EFDReadCancelled:
            ...
        except trio.Cancelled:
            ...
    async def receive_some(self, max_bytes: int | None = None) -> bytes:
        '''
        Receive up to `max_bytes`, if no `max_bytes` is provided
        a reasonable default is used.
        '''
        if max_bytes is None:
            max_bytes: int = _DEFAULT_RB_SIZE
        if max_bytes < 1:
            raise ValueError("max_bytes must be >= 1")
        # delta is remaining bytes we havent read
        delta = self._write_ptr - self._ptr
        if delta == 0:
            # we have read all we can, see if new data is available
            if self._end_ptr < 0:
                # if we havent been signaled about EOF yet
                try:
                    delta = await self._write_event.read()
                    self._write_ptr += delta
                except EFDReadCancelled:
                    # while waiting for new data `self._write_event` was closed
                    # this means writer signaled EOF
                    if self._end_ptr > 0:
                        # final self._write_ptr modification and recalculate delta
                        self._write_ptr = self._end_ptr
                        delta = self._end_ptr - self._ptr
                    else:
                        # shouldnt happen cause self._eof_monitor_task always sets
                        # self._end_ptr before closing self._write_event
                        raise InternalError(
                            'self._write_event.read cancelled but self._end_ptr is not set'
                        )
            else:
                # no more bytes to read and self._end_ptr set, EOF reached
                return b''
        # dont overflow caller
        delta = min(delta, max_bytes)
        target_ptr = self._ptr + delta
        # fetch next segment and advance ptr
        segment = bytes(self._shm.buf[self._ptr:target_ptr])
        self._ptr = target_ptr
        if self._ptr == self.size:
            # reached the end, signal wrap around
            self._ptr = 0
            self._write_ptr = 0
            self._wrap_event.write(1)
        return segment
    def open(self):
        self._shm = SharedMemory(
            name=self._token.shm_name,
            size=self._token.buf_size,
            create=False
        )
        self._write_event.open()
        self._wrap_event.open()
        self._eof_event.open()
    def close(self):
        if self._cleanup:
            self._write_event.close()
            self._wrap_event.close()
            self._eof_event.close()
            self._shm.close()
    async def aclose(self):
        self.close()
    async def __aenter__(self):
        self.open()
        return self
@acm
 async def attach_to_ringbuf_receiver(
    token: RBToken,
    cleanup: bool = True
 ) -> AsyncContextManager[RingBuffReceiver]:
    '''
    Attach a RingBuffReceiver from a previously opened
    RBToken.
    Launches `receiver._eof_monitor_task` in a `trio.Nursery`.
    '''
    async with (
        trio.open_nursery() as n,
        RingBuffReceiver(
            token,
            cleanup=cleanup
        ) as receiver
    ):
        n.start_soon(receiver._eof_monitor_task)
        yield receiver
@acm
 async def attach_to_ringbuf_sender(
    token: RBToken,
    cleanup: bool = True
 ) -> AsyncContextManager[RingBuffSender]:
    '''
    Attach a RingBuffSender from a previously opened
    RBToken.
    '''
    async with RingBuffSender(
        token,
        cleanup=cleanup
    ) as sender:
        yield sender
@cm
 def open_ringbuf_pair(
    name: str,
    buf_size: int = _DEFAULT_RB_SIZE
 ) -> ContextManager[tuple(RBToken, RBToken)]:
    '''
    Handle resources for a ringbuf pair to be used for
    bidirectional messaging.
    '''
    with (
        open_ringbuf(
            name + '.pair0',
            buf_size=buf_size
        ) as token_0,
        open_ringbuf(
            name + '.pair1',
            buf_size=buf_size
        ) as token_1
    ):
        yield token_0, token_1
@acm
 async def attach_to_ringbuf_stream(
    token_in: RBToken,
    token_out: RBToken,
    cleanup_in: bool = True,
    cleanup_out: bool = True
 ) -> AsyncContextManager[trio.StapledStream]:
    '''
    Attach a trio.StapledStream from a previously opened
    ringbuf pair.
    '''
    async with (
        attach_to_ringbuf_receiver(
            token_in,
            cleanup=cleanup_in
        ) as receiver,
        attach_to_ringbuf_sender(
            token_out,
            cleanup=cleanup_out
        ) as sender,
    ):
        yield trio.StapledStream(sender, receiver)
 class RingBuffBytesSender(trio.abc.SendChannel[bytes]):
    '''
    In order to guarantee full messages are received, all bytes
    sent by `RingBuffBytesSender` are preceded with a 4 byte header
    which decodes into a uint32 indicating the actual size of the
    next payload.
    Optional batch mode:
    If `batch_size` > 1 messages wont get sent immediately but will be
    stored until `batch_size` messages are pending, then it will send
    them all at once.
    `batch_size` can be changed dynamically but always call, `flush()`
    right before.
    '''
    def __init__(
        self,
        sender: RingBuffSender,
        batch_size: int = 1
    ):
        self._sender = sender
        self.batch_size = batch_size
        self._batch_msg_len = 0
        self._batch: bytes = b''
    async def flush(self) -> None:
        await self._sender.send_all(self._batch)
        self._batch = b''
        self._batch_msg_len = 0
    async def send(self, value: bytes) -> None:
        msg: bytes = struct.pack("<I", len(value)) + value
        if self.batch_size == 1:
            await self._sender.send_all(msg)
            return
        self._batch += msg
        self._batch_msg_len += 1
        if self._batch_msg_len == self.batch_size:
            await self.flush()
    async def aclose(self) -> None:
        await self._sender.aclose()
 class RingBuffBytesReceiver(trio.abc.ReceiveChannel[bytes]):
    '''
    See `RingBuffBytesSender` docstring.
    A `tricycle.BufferedReceiveStream` is used for the
    `receive_exactly` API.
    '''
    def __init__(
        self,
        receiver: RingBuffReceiver
    ):
        self._receiver = receiver
    async def _receive_exactly(self, num_bytes: int) -> bytes:
        '''
        Fetch bytes from receiver until we read exactly `num_bytes`
        or end of stream is signaled.
        '''
        payload = b''
        while len(payload) < num_bytes:
            remaining = num_bytes - len(payload)
            new_bytes = await self._receiver.receive_some(
                max_bytes=remaining
            )
            if new_bytes == b'':
                raise trio.EndOfChannel
            payload += new_bytes
        return payload
    async def receive(self) -> bytes:
        header: bytes = await self._receive_exactly(4)
        size: int
        size, = struct.unpack("<I", header)
        if size == 0:
            raise trio.EndOfChannel
        return await self._receive_exactly(size)
    async def aclose(self) -> None:
        await self._receiver.aclose()
@acm
 async def attach_to_ringbuf_rchannel(
    token: RBToken,
    cleanup: bool = True
 ) -> AsyncContextManager[RingBuffBytesReceiver]:
    '''
    Attach a RingBuffBytesReceiver from a previously opened
    RBToken.
    '''
    async with attach_to_ringbuf_receiver(
        token, cleanup=cleanup
    ) as receiver:
        yield RingBuffBytesReceiver(receiver)
@acm
 async def attach_to_ringbuf_schannel(
    token: RBToken,
    cleanup: bool = True,
    batch_size: int = 1,
 ) -> AsyncContextManager[RingBuffBytesSender]:
    '''
    Attach a RingBuffBytesSender from a previously opened
    RBToken.
    '''
    async with attach_to_ringbuf_sender(
        token, cleanup=cleanup
    ) as sender:
        yield RingBuffBytesSender(sender, batch_size=batch_size)
 class RingBuffChannel(trio.abc.Channel[bytes]):
    '''
    Combine `RingBuffBytesSender` and `RingBuffBytesReceiver`
    in order to expose the bidirectional `trio.abc.Channel` API.
    '''
    def __init__(
        self,
        sender: RingBuffBytesSender,
        receiver: RingBuffBytesReceiver
    ):
        self._sender = sender
        self._receiver = receiver
    async def send(self, value: bytes):
        await self._sender.send(value)
    async def receive(self) -> bytes:
        return await self._receiver.receive()
    async def aclose(self):
        await self._receiver.aclose()
        await self._sender.aclose()
@acm
 async def attach_to_ringbuf_channel(
    token_in: RBToken,
    token_out: RBToken,
    cleanup_in: bool = True,
    cleanup_out: bool = True
 ) -> AsyncContextManager[RingBuffChannel]:
    '''
    Attach to an already opened ringbuf pair and return
    a `RingBuffChannel`.
    '''
    async with (
        attach_to_ringbuf_rchannel(
            token_in,
            cleanup=cleanup_in
        ) as receiver,
        attach_to_ringbuf_schannel(
            token_out,
            cleanup=cleanup_out
        ) as sender,
    ):
        yield RingBuffChannel(sender, receiver)
--- a/tractor/ipc/_shm.py
+++ b/tractor/ipc/_shm.py
@ -0,0 +1,809 @@
 # 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
    import nptyping
 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,
    )
--- a/tractor/ipc/_tcp.py
+++ b/tractor/ipc/_tcp.py
@ -13,31 +13,19 @@
 # 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 
-"""
+'''
 Inter-process comms abstractions
 """
 from __future__ import annotations
 from collections.abc import (
    AsyncGenerator,
    AsyncIterator,
 )
 from contextlib import (
    asynccontextmanager as acm,
    contextmanager as cm,
 )
 import platform
 from pprint import pformat
 import struct
 import typing
 from typing import (
    Any,
    Callable,
    runtime_checkable,
    Protocol,
    Type,
    TypeVar,
 )
 import msgspec
@ -47,7 +35,6 @@ import trio
 from tractor.log import get_logger
 from tractor._exceptions import (
    MsgTypeError,
    pack_from_raise,
    TransportClosed,
    _mk_send_mte,
    _mk_recv_mte,
@ -59,11 +46,11 @@ from tractor.msg import (
    types as msgtypes,
    pretty_struct,
 )
 from tractor.ipc import MsgTransport
 log = get_logger(__name__)
 _is_windows = platform.system() == 'Windows'
 def get_stream_addrs(
    stream: trio.SocketStream
@ -85,56 +72,6 @@ def get_stream_addrs(
    )
 # from tractor.msg.types import MsgType
 # ?TODO? this should be our `Union[*msgtypes.__spec__]` alias now right..?
 # => BLEH, except can't bc prots must inherit typevar or param-spec
 #   vars..
 MsgType = TypeVar('MsgType')
 # TODO: break up this mod into a subpkg so we can start adding new
 # backends and move this type stuff into a dedicated file.. Bo
 #
@runtime_checkable
 class MsgTransport(Protocol[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
    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: 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?
@ -255,8 +192,8 @@ class MsgpackTCPStream(MsgTransport):
                raise TransportClosed(
                    message=(
                        f'IPC transport already closed by peer\n'
-                        f'x]> {type(trans_err)}\n'
+                        f'x)> {type(trans_err)}\n'
-                        f'  |_{self}\n'
+                        f' |_{self}\n'
                    ),
                    loglevel=loglevel,
                ) from trans_err
@ -273,8 +210,8 @@ class MsgpackTCPStream(MsgTransport):
                raise TransportClosed(
                    message=(
                        f'IPC transport already manually closed locally?\n'
-                        f'x]> {type(closure_err)} \n'
+                        f'x)> {type(closure_err)} \n'
-                        f'  |_{self}\n'
+                        f' |_{self}\n'
                    ),
                    loglevel='error',
                    raise_on_report=(
@ -289,8 +226,8 @@ class MsgpackTCPStream(MsgTransport):
                raise TransportClosed(
                    message=(
                        f'IPC transport already gracefully closed\n'
-                        f']>\n'
+                        f')>\n'
-                        f' |_{self}\n'
+                        f'|_{self}\n'
                    ),
                    loglevel='transport',
                    # cause=???  # handy or no?
@ -466,355 +403,3 @@ class MsgpackTCPStream(MsgTransport):
    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._aiter_msgs = self._iter_msgs()
        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,
        # XXX optionally provided codec pair for `msgspec`:
        # https://jcristharif.com/msgspec/extending.html#mapping-to-from-native-types
        codec: MsgCodec|None = None,
    ) -> MsgTransport:
        type_key = (
            type_key
            or
            self._transport_key
        )
        # get transport type, then
        self._transport = get_msg_transport(
            type_key
        # instantiate an instance of the msg-transport
        )(
            stream,
            codec=codec,
        )
        return self._transport
    @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 __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
    # 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 = False,
    ) -> 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 as _err:
            err = _err  # bind for introspection
            if not isinstance(_err, MsgTypeError):
                # assert err
                __tracebackhide__: bool = False
            else:
                assert err.cid
            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.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._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
@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
    with trio.CancelScope(shield=True):
        await chan.aclose()
--- a/tractor/ipc/_transport.py
+++ b/tractor/ipc/_transport.py
@ -0,0 +1,74 @@
 # 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/>.
 '''
 typing.Protocol based generic msg API, implement this class to add backends for
 tractor.ipc.Channel
 '''
 import trio
 from typing import (
    runtime_checkable,
    Protocol,
    TypeVar,
 )
 from collections.abc import AsyncIterator
 # from tractor.msg.types import MsgType
 # ?TODO? this should be our `Union[*msgtypes.__spec__]` alias now right..?
 # => BLEH, except can't bc prots must inherit typevar or param-spec
 #   vars..
 MsgType = TypeVar('MsgType')
@runtime_checkable
 class MsgTransport(Protocol[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
    stream: trio.abc.Stream
    drained: list[MsgType]
    def __init__(self, stream: trio.abc.Stream) -> 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]:
        ...
--- a/tractor/log.py
+++ b/tractor/log.py
@ -92,7 +92,7 @@ class StackLevelAdapter(LoggerAdapter):
    ) -> None:
        '''
        IPC transport level msg IO; generally anything below
-        `._ipc.Channel` and friends.
+        `.ipc.Channel` and friends.
        '''
        return self.log(5, msg)
@ -285,7 +285,7 @@ def get_logger(
        # NOTE: for handling for modules that use ``get_logger(__name__)``
        # we make the following stylistic choice:
        # - always avoid duplicate project-package token
-        #   in msg output: i.e. tractor.tractor _ipc.py in header
+        #   in msg output: i.e. tractor.tractor.ipc._chan.py in header
        #   looks ridiculous XD
        # - never show the leaf module name in the {name} part
        #   since in python the {filename} is always this same
--- a/tractor/msg/init.py
+++ b/tractor/msg/init.py
@ -33,6 +33,7 @@ from ._codec import (
    apply_codec as apply_codec,
    mk_codec as mk_codec,
    mk_dec as mk_dec,
    MsgCodec as MsgCodec,
    MsgDec as MsgDec,
    current_codec as current_codec,
--- a/tractor/msg/_codec.py
+++ b/tractor/msg/_codec.py
@ -61,6 +61,7 @@ from tractor.msg.pretty_struct import Struct
 from tractor.msg.types import (
    mk_msg_spec,
    MsgType,
    PayloadMsg,
 )
 from tractor.log import get_logger
@ -80,6 +81,7 @@ class MsgDec(Struct):
    '''
    _dec: msgpack.Decoder
    # _ext_types_box: Struct|None = None
    @property
    def dec(self) -> msgpack.Decoder:
@ -179,23 +181,126 @@ class MsgDec(Struct):
 def mk_dec(
-    spec: Union[Type[Struct]]|Any = Any,
+    spec: Union[Type[Struct]]|Type|None,
    # NOTE, required for ad-hoc type extensions to the underlying
    # serialization proto (which is default `msgpack`),
    # https://jcristharif.com/msgspec/extending.html#mapping-to-from-native-types
    dec_hook: Callable|None = None,
    ext_types: list[Type]|None = None,
 ) -> MsgDec:
    '''
-    Create an IPC msg decoder, normally used as the
+    Create an IPC msg decoder, a slightly higher level wrapper around
-    `PayloadMsg.pld: PayloadT` field decoder inside a `PldRx`.
+    a `msgspec.msgpack.Decoder` which provides,
    - easier introspection of the underlying type spec via
      the `.spec` and `.spec_str` attrs,
    - `.hook` access to the `Decoder.dec_hook()`,
    - automatic custom extension-types decode support when
      `dec_hook()` is provided such that any `PayloadMsg.pld` tagged
      as a type from from `ext_types` (presuming the `MsgCodec.encode()` also used
      a `.enc_hook()`) is processed and constructed by a `PldRx` implicitily.
    NOTE, as mentioned a `MsgDec` is normally used for `PayloadMsg.pld: PayloadT` field
    decoding inside an IPC-ctx-oriented `PldRx`.
    '''
    if (
        spec is None
        and
        ext_types is None
    ):
        raise TypeError(
            f'MIssing type-`spec` for msg decoder!\n'
            f'\n'
            f'`spec=None` is **only** permitted is if custom extension types '
            f'are provided via `ext_types`, meaning it must be non-`None`.\n'
            f'\n'
            f'In this case it is presumed that only the `ext_types`, '
            f'which much be handled by a paired `dec_hook()`, '
            f'will be permitted within the payload type-`spec`!\n'
            f'\n'
            f'spec = {spec!r}\n'
            f'dec_hook = {dec_hook!r}\n'
            f'ext_types = {ext_types!r}\n'
        )
    if dec_hook:
        if ext_types is None:
            raise TypeError(
                f'If extending the serializable types with a custom decode hook (`dec_hook()`), '
                f'you must also provide the expected type set that the hook will handle '
                f'via a `ext_types: Union[Type]|None = None` argument!\n'
                f'\n'
                f'dec_hook = {dec_hook!r}\n'
                f'ext_types = {ext_types!r}\n'
            )
        # XXX, i *thought* we would require a boxing struct as per docs,
        # https://jcristharif.com/msgspec/extending.html#mapping-to-from-native-types
        # |_ see comment,
        #  > Note that typed deserialization is required for
        #  > successful roundtripping here, so we pass `MyMessage` to
        #  > `Decoder`.
        #
        # BUT, turns out as long as you spec a union with `Raw` it
        # will work? kk B)
        #
        # maybe_box_struct = mk_boxed_ext_struct(ext_types)
        spec = Raw | Union[*ext_types]
    return MsgDec(
        _dec=msgpack.Decoder(
            type=spec,  # like `MsgType[Any]`
            dec_hook=dec_hook,
-        )
+        ),
    )
 # TODO? remove since didn't end up needing this?
 def mk_boxed_ext_struct(
    ext_types: list[Type],
 ) -> Struct:
    # NOTE, originally was to wrap non-msgpack-supported "extension
    # types" in a field-typed boxing struct, see notes around the
    # `dec_hook()` branch in `mk_dec()`.
    ext_types_union = Union[*ext_types]
    repr_ext_types_union: str = (
        str(ext_types_union)
        or
        "|".join(ext_types)
    )
    BoxedExtType = msgspec.defstruct(
        f'BoxedExts[{repr_ext_types_union}]',
        fields=[
            ('boxed', ext_types_union),
        ],
    )
    return BoxedExtType
 def unpack_spec_types(
    spec: Union[Type]|Type,
 ) -> set[Type]:
    '''
    Given an input type-`spec`, either a lone type
    or a `Union` of types (like `str|int|MyThing`),
    return a set of individual types.
    When `spec` is not a type-union returns `{spec,}`.
    '''
    spec_subtypes: set[Union[Type]] = set(
         getattr(
             spec,
             '__args__',
             {spec,},
         )
    )
    return spec_subtypes
 def mk_msgspec_table(
    dec: msgpack.Decoder,
    msg: MsgType|None = None,
@ -273,6 +378,8 @@ class MsgCodec(Struct):
    _dec: msgpack.Decoder
    _pld_spec: Type[Struct]|Raw|Any
    # _ext_types_box: Struct|None = None
    def __repr__(self) -> str:
        speclines: str = textwrap.indent(
            pformat_msgspec(codec=self),
@ -339,12 +446,15 @@ class MsgCodec(Struct):
    def encode(
        self,
-        py_obj: Any,
+        py_obj: Any|PayloadMsg,
        use_buf: bool = False,
        # ^-XXX-^ uhh why am i getting this?
        # |_BufferError: Existing exports of data: object cannot be re-sized
        as_ext_type: bool = False,
        hide_tb: bool = True,
    ) -> bytes:
        '''
        Encode input python objects to `msgpack` bytes for
@ -354,11 +464,46 @@ class MsgCodec(Struct):
        https://jcristharif.com/msgspec/perf-tips.html#reusing-an-output-buffer
        '''
        __tracebackhide__: bool = hide_tb
        if use_buf:
            self._enc.encode_into(py_obj, self._buf)
            return self._buf
-        else:
+
-            return self._enc.encode(py_obj)
+        return self._enc.encode(py_obj)
        # try:
        #     return self._enc.encode(py_obj)
        # except TypeError as typerr:
        #     typerr.add_note(
        #         '|_src error from `msgspec`'
        #         # f'|_{self._enc.encode!r}'
        #     )
        #     raise typerr
        # TODO! REMOVE once i'm confident we won't ever need it!
        #
        # box: Struct = self._ext_types_box
        # if (
        #     as_ext_type
        #     or
        #     (
        #         # XXX NOTE, auto-detect if the input type
        #         box
        #         and
        #         (ext_types := unpack_spec_types(
        #             spec=box.__annotations__['boxed'])
        #         )
        #     )
        # ):
        #     match py_obj:
        #         # case PayloadMsg(pld=pld) if (
        #         #     type(pld) in ext_types
        #         # ):
        #         #     py_obj.pld = box(boxed=py_obj)
        #         #     breakpoint()
        #         case _ if (
        #             type(py_obj) in ext_types
        #         ):
        #             py_obj = box(boxed=py_obj)
    @property
    def dec(self) -> msgpack.Decoder:
@ -378,21 +523,30 @@ class MsgCodec(Struct):
        return self._dec.decode(msg)
-# [x] TODO: a sub-decoder system as well? => No!
+# ?TODO? time to remove this finally?
 #
 # -[x] TODO: a sub-decoder system as well?
 # => No! already re-architected to include a "payload-receiver"
 #   now found in `._ops`.
 #
 # -[x] do we still want to try and support the sub-decoder with
 # `.Raw` technique in the case that the `Generic` approach gives
 # future grief?
-# => NO, since we went with the `PldRx` approach instead B)
+# => well YES but NO, since we went with the `PldRx` approach
 #   instead!
 #
 # IF however you want to see the code that was staged for this
 # from wayyy back, see the pure removal commit.
 def mk_codec(
-    # struct type unions set for `Decoder`
+    ipc_pld_spec: Union[Type[Struct]]|Any|Raw = Raw,
-    # https://jcristharif.com/msgspec/structs.html#tagged-unions
+    # tagged-struct-types-union set for `Decoder`ing of payloads, as
-    ipc_pld_spec: Union[Type[Struct]]|Any = Any,
+    # per https://jcristharif.com/msgspec/structs.html#tagged-unions.
    # NOTE that the default `Raw` here **is very intentional** since
    # the `PldRx._pld_dec: MsgDec` is responsible for per ipc-ctx-task
    # decoding of msg-specs defined by the user as part of **their**
    # `tractor` "app's" type-limited IPC msg-spec.
    # TODO: offering a per-msg(-field) type-spec such that
    # the fields can be dynamically NOT decoded and left as `Raw`
@ -405,13 +559,18 @@ def mk_codec(
    libname: str = 'msgspec',
-    # proxy as `Struct(**kwargs)` for ad-hoc type extensions
+    # settings for encoding-to-send extension-types,
    # https://jcristharif.com/msgspec/extending.html#mapping-to-from-native-types
-    # ------ - ------
+    # dec_hook: Callable|None = None,
    dec_hook: Callable|None = None,
    enc_hook: Callable|None = None,
-    # ------ - ------
+    ext_types: list[Type]|None = None,
    # optionally provided msg-decoder from which we pull its,
    # |_.dec_hook()
    # |_.type
    ext_dec: MsgDec|None = None
    #
    # ?TODO? other params we might want to support
    # Encoder:
    # write_buffer_size=write_buffer_size,
    #
@ -425,26 +584,44 @@ def mk_codec(
    `msgspec` ;).
    '''
-    # (manually) generate a msg-payload-spec for all relevant
+    pld_spec = ipc_pld_spec
-    # god-boxing-msg subtypes, parameterizing the `PayloadMsg.pld: PayloadT`
+    if enc_hook:
-    # for the decoder such that all sub-type msgs in our SCIPP
+        if not ext_types:
-    # will automatically decode to a type-"limited" payload (`Struct`)
+            raise TypeError(
-    # object (set).
+                f'If extending the serializable types with a custom encode hook (`enc_hook()`), '
                f'you must also provide the expected type set that the hook will handle '
                f'via a `ext_types: Union[Type]|None = None` argument!\n'
                f'\n'
                f'enc_hook = {enc_hook!r}\n'
                f'ext_types = {ext_types!r}\n'
            )
    dec_hook: Callable|None = None
    if ext_dec:
        dec: msgspec.Decoder = ext_dec.dec
        dec_hook = dec.dec_hook
        pld_spec |= dec.type
        if ext_types:
            pld_spec |= Union[*ext_types]
    # (manually) generate a msg-spec (how appropes) for all relevant
    # payload-boxing-struct-msg-types, parameterizing the
    # `PayloadMsg.pld: PayloadT` for the decoder such that all msgs
    # in our SC-RPC-protocol will automatically decode to
    # a type-"limited" payload (`Struct`) object (set).
    (
        ipc_msg_spec,
        msg_types,
    ) = mk_msg_spec(
-        payload_type_union=ipc_pld_spec,
+        payload_type_union=pld_spec,
    )
    assert len(ipc_msg_spec.__args__) == len(msg_types)
    assert ipc_msg_spec
-    # TODO: use this shim instead?
+    msg_spec_types: set[Type] = unpack_spec_types(ipc_msg_spec)
-    # bc.. unification, err somethin?
+    assert (
-    # dec: MsgDec = mk_dec(
+        len(ipc_msg_spec.__args__) == len(msg_types)
-    #     spec=ipc_msg_spec,
+        and
-    #     dec_hook=dec_hook,
+        len(msg_spec_types) == len(msg_types)
-    # )
+    )
    dec = msgpack.Decoder(
        type=ipc_msg_spec,
@ -453,22 +630,29 @@ def mk_codec(
    enc = msgpack.Encoder(
       enc_hook=enc_hook,
    )
    codec = MsgCodec(
        _enc=enc,
        _dec=dec,
-        _pld_spec=ipc_pld_spec,
+        _pld_spec=pld_spec,
    )
    # sanity on expected backend support
    assert codec.lib.__name__ == libname
    return codec
 # instance of the default `msgspec.msgpack` codec settings, i.e.
 # no custom structs, hooks or other special types.
-_def_msgspec_codec: MsgCodec = mk_codec(ipc_pld_spec=Any)
+#
 # XXX NOTE XXX, this will break our `Context.start()` call!
 #
 # * by default we roundtrip the started pld-`value` and if you apply
 #   this codec (globally anyway with `apply_codec()`) then the
 #   `roundtripped` value will include a non-`.pld: Raw` which will
 #   then type-error on the consequent `._ops.validte_payload_msg()`..
 #
 _def_msgspec_codec: MsgCodec = mk_codec(
    ipc_pld_spec=Any,
 )
 # The built-in IPC `Msg` spec.
 # Our composing "shuttle" protocol which allows `tractor`-app code
@ -476,13 +660,13 @@ _def_msgspec_codec: MsgCodec = mk_codec(ipc_pld_spec=Any)
 # https://jcristharif.com/msgspec/supported-types.html
 #
 _def_tractor_codec: MsgCodec = mk_codec(
-    # TODO: use this for debug mode locking prot?
+    ipc_pld_spec=Raw,  # XXX should be default righ!?
    # ipc_pld_spec=Any,
    ipc_pld_spec=Raw,
 )
-# TODO: IDEALLY provides for per-`trio.Task` specificity of the
+
 # -[x] TODO, IDEALLY provides for per-`trio.Task` specificity of the
 # IPC msging codec used by the transport layer when doing
 # `Channel.send()/.recv()` of wire data.
 # => impled as our `PldRx` which is `Context` scoped B)
 # ContextVar-TODO: DIDN'T WORK, kept resetting in every new task to default!?
 # _ctxvar_MsgCodec: ContextVar[MsgCodec] = ContextVar(
@ -559,17 +743,6 @@ def apply_codec(
    )
    token: Token = var.set(codec)
    # ?TODO? for TreeVar approach which copies from the
    # cancel-scope of the prior value, NOT the prior task
    # See the docs:
    # - https://tricycle.readthedocs.io/en/latest/reference.html#tree-variables
    # - https://github.com/oremanj/tricycle/blob/master/tricycle/_tests/test_tree_var.py
    #   ^- see docs for @cm `.being()` API
    # with _ctxvar_MsgCodec.being(codec):
    #     new = _ctxvar_MsgCodec.get()
    #     assert new is codec
    #     yield codec
    try:
        yield var.get()
    finally:
@ -580,6 +753,19 @@ def apply_codec(
        )
        assert var.get() is orig
    # ?TODO? for TreeVar approach which copies from the
    # cancel-scope of the prior value, NOT the prior task
    #
    # See the docs:
    # - https://tricycle.readthedocs.io/en/latest/reference.html#tree-variables
    # - https://github.com/oremanj/tricycle/blob/master/tricycle/_tests/test_tree_var.py
    #   ^- see docs for @cm `.being()` API
    #
    # with _ctxvar_MsgCodec.being(codec):
    #     new = _ctxvar_MsgCodec.get()
    #     assert new is codec
    #     yield codec
 def current_codec() -> MsgCodec:
    '''
@ -599,6 +785,7 @@ def limit_msg_spec(
    # -> related to the `MsgCodec._payload_decs` stuff above..
    # tagged_structs: list[Struct]|None = None,
    hide_tb: bool = True,
    **codec_kwargs,
 ) -> MsgCodec:
@ -609,7 +796,7 @@ def limit_msg_spec(
    for all IPC contexts in use by the current `trio.Task`.
    '''
-    __tracebackhide__: bool = True
+    __tracebackhide__: bool = hide_tb
    curr_codec: MsgCodec = current_codec()
    msgspec_codec: MsgCodec = mk_codec(
        ipc_pld_spec=payload_spec,
--- a/tractor/msg/_exts.py
+++ b/tractor/msg/_exts.py
@ -0,0 +1,94 @@
 # 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/>.
 '''
 Type-extension-utils for codec-ing (python) objects not
 covered by the `msgspec.msgpack` protocol.
 See the various API docs from `msgspec`.
 extending from native types,
 - https://jcristharif.com/msgspec/extending.html#mapping-to-from-native-types
 converters,
 - https://jcristharif.com/msgspec/converters.html
 - https://jcristharif.com/msgspec/api.html#msgspec.convert
 `Raw` fields,
 - https://jcristharif.com/msgspec/api.html#raw
 - support for `.convert()` and `Raw`,
  |_ https://jcristharif.com/msgspec/changelog.html
 '''
 from types import (
    ModuleType,
 )
 import typing
 from typing import (
    Type,
    Union,
 )
 def dec_type_union(
    type_names: list[str],
    mods: list[ModuleType] = []
 ) -> Type|Union[Type]:
    '''
    Look up types by name, compile into a list and then create and
    return a `typing.Union` from the full set.
    '''
    # import importlib
    types: list[Type] = []
    for type_name in type_names:
        for mod in [
            typing,
            # importlib.import_module(__name__),
        ] + mods:
            if type_ref := getattr(
                mod,
                type_name,
                False,
            ):
                types.append(type_ref)
    # special case handling only..
    # ipc_pld_spec: Union[Type] = eval(
    #     pld_spec_str,
    #     {},  # globals
    #     {'typing': typing},  # locals
    # )
    return Union[*types]
 def enc_type_union(
    union_or_type: Union[Type]|Type,
 ) -> list[str]:
    '''
    Encode a type-union or single type to a list of type-name-strings
    ready for IPC interchange.
    '''
    type_strs: list[str] = []
    for typ in getattr(
        union_or_type,
        '__args__',
        {union_or_type,},
    ):
        type_strs.append(typ.__qualname__)
    return type_strs
--- a/tractor/msg/_ops.py
+++ b/tractor/msg/_ops.py
@ -50,7 +50,9 @@ from tractor._exceptions import (
    _mk_recv_mte,
    pack_error,
 )
-from tractor._state import current_ipc_ctx
+from tractor._state import (
    current_ipc_ctx,
 )
 from ._codec import (
    mk_dec,
    MsgDec,
@ -78,7 +80,7 @@ if TYPE_CHECKING:
 log = get_logger(__name__)
-_def_any_pldec: MsgDec[Any] = mk_dec()
+_def_any_pldec: MsgDec[Any] = mk_dec(spec=Any)
 class PldRx(Struct):
@ -108,33 +110,11 @@ class PldRx(Struct):
    # TODO: better to bind it here?
    # _rx_mc: trio.MemoryReceiveChannel
    _pld_dec: MsgDec
    _ctx: Context|None = None
    _ipc: Context|MsgStream|None = None
    @property
    def pld_dec(self) -> MsgDec:
        return self._pld_dec
    # TODO: a better name?
    # -[ ] when would this be used as it avoids needingn to pass the
    #   ipc prim to every method
    @cm
    def wraps_ipc(
        self,
        ipc_prim: Context|MsgStream,
    ) -> PldRx:
        '''
        Apply this payload receiver to an IPC primitive type, one
        of `Context` or `MsgStream`.
        '''
        self._ipc = ipc_prim
        try:
            yield self
        finally:
            self._ipc = None
    @cm
    def limit_plds(
        self,
@ -148,6 +128,10 @@ class PldRx(Struct):
        exit.
        '''
        # TODO, ensure we pull the current `MsgCodec`'s custom
        # dec/enc_hook settings as well ?
        # -[ ] see `._codec.mk_codec()` inputs
        #
        orig_dec: MsgDec = self._pld_dec
        limit_dec: MsgDec = mk_dec(
            spec=spec,
@ -163,7 +147,7 @@ class PldRx(Struct):
    def dec(self) -> msgpack.Decoder:
        return self._pld_dec.dec
-    def recv_pld_nowait(
+    def recv_msg_nowait(
        self,
        # TODO: make this `MsgStream` compat as well, see above^
        # ipc_prim: Context|MsgStream,
@ -174,34 +158,95 @@ class PldRx(Struct):
        hide_tb: bool = False,
        **dec_pld_kwargs,
-    ) -> Any|Raw:
+    ) -> tuple[
        MsgType[PayloadT],
        PayloadT,
    ]:
        '''
        Attempt to non-blocking receive a message from the `._rx_chan` and
        unwrap it's payload delivering the pair to the caller.
        '''
        __tracebackhide__: bool = hide_tb
        msg: MsgType = (
            ipc_msg
            or
            # sync-rx msg from underlying IPC feeder (mem-)chan
            ipc._rx_chan.receive_nowait()
        )
-        return self.decode_pld(
+        pld: PayloadT = self.decode_pld(
            msg,
            ipc=ipc,
            expect_msg=expect_msg,
            hide_tb=hide_tb,
            **dec_pld_kwargs,
        )
        return (
            msg,
            pld,
        )
    async def recv_msg(
        self,
        ipc: Context|MsgStream,
        expect_msg: MsgType,
        # NOTE: ONLY for handling `Stop`-msgs that arrive during
        # a call to `drain_to_final_msg()` above!
        passthrough_non_pld_msgs: bool = True,
        hide_tb: bool = True,
        **decode_pld_kwargs,
    ) -> tuple[MsgType, PayloadT]:
        '''
        Retrieve the next avail IPC msg, decode its payload, and
        return the (msg, pld) pair.
        '''
        __tracebackhide__: bool = hide_tb
        msg: MsgType = await ipc._rx_chan.receive()
        match msg:
            case Return()|Error():
                log.runtime(
                    f'Rxed final outcome msg\n'
                    f'{msg}\n'
                )
            case Stop():
                log.runtime(
                    f'Rxed stream stopped msg\n'
                    f'{msg}\n'
                )
                if passthrough_non_pld_msgs:
                    return msg, None
        # TODO: is there some way we can inject the decoded
        # payload into an existing output buffer for the original
        # msg instance?
        pld: PayloadT = self.decode_pld(
            msg,
            ipc=ipc,
            expect_msg=expect_msg,
            hide_tb=hide_tb,
            **decode_pld_kwargs,
        )
        return (
            msg,
            pld,
        )
    async def recv_pld(
        self,
        ipc: Context|MsgStream,
-        ipc_msg: MsgType|None = None,
+        ipc_msg: MsgType[PayloadT]|None = None,
        expect_msg: Type[MsgType]|None = None,
        hide_tb: bool = True,
        **dec_pld_kwargs,
-    ) -> Any|Raw:
+    ) -> PayloadT:
        '''
        Receive a `MsgType`, then decode and return its `.pld` field.
@ -213,6 +258,13 @@ class PldRx(Struct):
            # async-rx msg from underlying IPC feeder (mem-)chan
            await ipc._rx_chan.receive()
        )
        if (
            type(msg) is Return
        ):
            log.info(
                f'Rxed final result msg\n'
                f'{msg}\n'
            )
        return self.decode_pld(
            msg=msg,
            ipc=ipc,
@ -401,45 +453,6 @@ class PldRx(Struct):
            __tracebackhide__: bool = False
            raise
    dec_msg = decode_pld
    async def recv_msg_w_pld(
        self,
        ipc: Context|MsgStream,
        expect_msg: MsgType,
        # NOTE: generally speaking only for handling `Stop`-msgs that
        # arrive during a call to `drain_to_final_msg()` above!
        passthrough_non_pld_msgs: bool = True,
        hide_tb: bool = True,
        **kwargs,
    ) -> tuple[MsgType, PayloadT]:
        '''
        Retrieve the next avail IPC msg, decode it's payload, and return
        the pair of refs.
        '''
        __tracebackhide__: bool = hide_tb
        msg: MsgType = await ipc._rx_chan.receive()
        if passthrough_non_pld_msgs:
            match msg:
                case Stop():
                    return msg, None
        # TODO: is there some way we can inject the decoded
        # payload into an existing output buffer for the original
        # msg instance?
        pld: PayloadT = self.decode_pld(
            msg,
            ipc=ipc,
            expect_msg=expect_msg,
            hide_tb=hide_tb,
            **kwargs,
        )
        return msg, pld
@cm
 def limit_plds(
@ -455,11 +468,16 @@ def limit_plds(
    '''
    __tracebackhide__: bool = True
    curr_ctx: Context|None = current_ipc_ctx()
    if curr_ctx is None:
        raise RuntimeError(
            'No IPC `Context` is active !?\n'
            'Did you open `limit_plds()` from outside '
            'a `Portal.open_context()` scope-block?'
        )
    try:
        curr_ctx: Context = current_ipc_ctx()
        rx: PldRx = curr_ctx._pld_rx
        orig_pldec: MsgDec = rx.pld_dec
        with rx.limit_plds(
            spec=spec,
            **dec_kwargs,
@ -469,6 +487,11 @@ def limit_plds(
                f'{pldec}\n'
            )
            yield pldec
    except BaseException:
        __tracebackhide__: bool = False
        raise
    finally:
        log.runtime(
            'Reverted to previous payload-decoder\n\n'
@ -522,8 +545,8 @@ async def maybe_limit_plds(
 async def drain_to_final_msg(
    ctx: Context,
    hide_tb: bool = True,
    msg_limit: int = 6,
    hide_tb: bool = True,
 ) -> tuple[
    Return|None,
@ -552,8 +575,8 @@ async def drain_to_final_msg(
    even after ctx closure and the `.open_context()` block exit.
    '''
    __tracebackhide__: bool = hide_tb
    raise_overrun: bool = not ctx._allow_overruns
    parent_never_opened_stream: bool = ctx._stream is None
    # wait for a final context result by collecting (but
    # basically ignoring) any bi-dir-stream msgs still in transit
@ -562,13 +585,14 @@ async def drain_to_final_msg(
    result_msg: Return|Error|None = None
    while not (
        ctx.maybe_error
-        and not ctx._final_result_is_set()
+        and
        not ctx._final_result_is_set()
    ):
        try:
            # receive all msgs, scanning for either a final result
            # or error; the underlying call should never raise any
            # remote error directly!
-            msg, pld = await ctx._pld_rx.recv_msg_w_pld(
+            msg, pld = await ctx._pld_rx.recv_msg(
                ipc=ctx,
                expect_msg=Return,
                raise_error=False,
@ -615,6 +639,11 @@ async def drain_to_final_msg(
                    )
                    __tracebackhide__: bool = False
            else:
                log.cancel(
                    f'IPC ctx cancelled externally during result drain ?\n'
                    f'{ctx}'
                )
            # CASE 2: mask the local cancelled-error(s)
            # only when we are sure the remote error is
            # the source cause of this local task's
@ -646,17 +675,24 @@ async def drain_to_final_msg(
            case Yield():
                pre_result_drained.append(msg)
                if (
-                    (ctx._stream.closed
+                    not parent_never_opened_stream
-                     and (reason := 'stream was already closed')
+                    and (
-                    )
+                        (ctx._stream.closed
-                    or (ctx.cancel_acked
+                         and
-                        and (reason := 'ctx cancelled other side')
+                         (reason := 'stream was already closed')
-                    )
+                        ) or
-                    or (ctx._cancel_called
+                        (ctx.cancel_acked
-                        and (reason := 'ctx called `.cancel()`')
+                            and
-                    )
+                            (reason := 'ctx cancelled other side')
-                    or (len(pre_result_drained) > msg_limit
+                        )
-                        and (reason := f'"yield" limit={msg_limit}')
+                        or (ctx._cancel_called
                            and
                            (reason := 'ctx called `.cancel()`')
                        )
                        or (len(pre_result_drained) > msg_limit
                            and
                            (reason := f'"yield" limit={msg_limit}')
                        )
                    )
                ):
                    log.cancel(
@ -674,7 +710,7 @@ async def drain_to_final_msg(
                # drain up to the `msg_limit` hoping to get
                # a final result or error/ctxc.
                else:
-                    log.warning(
+                    report: str = (
                        'Ignoring "yield" msg during `ctx.result()` drain..\n'
                        f'<= {ctx.chan.uid}\n'
                        f'  |_{ctx._nsf}()\n\n'
@ -683,6 +719,14 @@ async def drain_to_final_msg(
                        f'{pretty_struct.pformat(msg)}\n'
                    )
                    if parent_never_opened_stream:
                        report = (
                            f'IPC ctx never opened stream on {ctx.side!r}-side!\n'
                            f'\n'
                            # f'{ctx}\n'
                        ) + report
                    log.warning(report)
                    continue
            # stream terminated, but no result yet..
@ -774,6 +818,7 @@ async def drain_to_final_msg(
            f'{ctx.outcome}\n'
        )
    __tracebackhide__: bool = hide_tb
    return (
        result_msg,
        pre_result_drained,
--- a/tractor/msg/types.py
+++ b/tractor/msg/types.py
@ -599,15 +599,15 @@ def mk_msg_spec(
        Msg[payload_type_union],
        Generic[PayloadT],
    )
-    defstruct_bases: tuple = (
+    # defstruct_bases: tuple = (
-        Msg, # [payload_type_union],
+    #     Msg, # [payload_type_union],
-        # Generic[PayloadT],
+    #     # Generic[PayloadT],
-        # ^-XXX-^: not allowed? lul..
+    #     # ^-XXX-^: not allowed? lul..
-    )
+    # )
    ipc_msg_types: list[Msg] = []
    idx_msg_types: list[Msg] = []
-    defs_msg_types: list[Msg] = []
+    # defs_msg_types: list[Msg] = []
    nc_msg_types: list[Msg] = []
    for msgtype in __msg_types__:
@ -625,7 +625,7 @@ def mk_msg_spec(
        # TODO: wait why do we need the dynamic version here?
        # XXX ANSWER XXX -> BC INHERITANCE.. don't work w generics..
        #
-        # NOTE previously bc msgtypes WERE NOT inheritting
+        # NOTE previously bc msgtypes WERE NOT inheriting
        # directly the `Generic[PayloadT]` type, the manual method
        # of generic-paraming with `.__class_getitem__()` wasn't
        # working..
@ -662,38 +662,35 @@ def mk_msg_spec(
        # with `msgspec.structs.defstruct`
        # XXX ALSO DOESN'T WORK
-        defstruct_msgtype = defstruct(
+        # defstruct_msgtype = defstruct(
-            name=msgtype.__name__,
+        #     name=msgtype.__name__,
-            fields=[
+        #     fields=[
-                ('cid', str),
+        #         ('cid', str),
-                # XXX doesn't seem to work..
+        #         # XXX doesn't seem to work..
-                # ('pld', PayloadT),
+        #         # ('pld', PayloadT),
                ('pld', payload_type_union),
            ],
            bases=defstruct_bases,
        )
        defs_msg_types.append(defstruct_msgtype)
        #         ('pld', payload_type_union),
        #     ],
        #     bases=defstruct_bases,
        # )
        # defs_msg_types.append(defstruct_msgtype)
        # assert index_paramed_msg_type == manual_paramed_msg_subtype
        # paramed_msg_type = manual_paramed_msg_subtype
        # ipc_payload_msgs_type_union |= index_paramed_msg_type
    idx_spec: Union[Type[Msg]] = Union[*idx_msg_types]
-    def_spec: Union[Type[Msg]] = Union[*defs_msg_types]
+    # def_spec: Union[Type[Msg]] = Union[*defs_msg_types]
    nc_spec: Union[Type[Msg]] = Union[*nc_msg_types]
    specs: dict[str, Union[Type[Msg]]] = {
        'indexed_generics': idx_spec,
-        'defstruct': def_spec,
+        # 'defstruct': def_spec,
        'types_new_class': nc_spec,
    }
    msgtypes_table: dict[str, list[Msg]] = {
        'indexed_generics': idx_msg_types,
-        'defstruct': defs_msg_types,
+        # 'defstruct': defs_msg_types,
        'types_new_class': nc_msg_types,
    }
--- a/uv.lock
+++ b/uv.lock
@ -20,10 +20,38 @@ dependencies = [
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/fc/97/c783634659c2920c3fc70419e3af40972dbaf758daa229a7d6ea6135c90d/cffi-1.17.1.tar.gz", hash = "sha256:1c39c6016c32bc48dd54561950ebd6836e1670f2ae46128f67cf49e789c52824", size = 516621 }
 wheels = [
    { url = "https://files.pythonhosted.org/packages/6b/f4/927e3a8899e52a27fa57a48607ff7dc91a9ebe97399b357b85a0c7892e00/cffi-1.17.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:a45e3c6913c5b87b3ff120dcdc03f6131fa0065027d0ed7ee6190736a74cd401", size = 182264 },
    { url = "https://files.pythonhosted.org/packages/6c/f5/6c3a8efe5f503175aaddcbea6ad0d2c96dad6f5abb205750d1b3df44ef29/cffi-1.17.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:30c5e0cb5ae493c04c8b42916e52ca38079f1b235c2f8ae5f4527b963c401caf", size = 178651 },
    { url = "https://files.pythonhosted.org/packages/94/dd/a3f0118e688d1b1a57553da23b16bdade96d2f9bcda4d32e7d2838047ff7/cffi-1.17.1-cp311-cp311-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:f75c7ab1f9e4aca5414ed4d8e5c0e303a34f4421f8a0d47a4d019ceff0ab6af4", size = 445259 },
    { url = "https://files.pythonhosted.org/packages/2e/ea/70ce63780f096e16ce8588efe039d3c4f91deb1dc01e9c73a287939c79a6/cffi-1.17.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a1ed2dd2972641495a3ec98445e09766f077aee98a1c896dcb4ad0d303628e41", size = 469200 },
    { url = "https://files.pythonhosted.org/packages/1c/a0/a4fa9f4f781bda074c3ddd57a572b060fa0df7655d2a4247bbe277200146/cffi-1.17.1-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:46bf43160c1a35f7ec506d254e5c890f3c03648a4dbac12d624e4490a7046cd1", size = 477235 },
    { url = "https://files.pythonhosted.org/packages/62/12/ce8710b5b8affbcdd5c6e367217c242524ad17a02fe5beec3ee339f69f85/cffi-1.17.1-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:a24ed04c8ffd54b0729c07cee15a81d964e6fee0e3d4d342a27b020d22959dc6", size = 459721 },
    { url = "https://files.pythonhosted.org/packages/ff/6b/d45873c5e0242196f042d555526f92aa9e0c32355a1be1ff8c27f077fd37/cffi-1.17.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:610faea79c43e44c71e1ec53a554553fa22321b65fae24889706c0a84d4ad86d", size = 467242 },
    { url = "https://files.pythonhosted.org/packages/1a/52/d9a0e523a572fbccf2955f5abe883cfa8bcc570d7faeee06336fbd50c9fc/cffi-1.17.1-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:a9b15d491f3ad5d692e11f6b71f7857e7835eb677955c00cc0aefcd0669adaf6", size = 477999 },
    { url = "https://files.pythonhosted.org/packages/44/74/f2a2460684a1a2d00ca799ad880d54652841a780c4c97b87754f660c7603/cffi-1.17.1-cp311-cp311-musllinux_1_1_i686.whl", hash = "sha256:de2ea4b5833625383e464549fec1bc395c1bdeeb5f25c4a3a82b5a8c756ec22f", size = 454242 },
    { url = "https://files.pythonhosted.org/packages/f8/4a/34599cac7dfcd888ff54e801afe06a19c17787dfd94495ab0c8d35fe99fb/cffi-1.17.1-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:fc48c783f9c87e60831201f2cce7f3b2e4846bf4d8728eabe54d60700b318a0b", size = 478604 },
    { url = "https://files.pythonhosted.org/packages/34/33/e1b8a1ba29025adbdcda5fb3a36f94c03d771c1b7b12f726ff7fef2ebe36/cffi-1.17.1-cp311-cp311-win32.whl", hash = "sha256:85a950a4ac9c359340d5963966e3e0a94a676bd6245a4b55bc43949eee26a655", size = 171727 },
    { url = "https://files.pythonhosted.org/packages/3d/97/50228be003bb2802627d28ec0627837ac0bf35c90cf769812056f235b2d1/cffi-1.17.1-cp311-cp311-win_amd64.whl", hash = "sha256:caaf0640ef5f5517f49bc275eca1406b0ffa6aa184892812030f04c2abf589a0", size = 181400 },
    { url = "https://files.pythonhosted.org/packages/5a/84/e94227139ee5fb4d600a7a4927f322e1d4aea6fdc50bd3fca8493caba23f/cffi-1.17.1-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:805b4371bf7197c329fcb3ead37e710d1bca9da5d583f5073b799d5c5bd1eee4", size = 183178 },
    { url = "https://files.pythonhosted.org/packages/da/ee/fb72c2b48656111c4ef27f0f91da355e130a923473bf5ee75c5643d00cca/cffi-1.17.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:733e99bc2df47476e3848417c5a4540522f234dfd4ef3ab7fafdf555b082ec0c", size = 178840 },
    { url = "https://files.pythonhosted.org/packages/cc/b6/db007700f67d151abadf508cbfd6a1884f57eab90b1bb985c4c8c02b0f28/cffi-1.17.1-cp312-cp312-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:1257bdabf294dceb59f5e70c64a3e2f462c30c7ad68092d01bbbfb1c16b1ba36", size = 454803 },
    { url = "https://files.pythonhosted.org/packages/1a/df/f8d151540d8c200eb1c6fba8cd0dfd40904f1b0682ea705c36e6c2e97ab3/cffi-1.17.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:da95af8214998d77a98cc14e3a3bd00aa191526343078b530ceb0bd710fb48a5", size = 478850 },
    { url = "https://files.pythonhosted.org/packages/28/c0/b31116332a547fd2677ae5b78a2ef662dfc8023d67f41b2a83f7c2aa78b1/cffi-1.17.1-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:d63afe322132c194cf832bfec0dc69a99fb9bb6bbd550f161a49e9e855cc78ff", size = 485729 },
    { url = "https://files.pythonhosted.org/packages/91/2b/9a1ddfa5c7f13cab007a2c9cc295b70fbbda7cb10a286aa6810338e60ea1/cffi-1.17.1-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:f79fc4fc25f1c8698ff97788206bb3c2598949bfe0fef03d299eb1b5356ada99", size = 471256 },
    { url = "https://files.pythonhosted.org/packages/b2/d5/da47df7004cb17e4955df6a43d14b3b4ae77737dff8bf7f8f333196717bf/cffi-1.17.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b62ce867176a75d03a665bad002af8e6d54644fad99a3c70905c543130e39d93", size = 479424 },
    { url = "https://files.pythonhosted.org/packages/0b/ac/2a28bcf513e93a219c8a4e8e125534f4f6db03e3179ba1c45e949b76212c/cffi-1.17.1-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:386c8bf53c502fff58903061338ce4f4950cbdcb23e2902d86c0f722b786bbe3", size = 484568 },
    { url = "https://files.pythonhosted.org/packages/d4/38/ca8a4f639065f14ae0f1d9751e70447a261f1a30fa7547a828ae08142465/cffi-1.17.1-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:4ceb10419a9adf4460ea14cfd6bc43d08701f0835e979bf821052f1805850fe8", size = 488736 },
    { url = "https://files.pythonhosted.org/packages/86/c5/28b2d6f799ec0bdecf44dced2ec5ed43e0eb63097b0f58c293583b406582/cffi-1.17.1-cp312-cp312-win32.whl", hash = "sha256:a08d7e755f8ed21095a310a693525137cfe756ce62d066e53f502a83dc550f65", size = 172448 },
    { url = "https://files.pythonhosted.org/packages/50/b9/db34c4755a7bd1cb2d1603ac3863f22bcecbd1ba29e5ee841a4bc510b294/cffi-1.17.1-cp312-cp312-win_amd64.whl", hash = "sha256:51392eae71afec0d0c8fb1a53b204dbb3bcabcb3c9b807eedf3e1e6ccf2de903", size = 181976 },
    { url = "https://files.pythonhosted.org/packages/8d/f8/dd6c246b148639254dad4d6803eb6a54e8c85c6e11ec9df2cffa87571dbe/cffi-1.17.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:f3a2b4222ce6b60e2e8b337bb9596923045681d71e5a082783484d845390938e", size = 182989 },
    { url = "https://files.pythonhosted.org/packages/8b/f1/672d303ddf17c24fc83afd712316fda78dc6fce1cd53011b839483e1ecc8/cffi-1.17.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:0984a4925a435b1da406122d4d7968dd861c1385afe3b45ba82b750f229811e2", size = 178802 },
    { url = "https://files.pythonhosted.org/packages/0e/2d/eab2e858a91fdff70533cab61dcff4a1f55ec60425832ddfdc9cd36bc8af/cffi-1.17.1-cp313-cp313-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:d01b12eeeb4427d3110de311e1774046ad344f5b1a7403101878976ecd7a10f3", size = 454792 },
    { url = "https://files.pythonhosted.org/packages/75/b2/fbaec7c4455c604e29388d55599b99ebcc250a60050610fadde58932b7ee/cffi-1.17.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:706510fe141c86a69c8ddc029c7910003a17353970cff3b904ff0686a5927683", size = 478893 },
    { url = "https://files.pythonhosted.org/packages/4f/b7/6e4a2162178bf1935c336d4da8a9352cccab4d3a5d7914065490f08c0690/cffi-1.17.1-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:de55b766c7aa2e2a3092c51e0483d700341182f08e67c63630d5b6f200bb28e5", size = 485810 },
    { url = "https://files.pythonhosted.org/packages/c7/8a/1d0e4a9c26e54746dc08c2c6c037889124d4f59dffd853a659fa545f1b40/cffi-1.17.1-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:c59d6e989d07460165cc5ad3c61f9fd8f1b4796eacbd81cee78957842b834af4", size = 471200 },
    { url = "https://files.pythonhosted.org/packages/26/9f/1aab65a6c0db35f43c4d1b4f580e8df53914310afc10ae0397d29d697af4/cffi-1.17.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:dd398dbc6773384a17fe0d3e7eeb8d1a21c2200473ee6806bb5e6a8e62bb73dd", size = 479447 },
    { url = "https://files.pythonhosted.org/packages/5f/e4/fb8b3dd8dc0e98edf1135ff067ae070bb32ef9d509d6cb0f538cd6f7483f/cffi-1.17.1-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:3edc8d958eb099c634dace3c7e16560ae474aa3803a5df240542b305d14e14ed", size = 484358 },
    { url = "https://files.pythonhosted.org/packages/f1/47/d7145bf2dc04684935d57d67dff9d6d795b2ba2796806bb109864be3a151/cffi-1.17.1-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:72e72408cad3d5419375fc87d289076ee319835bdfa2caad331e377589aebba9", size = 488469 },
    { url = "https://files.pythonhosted.org/packages/bf/ee/f94057fa6426481d663b88637a9a10e859e492c73d0384514a17d78ee205/cffi-1.17.1-cp313-cp313-win32.whl", hash = "sha256:e03eab0a8677fa80d646b5ddece1cbeaf556c313dcfac435ba11f107ba117b5d", size = 172475 },
    { url = "https://files.pythonhosted.org/packages/7c/fc/6a8cb64e5f0324877d503c854da15d76c1e50eb722e320b15345c4d0c6de/cffi-1.17.1-cp313-cp313-win_amd64.whl", hash = "sha256:f6a16c31041f09ead72d69f583767292f750d24913dadacf5756b966aacb3f1a", size = 182009 },
 ]
@ -321,6 +349,7 @@ name = "tractor"
 version = "0.1.0a6.dev0"
 source = { editable = "." }
 dependencies = [
    { name = "cffi" },
    { name = "colorlog" },
    { name = "msgspec" },
    { name = "pdbp" },
@ -342,6 +371,7 @@ dev = [
 [package.metadata]
 requires-dist = [
    { name = "cffi", specifier = ">=1.17.1" },
    { name = "colorlog", specifier = ">=6.8.2,<7" },
    { name = "msgspec", specifier = ">=0.19.0" },
    { name = "pdbp", specifier = ">=1.6,<2" },
Author	SHA1	Message	Date
Guillermo Rodriguez	7ea9d3bf31	Important RingBuffBytesSender fix on non batched mode! & downgrade nix-shell python to lowest supported	2025-03-27 19:14:21 -03:00
Guillermo Rodriguez	1bade68c79	Catch trio cancellation on RingBuffReceiver bg eof listener task, add batched mode to RingBuffBytesSender	2025-03-27 19:14:21 -03:00
Guillermo Rodriguez	5b51bb47a4	Add direct read method on EventFD Type hint all ctx managers in _ringbuf.py Remove unnecesary send lock on ring chan sender Handle EOF on ring chan receiver Rename ringbuf tests to make it less redundant	2025-03-27 19:14:21 -03:00
Guillermo Rodriguez	7d4e745e25	Add direct ctx managers for RB channels	2025-03-27 19:14:21 -03:00
Guillermo Rodriguez	9ee585e599	Improve test_ringbuf test, drop MsgTransport ring buf impl for now in favour of a trio.abc.Channel[bytes] impl, add docstrings	2025-03-27 19:14:21 -03:00
Guillermo Rodriguez	e56306e8f0	Switch `tractor.ipc.MsgTransport.stream` type to `trio.abc.Stream` Add EOF signaling mechanism Support proper `receive_some` end of stream semantics Add StapledStream non-ipc test Create MsgpackRBStream similar to MsgpackTCPStream for buffered whole-msg reads Add EventFD.read cancellation on EventFD.close mechanism using cancel scope Add test for eventfd cancellation Improve and add docstrings	2025-03-27 19:14:21 -03:00
Guillermo Rodriguez	c424f6c8d5	Better encapsulate RingBuff ctx managment methods and support non ipc usage Add trio.StrictFIFOLock on sender.send_all Support max_bytes argument on receive_some, keep track of write_ptr on receiver Add max_bytes receive test test_ringbuf_max_bytes Add docstrings to all ringbuf tests Remove EFD_NONBLOCK support, not necesary anymore since we can use abandon_on_cancel=True on trio.to_thread.run_sync Close eventfd's after usage on open_ringbuf	2025-03-27 19:14:21 -03:00
Guillermo Rodriguez	017bc50582	Break out transport protocol and tcp specifics into their own submodules under tractor.ipc	2025-03-27 19:14:21 -03:00
Guillermo Rodriguez	0bd78a0a12	Add buf_size to RBToken and add sender cancel test, move disable_mantracker to its own _mp_bs module	2025-03-27 19:14:21 -03:00
Guillermo Rodriguez	c18d2548f6	Make ring buf api use pickle-able RBToken	2025-03-27 19:14:21 -03:00
Guillermo Rodriguez	4a47b4a1e3	Address some of fomo\'s comments	2025-03-27 19:14:20 -03:00
Guillermo Rodriguez	fc7a8a5441	Handle cancelation on EventFD.read	2025-03-27 19:14:20 -03:00
Guillermo Rodriguez	22a84bcb74	Add module headers and fix spacing on tractor._ipc._linux	2025-03-27 19:14:20 -03:00
Guillermo Rodriguez	bae342a7bc	Move RingBuffSender\|Receiver to its own tractor.ipc._ringbuf module	2025-03-27 19:14:20 -03:00
Guillermo Rodriguez	ef9b30639f	Move linux specifics from tractor.ipc._shm into tractor.ipc._linux	2025-03-27 19:14:20 -03:00
Guillermo Rodriguez	8e294b8b7c	Move tractor._shm to tractor.ipc._shm	2025-03-27 19:14:20 -03:00
Guillermo Rodriguez	fad839ee78	move tractor._ipc.py into tractor.ipc._chan.py	2025-03-27 19:14:20 -03:00
Guillermo Rodriguez	ecf84991a4	General improvements EventFD class now expects the fd to already be init with open_eventfd RingBuff Sender and Receiver fully manage SharedMemory and EventFD lifecycles, no aditional ctx mngrs needed Separate ring buf tests into its own test bed Add parametrization to test and cancellation Add docstrings Add simple testing data gen module .samples	2025-03-27 19:14:20 -03:00
Guillermo Rodriguez	4c53c3e9b3	IPC ring bug impl with async read	2025-03-27 19:14:20 -03:00
Tyler Goodlet	e94fd65e91	Updates from latest `piker.data._sharedmem` changes	2025-03-27 15:51:53 -04:00
Tyler Goodlet	c67f72ca48	Pass `str` dtype for `use_str` case	2025-03-27 15:51:53 -04:00
Tyler Goodlet	c89467cbca	Allocate size-specced "empty" sequence from default values by type	2025-03-27 15:51:53 -04:00
Tyler Goodlet	0ddf450346	Mod define `_USE_POSIX`, add a of of todos	2025-03-27 15:51:53 -04:00
Tyler Goodlet	5f085b94ab	Parametrize rw test with variable frame sizes Demonstrates fixed size frame-oriented reads by the child where the parent only transmits a "read" stream msg on "frame fill events" such that the child incrementally reads the shm list data (much like in a real-time-buffered streaming system).	2025-03-27 15:51:53 -04:00
Tyler Goodlet	bab65c6faa	Add `ShmList` slice support in `.__getitem__()`	2025-03-27 15:51:53 -04:00
Tyler Goodlet	3f64323a1a	Rename token type to `NDToken` in the style of `nptyping`	2025-03-27 15:51:53 -04:00
Tyler Goodlet	8344564ce7	Don't require runtime (for now), type annot fixing	2025-03-27 15:51:53 -04:00
Tyler Goodlet	1a6d8639c4	Add repetitive attach to existing segment test	2025-03-27 15:51:53 -04:00
Tyler Goodlet	f81138a968	Add initial readers-writer shm list tests	2025-03-27 15:51:53 -04:00
Tyler Goodlet	08c60683ea	Add `ShmList` wrapping the stdlib's `ShareableList` First attempt at getting `multiprocessing.shared_memory.ShareableList` working; we wrap the stdlib type with a readonly attr and a `.key` for cross-actor lookup. Also, rename all `numpy` specific routines to have a `ndarray` suffix in the func names.	2025-03-27 15:51:53 -04:00
Tyler Goodlet	b0de8d0f88	Initial module import from `piker.data._sharemem` More or less a verbatim copy-paste minus some edgy variable naming and internal `piker` module imports. There is a bunch of OHLC related defaults that need to be dropped and we need to adjust to an optional dependence on `numpy` by supporting shared lists as per the mp docs.	2025-03-27 15:51:53 -04:00
Tyler Goodlet	eb12029372	Mask top level import of `.hilevel` Since it isn't required until the landing of the new service-manager stuff in #12; was an oversight from commit `0607a31dddeba032a2cf7d9fe605edd9d7bb4846`.	2025-03-27 15:51:34 -04:00
Tyler Goodlet	27a97e8b1c	Add `.runtime()`-emit to `._invoke()` to report final result msg in the child	2025-03-27 15:51:34 -04:00
Tyler Goodlet	8921443503	Add `MsgStream._stop_msg` use new `PldRx` API In particular ensuring we use `ctx._pld_rx.recv_msg_nowait()` from `.receive_nowait()` (which is called from `.aclose()`) such that we ALWAYS (can) set the surrounding `Context._result/._outcome_msg` attrs on reception of a final `Return`!! This fixes a final stream-teardown-race-condition-bug where prior we normally didn't set the `Context._result/._outcome_msg` in such cases. This is precisely because `.receive_nowait()` only returns the `pld` and when called from `.aclose()` this value is discarded, meaning so is its boxing `Return` despite consuming it from the underlying `._rx_chan`.. Longer term this should be solved differently by ensuring such races cases are handled at a higher scope like inside `Context._deliver_msg()` or the `Portal.open_context()` enter/exit blocks? Add a detailed warning note and todos for all this around the special case block!	2025-03-27 15:51:34 -04:00
Tyler Goodlet	c8dd4a3452	Add `Context._outcome_msg` use new `PldRx` API Such that any `Return` is always capture for each ctx instance and set in `._deliver_msg()` normally; ensures we can at least introspect for it when missing (like in a recently discovered stream teardown race bug). Yes this augments the already existing `._result` which is dedicated for the `._outcome_msg.pld` in the non-error case; we might want to see if there's a nicer way to directly proxy ref to that without getting the pre-pld-decoded `Raw` form with `msgspec`? Also use the new `ctx._pld_rx.recv_msg()` and drop assigning `pld_rx._ctx`.	2025-03-27 15:51:34 -04:00
Tyler Goodlet	7b43bd9f25	Slight `PldRx` rework to simplify Namely renaming and tweaking the `MsgType` receiving methods, - `.recv_msg()` from what was `.recv_msg_w_pld()` which both receives the IPC msg from the underlying `._rx_chan` and then decodes its payload with `.decode_pld()`; it now also log reports on the different "stage of SC dialog protocol" msg types via a `match/case`. - a new `.recv_msg_nowait()` sync equivalent of ^ (was `.recv_pld_nowait()`) who's use was the source of a recently discovered bug where any final `Return.pld` is being consumed-n-discarded by by `MsgStream.aclose()` depending on ctx/stream teardown race conditions.. Also, - remove all the "instance persistent" ipc-ctx attrs, specifically the optional `_ipc`, `_ctx` and the `.wraps_ipc()` cm, since none of them were ever really needed/used; all methods which require a `Context/MsgStream` are explicitly always passed. - update a buncha typing namely to use the more generic-styled `PayloadT` over `Any` and obviously `MsgType[PayloadT]`.	2025-03-27 15:51:34 -04:00
Tyler Goodlet	de8d8afc41	Rename ext-types with `msgspec` suite module	2025-03-27 15:51:34 -04:00
Tyler Goodlet	9b89d79ef6	Complete rename to parent->child IPC ctx peers Now changed in all comments docs and test-code content such that we aren't using the "caller"->"callee" semantics anymore.	2025-03-27 15:51:34 -04:00
Tyler Goodlet	99958cc727	Fix msg-draining on `parent_never_opened_stream`! Repairs a bug in `drain_to_final_msg()` where in the `Yield()` case block we weren't guarding against the `ctx._stream is None` edge case which should be treated a `continue`-draining (not a `break` or attr-error!!) situation since the peer task maybe be continuing to send `Yield` but has not yet sent an outcome msg (one of `Return/Error/ContextCancelled`) to terminate the loop. Ensure we explicitly warn about this case as well as `.cancel()` emit on a taskc. Thanks again to @guille for discovering this! Also add temporary `.info()`s around rxed `Return` msgs as part of trying to debug a different bug discovered while updating the context-semantics test suite (in a prior commit).	2025-03-27 15:51:34 -04:00
Tyler Goodlet	4e5742a056	Extend ctx semantics suite for streaming edge cases! Muchas grax to @guilledk for finding the first issue which kicked of this further scrutiny of the `tractor.Context` and `MsgStream` semantics test suite with a strange edge case where, - if the parent opened and immediately closed a stream while the remote child task started and continued (without terminating) to send msgs the parent's `open_context().__aexit__()` would not block on the child to complete! => this was seemingly due to a bug discovered inside the `.msg._ops.drain_to_final_msg()` stream handling case logic where we are NOT checking if `Context._stream` is non-`None`! As such this, - extends the `test_caller_closes_ctx_after_callee_opens_stream` (now renamed, see below) to include cases for all combinations of the child and parent sending before receiving on the stream as well as all placements of `Context.cancel()` in the parent before, around and after the stream open. - uses the new `expect_ctxc()` for expecting the taskc (`trio.Task` cancelled)` cases. - also extends the `test_callee_closes_ctx_after_stream_open` (also renamed) to include the case where the parent sends a msg before it receives. => this case has unveiled yet-another-bug where somehow the underlying `MsgStream._rx_chan: trio.ReceiveMemoryChannel` is allowing the child's `Return[None]` msg be consumed and NOT in a place where it is correctly set as `Context._result` resulting in the parent hanging forever inside `._ops.drain_to_final_msg()`.. Alongside, - start renaming using the new "remote-task-peer-side" semantics throughout the test module: "caller" -> "parent", "callee" -> "child".	2025-03-27 15:51:34 -04:00
Tyler Goodlet	3e1d18497f	Deliver a `MaybeBoxedError` from `.expect_ctxc()` Just like we do from the `.devx._debug.open_crash_handler()`, this allows checking various attrs on the raised `ContextCancelled` much like `with pytest.raises() as excinfo:`.	2025-03-27 15:51:34 -04:00
Tyler Goodlet	f3b10a8032	Support `ctx: UnionType` annots for `@tractor.context` eps	2025-03-27 15:51:34 -04:00
Tyler Goodlet	305e1d0347	Avoid attr-err when `._ipc_msg==None` Seems this can happen in particular when we raise a `MessageTypeError` on the sender side of a `Context`, since there isn't any msg relayed from the other side (though i'm wondering if MTE should derive from RAE then considering this case?). Means `RemoteActorError.boxed_type = None` in such cases instead of raising an attr-error for the `None.boxed_type_str`.	2025-03-27 15:51:34 -04:00
Tyler Goodlet	80fa61af61	Facepalm, fix logic misstep on child side Namely that `add_hooks: bool` should be the same as on the rent side.. Also, just drop the now unused `iter_maybe_sends`. This makes the suite entire greeeeen btw, including the new sub-suite which i hadn't runt before Bo	2025-03-27 15:51:33 -04:00
Tyler Goodlet	048a232a6e	Rework IPC-using `test_caps_basesd_msging` tests Namely renaming and massively simplifying it to a new `test_ext_types_over_ipc` which avoids all the wacky "parent dictates what sender should be able to send beforehand".. Instead keep it simple and just always try to send the same small set of types over the wire with expect-logic to handle each case, - use the new `dec_hook`/`ext_types` args to `mk_[co]dec()` routines for pld-spec ipc transport. - always try to stream a small set of types from the child with logic to handle the cases expected to error. Other, - draft a `test_pld_limiting_usage` to check runtime raising of bad API usage; haven't run it yet tho. - move `test_custom_extension_types` to top of mod so that the `enc/dec_nsp()` hooks can be reffed from test parametrizations. - comment out (and maybe remove) the old routines for `iter_maybe_sends`, `test_limit_msgspec`, `chk_pld_type`. XXX TODO, turns out the 2 failing cases from this suite have exposed an an actual bug with `MsgTypeError` unpacking where the `ipc_msg=` input is being set to `None` ?? -> see the comment at the bottom of `._exceptions._mk_recv_mte()` which seems to describe the likely culprit?	2025-03-27 15:51:33 -04:00
Tyler Goodlet	337385762b	Raise RTE from `limit_plds()` on no `curr_ctx` Since it should only be used from within a `Portal.open_context()` scope, make sure the caller knows that! Also don't hide the frame in tb if the immediate function errors..	2025-03-27 15:51:33 -04:00
Tyler Goodlet	fbb8c7ecd0	Offer a `mods: list` to `dec_type_union()`; drop importing this-mod	2025-03-27 15:51:33 -04:00
Tyler Goodlet	f8cc034630	Tweak type-error messages for when `ext_types` is missing	2025-03-27 15:51:33 -04:00
Tyler Goodlet	56d0f10195	Move `Union` serializers to new `msg.` mod Namely moving `enc/dec_type_union()` from the test mod to a new `tractor.msg._exts` for general use outside the test suite.	2025-03-27 15:51:33 -04:00
Tyler Goodlet	49aeae4150	Finally get type-extended `msgspec` fields workinn By using our new `PldRx` design we can, - pass through the pld-spec & a `dec_hook()` to our `MsgDec` which is used to configure the underlying `.dec: msgspec.msgpack.Decoder` - pass through a `enc_hook()` to `mk_codec()` and use it to conf the equiv `MsgCodec.enc` such that sent msg-plds are converted prior to transport. The trick ended up being just to always union the `mk_dec()` extension-types spec with the normaly with the `msgspec.Raw` pld-spec such that the `dec_hook()` is only invoked for payload types tagged by the encoder/sender side B) A variety of impl tweaks to make it all happen as well as various cleanups in the `.msg._codec` mod include, - `mk_dec()` no defaul `spec` arg, better doc string, accept the new `ext_types` arg, doing the union of that with `msgspec.Raw`. - proto-ed a now unused `mk_boxed_ext_struct()` which will likely get removed since it ended up that our `PayloadMsg` structs already cover the ext-type-hook requirement that the decoder is passed a `.type=msgspec.Struct` of some sort in order for `.dec_hook` to be used. - add a `unpack_spec_types()` util fn for getting the `set[Type]` from from a `Union[Type]` annotation instance. - mk the default `mk_codec(pc_pld_spec = Raw,)` since the `PldRx` design was already passing/overriding it and it doesn't make much sense to use `Any` anymore for the same reason; it will cause various `Context` apis to now break. \|_ also accept a `enc_hook()` and `ext_types` which are used to maybe config the `.msgpack.Encoder` - generally tweak a bunch of comments-as-docs and todos namely the ones that are completed after the pld-rx design was implemented. Also, - mask the non-functioning `'defstruct'` approach `inside `.msg.types.mk_msg_spec()` to prep for its removal. Adjust the test suite (rn called `test_caps_based_msging`), - add a new suite `test_custom_extension_types` and move and use the `enc/dec_nsp()` hooks to the mod level for its use. - prolly planning to drop the `test_limit_msgspec` suite since it's mostly replaced by the `test_pldrx_limiting` mod's version? - originally was tweaking a bunch in `test_codec_hooks_mod` but likely it will get mostly rewritten to be simpler and simply verify that ext-typed fields can be used over IPC `Context`s between actors (as originally intended for this sub-suite).	2025-03-27 15:51:33 -04:00