tractor/tractor/to_asyncio.py

# 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/>.

'''
Infection apis for ``asyncio`` loops running ``trio`` using guest mode.

'''
from __future__ import annotations
import asyncio
from asyncio.exceptions import (
    CancelledError,
)
from contextlib import asynccontextmanager as acm
from dataclasses import dataclass
import inspect
import platform
import sys
import traceback
from typing import (
    Any,
    Callable,
    AsyncIterator,
    Awaitable,
)

import tractor
from tractor._exceptions import (
    InternalError,
    TrioTaskExited,
    TrioCancelled,
    AsyncioTaskExited,
    AsyncioCancelled,
)
from tractor.runtime._state import (
    debug_mode,
    _runtime_vars,
)
from tractor._context import Unresolved
from tractor import devx
from tractor.log import (
    get_logger,
    StackLevelAdapter,
)
# TODO, wite the equiv of `trio.abc.Channel` but without attrs..
# -[ ] `trionics.chan_types.ChanStruct` maybe?
# from tractor.msg import (
#     pretty_struct,
# )
from tractor.trionics import (
    is_multi_cancelled,
)
from tractor.trionics._broadcast import (
    broadcast_receiver,
    BroadcastReceiver,
)
import trio
from outcome import (
    Error,
    Outcome,
)

log: StackLevelAdapter = get_logger()


__all__ = [
    'run_task',
    'run_as_asyncio_guest',
]

if (_py_313 := (
        ('3', '13')
        ==
        platform.python_version_tuple()[:-1]
    )
):
    # 3.13+ only.. lel.
    # https://docs.python.org/3.13/library/asyncio-queue.html#asyncio.QueueShutDown
    from asyncio import (
        QueueShutDown,
    )
else:
    QueueShutDown = False


# TODO, generally speaking we can generalize this abstraction as,
#
# > A "SC linked, inter-event-loop" channel for comms between
# > a `parent: trio.Task` -> `child: asyncio.Task` pair.
#
# It is **very similar** in terms of its operation as a "supervision
# scope primitive" to that of our `._context.Context` with the only
# difference being in how the tasks conduct msg-passing comms.
#
# For `LinkedTaskChannel` we are passing the equivalent of (once you
# include all the recently added  `._trio/aio_to_raise`
# exd-as-signals) our SC-dialog-proto over each asyncIO framework's
# mem-chan impl,
#
# verus in `Context`
#
# We are doing the same thing but msg-passing comms happens over an
# IPC transport between tasks in different memory domains.

@dataclass
class LinkedTaskChannel(
    trio.abc.Channel,

    # XXX LAME! meta-base conflict..
    # pretty_struct.Struct,
):
    '''
    A "linked task channel" which allows for two-way synchronized msg
    passing between a ``trio``-in-guest-mode task and an ``asyncio``
    task scheduled in the host loop.

    '''
    # ?TODO, rename as `._aio_q` since it's 2-way?
    _to_aio: asyncio.Queue
    _from_aio: trio.MemoryReceiveChannel

    _to_trio: trio.MemorySendChannel
    _trio_cs: trio.CancelScope
    _trio_task: trio.Task
    _aio_task_complete: trio.Event

    _closed_by_aio_task: bool = False
    _suppress_graceful_exits: bool = True

    _trio_err: BaseException|None = None
    _trio_to_raise: (
        AsyncioTaskExited|  # aio task exits while trio ongoing
        AsyncioCancelled|  # aio task is (self-)cancelled
        BaseException|
        None
    ) = None
    _trio_exited: bool = False

    # set after `asyncio.create_task()`
    _aio_task: asyncio.Task|None = None
    _aio_err: BaseException|None = None
    _aio_to_raise: (
        TrioTaskExited|  # trio task exits while aio ongoing
        BaseException|
        None
    ) = None
    # _aio_first: Any|None = None  # TODO?
    _aio_result: Any|Unresolved = Unresolved

    def _final_result_is_set(self) -> bool:
        return self._aio_result is not Unresolved

    # TODO? equiv from `Context`?
    # @property
    # def has_outcome(self) -> bool:
    #     return (
    #         bool(self.maybe_error)
    #         or
    #         self._final_result_is_set()
    #     )

    async def wait_for_result(
        self,
        hide_tb: bool = True,

    ) -> Any:
        '''
        Wait for the `asyncio.Task.result()` from `trio`

        '''
        __tracebackhide__: bool = hide_tb
        assert self._portal, (
            '`Context.wait_for_result()` can not be called from callee side!'
        )
        if self._final_result_is_set():
            return self._aio_result

        async with translate_aio_errors(
            chan=self,
            wait_aio_task=False,
        ):
            await self._aio_task_complete.wait()

        if (
            not self._final_result_is_set()
        ):
            if (trio_to_raise := self._trio_to_raise):
                raise trio_to_raise from self._aio_err

            elif aio_err := self._aio_err:
                raise aio_err

            else:
                raise InternalError(
                    f'Asyncio-task has no result or error set !?\n'
                    f'{self._aio_task}'
                )

        return self._aio_result

    _broadcaster: BroadcastReceiver|None = None

    async def aclose(self) -> None:
        await self._from_aio.aclose()

    # ?TODO? async version of this?
    def started_nowait(
        self,
        val: Any = None,
    ) -> None:
        '''
        Synchronize aio-side with its trio-parent.

        '''
        self._aio_started_val = val
        return self._to_trio.send_nowait(val)

    # TODO, mk this side-agnostic?
    #
    # -[ ] add private meths for both sides and dynamically
    #    determine which to use based on task-type read at calltime?
    #    -[ ] `._recv_trio()`: receive to trio<-asyncio
    #    -[ ] `._send_trio()`: send from trio->asyncio
    #    -[ ] `._recv_aio()`: send from asyncio->trio
    #    -[ ] `._send_aio()`: receive to asyncio<-trio
    #
    # -[ ] pass the instance to the aio side instead of the separate
    #    per-side chan types?
    #
    async def receive(self) -> Any:
        '''
        Receive a value `trio.Task` <- `asyncio.Task`.

        Note the tasks in each loop are "SC linked" as a pair with
        exception/cancel handling to teardown both sides on any
        unexpected error or cancellation.

        '''
        try:
            # TODO: do we need this to guarantee asyncio code get's
            # cancelled in the case where the trio side somehow creates
            # a state where the asyncio cycle-task isn't getting the
            # cancel request sent by (in theory) the last checkpoint
            # cycle on the trio side?
            # await trio.lowlevel.checkpoint()
            return await self._from_aio.receive()

        except BaseException as err:
            async with translate_aio_errors(
                chan=self,
                # NOTE, determined by `open_channel_from()` input arg
                suppress_graceful_exits=self._suppress_graceful_exits,

                # XXX: obviously this will deadlock if an on-going stream is
                # being procesed.
                # wait_on_aio_task=False,
            ):
                raise err

    async def get(self) -> Any:
        '''
        Receive a value `asyncio.Task` <- `trio.Task`.

        This is equiv to `await self._to_aio.get()`.

        '''
        return await self._to_aio.get()

    async def send(self, item: Any) -> None:
        '''
        Send a value `trio.Task` -> `asyncio.Task`
        by enqueuing `item` onto the internal
        `asyncio.Queue` via `put_nowait()`.

        '''
        self._to_aio.put_nowait(item)

    # TODO? could we only compile-in this method on an instance
    # handed to the `asyncio`-side, i.e. the fn invoked with
    # `.open_channel_from()`.
    def send_nowait(
        self,
        item: Any,
    ) -> None:
        '''
        Send a value through FROM the `asyncio.Task` to
        the `trio.Task` NON-BLOCKING.

        This is equiv to `self._to_trio.send_nowait()`.

        '''
        self._to_trio.send_nowait(item)

    # TODO? needed?
    # async def wait_aio_complete(self) -> None:
    #     await self._aio_task_complete.wait()

    def cancel_asyncio_task(
        self,
        msg: str = '',
    ) -> None:
        self._aio_task.cancel(
            msg=msg,
        )

    def closed(self) -> bool:
        return self._from_aio._closed  # type: ignore

    # TODO: shoud we consider some kind of "decorator" system
    # that checks for structural-typing compatibliity and then
    # automatically adds this ctx-mngr-as-method machinery?
    @acm
    async def subscribe(
        self,

    ) -> AsyncIterator[BroadcastReceiver]:
        '''
        Allocate and return a ``BroadcastReceiver`` which delegates
        to this inter-task channel.

        This allows multiple local tasks to receive each their own copy
        of this message stream.

        See ``tractor._streaming.MsgStream.subscribe()`` for further
        similar details.
        '''
        if self._broadcaster is None:

            bcast = self._broadcaster = broadcast_receiver(
                self,
                # use memory channel size by default
                self._from_aio._state.max_buffer_size,  # type: ignore
                receive_afunc=self.receive,
            )

            self.receive = bcast.receive  # type: ignore

        async with self._broadcaster.subscribe() as bstream:
            assert bstream.key != self._broadcaster.key
            assert bstream._recv == self._broadcaster._recv
            yield bstream


def _run_asyncio_task(
    func: Callable,
    *,
    qsize: int = 1,
    provide_channels: bool = False,
    suppress_graceful_exits: bool = True,
    hide_tb: bool = True,
    **kwargs,

) -> LinkedTaskChannel:
    '''
    Run an `asyncio`-compat async function or generator in a task,
    return or stream the result back to the caller
    `trio.lowleve.Task`.

    '''
    __tracebackhide__: bool = hide_tb
    if not (actor := tractor.current_actor()).is_infected_aio():
        raise RuntimeError(
            f'`infect_asyncio: bool` mode is not enabled ??\n'
            f'Ensure you pass `ActorNursery.start_actor(infect_asyncio=True)`\n'
            f'\n'
            f'{actor}\n'
        )

    # ITC (inter task comms), these channel/queue names are mostly from
    # ``asyncio``'s perspective.
    aio_q = from_trio = asyncio.Queue(qsize)  # type: ignore
    to_trio, from_aio = trio.open_memory_channel(qsize)  # type: ignore

    args = tuple(inspect.getfullargspec(func).args)
    if getattr(func, '_tractor_steam_function', None):
        # the assumption is that the target async routine accepts the
        # send channel then it intends to yield more then one return
        # value otherwise it would just return ;P
        assert qsize > 1

    trio_task: trio.Task = trio.lowlevel.current_task()
    trio_cs = trio.CancelScope()
    aio_task_complete = trio.Event()

    chan = LinkedTaskChannel(
        _to_aio=aio_q,  # asyncio.Queue
        _from_aio=from_aio,  # recv chan
        _to_trio=to_trio,  # send chan
        _trio_cs=trio_cs,
        _trio_task=trio_task,
        _aio_task_complete=aio_task_complete,
        _suppress_graceful_exits=suppress_graceful_exits,
    )

    # allow target func to accept/stream results manually by name
    if 'to_trio' in args:
        kwargs['to_trio'] = to_trio

    if 'from_trio' in args:
        kwargs['from_trio'] = from_trio

    if 'chan' in args:
        kwargs['chan'] = chan

    if provide_channels:
        assert (
            'to_trio' in args
            or
            'chan' in args
        )

    coro = func(**kwargs)

    async def wait_on_coro_final_result(
        to_trio: trio.MemorySendChannel,
        coro: Awaitable,
        aio_task_complete: trio.Event,

    ) -> None:
        '''
        Await input `coro` as/in an `asyncio.Task` and deliver final
        `return`-ed result back to `trio`.

        '''
        nonlocal chan

        orig = result = id(coro)
        try:
            # XXX TODO UGH!
            # this seems to break a `test_sync_pause_from_aio_task`
            # in a REALLY weird way where a `dict` value for
            # `_runtime_vars['_root_addrs']` is delivered from the
            # parent actor??
            #
            # XXX => see masked `.set_trace()` block in
            # `Actor.from_parent()`..
            #
            # with devx.maybe_open_crash_handler(
            #     # XXX, if trio-side exits (intentionally) we
            #     # shouldn't care bc it should have its own crash
            #     # handling logic.
            #     ignore={TrioTaskExited,},
            # ) as _bxerr:
            result: Any = await coro

            chan._aio_result = result
        except BaseException as aio_err:
            chan._aio_err = aio_err
            if isinstance(aio_err, CancelledError):
                log.runtime(
                    '`asyncio` task was cancelled..\n'
                )
            else:
                log.exception(
                    '`asyncio` task errored\n'
                )
            raise
        else:
            if (
                result != orig
                and
                chan._aio_err is None
                and

                # in the `open_channel_from()` case we don't
                # relay through the "return value".
                not provide_channels
            ):
                to_trio.send_nowait(result)

        finally:
            # if the task was spawned using `open_channel_from()`
            # then we close the channels on exit.
            if provide_channels:
                # breakpoint()  # TODO! why no work!?
                # import pdbp; pdbp.set_trace()

                # IFF there is a blocked trio waiter, we set the
                # aio-side error to be an explicit "exited early"
                # (much like a `Return` in our SC IPC proto) for the
                # `.open_channel_from()` case where the parent trio
                # task might not wait directly for a final returned
                # result (i.e. the trio side might be waiting on
                # a streamed value) - this is a signal that the
                # asyncio.Task has returned early!
                #
                # TODO, solve other cases where trio side might,
                # - raise Cancelled but aio side exits on next tick.
                # - raise error but aio side exits on next tick.
                # - raise error and aio side errors "independently"
                #   on next tick (SEE draft HANDLER BELOW).
                stats: trio.MemoryChannelStatistics = to_trio.statistics()
                if (
                    stats.tasks_waiting_receive
                    and
                    not chan._aio_err
                ):
                    chan._trio_to_raise = AsyncioTaskExited(
                        f'Task exited with final result: {result!r}\n'
                    )

                # XXX ALWAYS close the child-`asyncio`-task-side's
                # `to_trio` handle which will in turn relay
                # a `trio.EndOfChannel` to the `trio`-parent.
                # Consequently the parent `trio` task MUST ALWAYS
                # check for any `chan._aio_err` to be raised when it
                # receives an EoC.
                #
                # NOTE, there are 2 EoC cases,
                # - normal/graceful EoC due to the aio-side actually
                #   terminating its "streaming", but the task did not
                #   error and is not yet complete.
                #
                # - the aio-task terminated and we specially mark the
                #   closure as due to the `asyncio.Task`'s exit.
                #
                to_trio.close()
                chan._closed_by_aio_task = True

            aio_task_complete.set()
            log.runtime(
                f'`asyncio` task completed\n'
                f')>\n'
                f' |_{task}\n'
            )

    # start the asyncio task we submitted from trio
    if not inspect.isawaitable(coro):
        raise TypeError(
            f'Pass the async-fn NOT a coroutine\n'
            f'{coro!r}'
        )

    # schedule the (bg) `asyncio.Task`
    task: asyncio.Task = asyncio.create_task(
        wait_on_coro_final_result(
            to_trio,
            coro,
            aio_task_complete
        )
    )
    chan._aio_task: asyncio.Task = task

    # XXX TODO XXX get this actually workin.. XD
    # -[ ] we need logic to setup `greenback` for `asyncio`-side task
    #     REPLing.. which should normally be nearly the same as for
    #     `trio`?
    # -[ ] add to a new `.devx._greenback.maybe_init_for_asyncio()`?
    if (
        debug_mode()
        and
        (greenback := devx.debug.maybe_import_greenback(
            force_reload=True,
            raise_not_found=False,
        ))
    ):
        log.devx(
            f'Bestowing `greenback` portal for `asyncio`-task\n'
            f'{task}\n'
        )
        greenback.bestow_portal(task)

    def signal_trio_when_done(
        task: asyncio.Task,
    ) -> None:
        '''
        Maybe-cancel, relay-and-raise an error to, OR pack a final
        `return`-value for the parent (in SC terms) `trio.Task` on
        completion of the `asyncio.Task`.

        Note for certain "edge" scheduling-race-conditions we allow
        the aio side to dictate dedicated `tractor`-defined excs to
        be raised in the `trio` parent task; the intention is to
        indicate those races in a VERY pedantic manner!

        '''
        nonlocal chan
        trio_err: BaseException|None = chan._trio_err

        # XXX, since the original error we read from the asyncio.Task
        # might change between BEFORE and AFTER we here call
        # `asyncio.Task.result()`
        #
        # -> THIS is DUE TO US in `translate_aio_errors()`!
        #
        # => for example we might set a special exc
        # (`AsyncioCancelled|AsyncioTaskExited`) meant to be raised
        # in trio (and maybe absorbed depending on the called API)
        # BEFORE this done-callback is invoked by `asyncio`'s
        # runtime.
        trio_to_raise: BaseException|None = chan._trio_to_raise
        orig_aio_err: BaseException|None = chan._aio_err
        aio_err: BaseException|None = None

        # only to avoid `asyncio` complaining about uncaptured
        # task exceptions
        try:
            res: Any = task.result()
            log.info(
                f'`trio` received final result from `asyncio` task,\n'
                f')> {res}\n'
                f' |_{task}\n'
            )
            if not chan._aio_result:
                chan._aio_result = res

            # ?TODO, should we also raise `AsyncioTaskExited[res]`
            # in any case where trio is NOT blocking on the
            # `._to_trio` chan?
            #
            # -> ?NO RIGHT? since the
            #   `open_channel_from().__aexit__()` should detect this
            #   and then set any final `res` from above as a field
            #   that can optionally be read by the trio-paren-task as
            #   needed (just like in our
            #   `Context.wait_for_result()/.result` API yah?
            #
            # if provide_channels:

        except BaseException as _aio_err:
            aio_err: BaseException = _aio_err

            # READ AGAIN, AFTER the `asyncio` side errors, in case
            # it was cancelled due to an error from `trio` (or
            # some other out of band exc) and then set to something
            # else?
            curr_aio_err: BaseException|None = chan._aio_err

            # always true right?
            assert (
                type(aio_err)
                is type(orig_aio_err)
                is type(curr_aio_err)
            ), (
                f'`asyncio`-side task errors mismatch?!?\n\n'
                f'(caught) aio_err: {aio_err}\n'
                f'ORIG chan._aio_err: {orig_aio_err}\n'
                f'chan._aio_err: {curr_aio_err}\n'
            )

            msg: str = (
                '`trio`-side reports that the `asyncio`-side '
                '{etype_str}\n'
                # ^NOTE filled in below
            )
            if isinstance(aio_err, CancelledError):
                msg += (
                    f'c)>\n'
                    f' |_{task}\n'
                )
                log.cancel(
                    msg.format(etype_str='cancelled')
                )

            # XXX when the asyncio.Task exits early (before the trio
            # side) we relay through an exc-as-signal which is
            # normally suppressed unless the trio.Task also errors
            #
            # ?TODO, is this even needed (does it happen) now?
            elif (
                _py_313
                and
                isinstance(aio_err, QueueShutDown)
            ):
                # import pdbp; pdbp.set_trace()
                trio_err = AsyncioTaskExited(
                    'Task exited before `trio` side'
                )
                if not chan._trio_err:
                    chan._trio_err = trio_err

                msg += (
                    f')>\n'
                    f' |_{task}\n'
                )
                log.info(
                    msg.format(etype_str='exited')
                )

            else:
                msg += (
                    f'x)>\n'
                    f' |_{task}\n'
                )
                log.exception(
                    msg.format(etype_str='errored')
                )

        # is trio the src of the aio task's exc-as-outcome?
        trio_err: BaseException|None = chan._trio_err
        curr_aio_err: BaseException|None = chan._aio_err
        if (
            curr_aio_err
            or
            trio_err
            or
            trio_to_raise
        ):
            # XXX, if not already, ALWAYs cancel the trio-side on an
            # aio-side error or early return. In the case where the trio task is
            # blocking on a checkpoint or `asyncio.Queue.get()`.

            # NOTE: currently mem chan closure may act as a form
            # of error relay (at least in the `asyncio.CancelledError`
            # case) since we have no way to directly trigger a `trio`
            # task error without creating a nursery to throw one.
            # We might want to change this in the future though.
            from_aio.close()

            if (
                not trio_cs.cancelled_caught
                or
                not trio_cs.cancel_called
            ):
                log.cancel(
                    f'Cancelling trio-side due to aio-side src exc\n'
                    f'\n'
                    f'{curr_aio_err!r}\n'
                    f'\n'
                    f'(c>\n'
                    f'  |_{trio_task}\n'
                )
                trio_cs.cancel()

            # maybe the `trio` task errored independent from the
            # `asyncio` one and likely in between
            # a guest-run-sched-tick.
            #
            # The obvious ex. is where one side errors during
            # the current tick and then the other side immediately
            # errors before its next checkpoint; i.e. the 2 errors
            # are "independent".
            #
            # "Independent" here means in the sense that neither task
            # was the explicit cause of the other side's exception
            # according to our `tractor.to_asyncio` SC API's error
            # relaying mechanism(s); the error pair is *possibly
            # due-to* but **not necessarily** inter-related by some
            # (subsys) state between the tasks,
            #
            # NOTE, also see the `test_trio_prestarted_task_bubbles`
            # for reproducing detailed edge cases as per the above
            # cases.
            #
            trio_to_raise: AsyncioCancelled|AsyncioTaskExited = chan._trio_to_raise
            aio_to_raise: TrioTaskExited|TrioCancelled = chan._aio_to_raise
            if (
                not chan._aio_result
                and
                not trio_cs.cancelled_caught
                and (
                    (aio_err and type(aio_err) not in {
                        asyncio.CancelledError
                    })
                    or
                    aio_to_raise
                )
                and (
                    ((trio_err := chan._trio_err) and type(trio_err) not in {
                        trio.Cancelled,
                    })
                    or
                    trio_to_raise
                )
            ):
                eg = ExceptionGroup(
                    'Both the `trio` and `asyncio` tasks errored independently!!\n',
                    (
                        trio_to_raise or trio_err,
                        aio_to_raise or aio_err,
                    ),
                )
                # chan._trio_err = eg
                # chan._aio_err = eg
                raise eg

            elif aio_err:
                # XXX raise any `asyncio` side error IFF it doesn't
                # match the one we just caught from the task above!
                # (that would indicate something weird/very-wrong
                # going on?)
                if (
                    aio_err is not trio_to_raise
                    and (
                        not suppress_graceful_exits
                        and (
                            chan._aio_result is not Unresolved
                            and
                            isinstance(trio_to_raise, AsyncioTaskExited)
                        )
                    )
                ):
                    # raise aio_err from relayed_aio_err
                    raise trio_to_raise from curr_aio_err

                raise aio_err

    task.add_done_callback(signal_trio_when_done)
    return chan


def maybe_signal_aio_task(
    aio_task: asyncio.Task,
    exc: BaseException,
    *,
    cause: BaseException|None = None,
    pre_captured_fut: asyncio.Future|None = None,
    allow_cancel_fallback: bool = False,

) -> tuple[bool, str]:
    '''
    Best-effort delivery of `exc` to a still-running `aio_task`
    via its `_fut_waiter` (the `asyncio.Future` the task is
    currently `await`-ing on).

    Returns `(delivered, report)` where `delivered=True` iff
    either,
      - `fut.set_exception(exc)` was successfully called on an
        un-`done()` `_fut_waiter`, OR
      - the cancel-fallback path fired (only when the caller
        opted-in via `allow_cancel_fallback=True`).

    Why `_fut_waiter.set_exception(exc)` and NOT
    `aio_task.set_exception(exc)`:

      On py3.13+ `asyncio.Task.set_exception()` ALWAYS raises
      `RuntimeError("Task does not support set_exception
      operation")` — so calling it as a relay mechanism is dead
      code. The `_fut_waiter` is a plain `asyncio.Future` and
      its `set_exception()` works on all Python versions; the
      task's `_wakeup` callback then propagates the exc into
      the coro on its next tick.

    Why we PREFER NOT to call `aio_task.cancel()`:

      `Task.cancel()` injects a `CancelledError` that races
      any in-flight exception already queued on `_fut_waiter`
      (e.g. via a prior `set_exception()` from a sibling
      teardown path). The race can mask BOTH the original
      trio-side error and any asyncio-side error the task was
      mid-raising. See the
      `test_trio_closes_early_and_channel_exits` hang TODO
      around the `translate_aio_errors` finally for the
      historical artifact.

      However a caller may have NO OTHER way to terminate the
      task — when `_fut_waiter is None` AND the task is busy
      looping / runnable, neither `set_exception` nor a chan
      close can poke it. In that narrow case `cancel()` is the
      only available termination signal; opt-in via
      `allow_cancel_fallback=True`. The fallback NEVER runs
      when `_fut_waiter` carries an in-flight exc (the
      `fut.done()` branch); only when there's truly no
      `_fut_waiter` ref to poke.

    Pre-checkpoint capture:

      `asyncio.Task._wakeup` clears `_fut_waiter = None` as
      part of the wakeup sequence. If the caller crosses a
      trio checkpoint between fut-capture and this call,
      re-reading `aio_task._fut_waiter` will see `None` even
      though the exc is still in flight on the (now-`done()`)
      original fut. Pass `pre_captured_fut` to use the
      already-captured reference.

    Causal chaining via `cause`:

      Pass the underlying trio-side exc (the *reason* we're
      poking the aio side) via `cause` and the helper sets
      `exc.__cause__ = cause`. The chain travels with `exc`
      through `_fut_waiter.set_exception()` → `Task._wakeup`
      → coro raise → `wait_on_coro_final_result`'s except →
      `signal_trio_when_done`'s `task.result()`-`raise
      aio_err`. The final traceback then renders as
      "<trio-side exc> -> (direct cause of) -> <relay exc>"
      instead of an opaque, root-cause-detached relay.

    See the "cross-loop cause-chain matrix" comment in
    `translate_aio_errors()`'s final-raise block for how this
    `cause` interacts with every `raise X [from Y]` exit path
    (esp. the relay-echo guard which prevents a cause CYCLE).

    '''
    if cause is not None and exc.__cause__ is None:
        exc.__cause__ = cause

    if aio_task.done():
        return False, (
            f'aio-task already done; nothing to signal\n'
            f' |_{aio_task!r}\n'
        )

    fut: asyncio.Future|None = (
        pre_captured_fut
        if pre_captured_fut is not None
        else aio_task._fut_waiter
    )

    if fut and not fut.done():
        fut.set_exception(exc)
        return True, (
            f'signalled aio-task via `_fut_waiter.set_exception()`\n'
            f'exc: {exc!r}\n'
            f' |_{aio_task!r}\n'
        )

    if fut and fut.done():
        # NEVER cancel here even when `allow_cancel_fallback=True`
        # — the in-flight exc on `fut` will terminate the task
        # on its next tick; injecting `CancelledError` on top
        # would race and mask the real exc.
        return False, (
            f'`_fut_waiter` already signalled with,\n'
            f' |_{fut.exception()!r}\n'
            f'aio-task will exit on next tick via the in-flight exc;\n'
            f'SKIPPING re-signal (would race in-flight delivery).\n'
            f' |_{aio_task!r}\n'
        )

    # fut is None — task is runnable (sitting in asyncio's
    # ready queue), not parked on a future we can poke.
    if allow_cancel_fallback:
        cancel_msg: str = (
            f'\n'
            f'MANUALLY Cancelling `asyncio`-task: '
            f'{aio_task.get_name()}!\n\n'
            f'**THIS CAN SILENTLY SUPPRESS ERRORS FYI\n\n'
        )
        aio_task.cancel(msg=cancel_msg)
        return True, (
            f'aio-task has no `_fut_waiter`; FALLBACK cancel issued\n'
            f'(caller opted-in via `allow_cancel_fallback=True`).\n'
            f'{cancel_msg}'
            f' |_{aio_task!r}\n'
        )

    return False, (
        f'aio-task has no `_fut_waiter`; cannot signal without\n'
        f'`aio_task.cancel()` which can mask errors.\n'
        f'LEAVING AS-IS (caller did NOT opt-in to cancel fallback);\n'
        f'task should exit via chan close / aio-loop teardown\n'
        f'already in flight.\n'
        f' |_{aio_task!r}\n'
    )


@acm
async def translate_aio_errors(
    chan: LinkedTaskChannel,
    wait_on_aio_task: bool = False,
    cancel_aio_task_on_trio_exit: bool = True,
    suppress_graceful_exits: bool = True,

    hide_tb: bool = True,

) -> AsyncIterator[None]:
    '''
    An error handling to cross-loop propagation context around
    `asyncio.Task` spawns via one of this module's APIs:

    - `open_channel_from()`
    - `run_task()`

    appropriately translates errors and cancels into ``trio`` land.

    '''
    __tracebackhide__: bool = hide_tb

    trio_task = trio.lowlevel.current_task()
    aio_err: BaseException|None = chan._aio_err
    aio_task: asyncio.Task = chan._aio_task
    aio_done_before_trio: bool = aio_task.done()
    assert aio_task
    trio_err: BaseException|None = None
    eoc: trio.EndOfChannel|None = None
    try:
        yield  # back to one of the cross-loop apis
    except trio.Cancelled as taskc:
        trio_err = taskc
        chan._trio_err = trio_err

        # should NEVER be the case that `trio` is cancel-handling
        # BEFORE the other side's task-ref was set!?
        assert chan._aio_task

        # import pdbp; pdbp.set_trace()  # lolevel-debug

        # relay cancel through to called `asyncio` task
        chan._aio_to_raise = TrioCancelled(
            f'trio`-side cancelled the `asyncio`-side,\n'
            f'c)>\n'
            f'  |_{trio_task}\n'
            f'\n'
            f'trio src exc: {trio_err!r}\n'
        )

        # XXX NOTE XXX seems like we can get all sorts of unreliable
        # behaviour from `asyncio` under various cancellation
        # conditions (like SIGINT/kbi) when this is used..
        # SO FOR NOW, try to avoid it at most costs!
        #
        # aio_task.cancel(
        #     msg=f'the `trio` parent task was cancelled: {trio_task.name}'
        # )
        # raise

    # XXX EoC is a special SIGNAL from the aio-side here!
    # There are 2 cases to handle:
    # 1. the "EoC passthrough" case.
    #   - the aio-task actually closed the channel "gracefully" and
    #     the trio-task should unwind any ongoing channel
    #     iteration/receiving,
    #  |_this exc-translator wraps calls to `LinkedTaskChannel.receive()`
    #    in which case we want to relay the actual "end-of-chan" for
    #    iteration purposes.
    #
    # 2. relaying the "asyncio.Task termination" case.
    #   - if the aio-task terminates, maybe with an error, AND the
    #    `open_channel_from()` API was used, it will always signal
    #    that termination.
    #  |_`wait_on_coro_final_result()` always calls
    #    `to_trio.close()` when `provide_channels=True` so we need to
    #    always check if there is an aio-side exc which needs to be
    #    relayed to the parent trio side!
    #  |_in this case the special `chan._closed_by_aio_task` is
    #    ALWAYS set.
    #
    except trio.EndOfChannel as _eoc:
        eoc = _eoc
        if (
            chan._closed_by_aio_task
            and
            aio_err
        ):
            log.cancel(
                f'The asyncio-child task terminated due to error\n'
                f'{aio_err!r}\n'
            )
            chan._trio_to_raise = aio_err
            trio_err = chan._trio_err = eoc
            #
            # ?TODO?, raise something like a,
            # chan._trio_to_raise = AsyncioErrored()
            # BUT, with the tb rewritten to reflect the underlying
            # call stack?
        else:
            trio_err = chan._trio_err = eoc

        raise eoc

    # NOTE ALSO SEE the matching note in the `cancel_trio()` asyncio
    # task-done-callback.
    #
    # when the aio side is (possibly self-)cancelled it will close
    # the `chan._to_trio` and thus trigger the trio side to raise
    # a dedicated `AsyncioCancelled`
    except (
        trio.ClosedResourceError,
    ) as cre:
        chan._trio_err = cre
        aio_err = chan._aio_err

        # XXX if an underlying `asyncio.CancelledError` triggered
        # this channel close, raise our (non-`BaseException`) wrapper
        # exception (`AsyncioCancelled`) from that source error.
        if (
            # aio-side is cancelled?
            # |_ first not set until it terminates??
            aio_task.cancelled()
            and
            type(aio_err) is CancelledError

            # TODO, if we want suppression of the
            # silent-exit-by-`trio` case?
            # -[ ] the parent task can also just catch it though?
            # -[ ] OR, offer a `signal_aio_side_on_exit=True` ??
        ):
            # await tractor.pause(shield=True)
            chan._trio_to_raise = AsyncioCancelled(
                f'asyncio`-side cancelled the `trio`-side,\n'
                f'c(>\n'
                f'  |_{aio_task}\n\n'

                f'(triggered on the `trio`-side by a {cre!r})\n'
            )
            # TODO?? needed or does this just get reraised in the
            # `finally:` block below?
            # raise to_raise_trio from aio_err

        # maybe the chan-closure is due to something else?
        else:
            raise cre

    except BaseException as _trio_err:
        trio_err = chan._trio_err = _trio_err
        # await tractor.pause(shield=True)  # workx!

        # !TODO! we need an inter-loop lock here to avoid aio-tasks
        # clobbering trio ones when both crash in debug-mode!
        #
        entered: bool = await devx.debug._maybe_enter_pm(
            trio_err,
            api_frame=inspect.currentframe(),
        )
        if (
            not entered
            and
            not is_multi_cancelled(trio_err)
        ):
            log.exception(
                '`trio`-side task errored?'
            )
            # __tracebackhide__: bool = False

        # TODO, just a log msg here indicating the scope closed
        # and that the trio-side expects that and what the final
        # result from the aio side was?
        #
        # if isinstance(chan._aio_err, AsyncioTaskExited):
        #     await tractor.pause(shield=True)

        # if aio side is still active relay the trio-side error
        # to it via `_fut_waiter.set_exception()`.
        # ?TODO, mk `AsyncioCancelled[typeof(trio_err)]` embed the
        # current exc?
        aio_taskc = TrioCancelled(
            f'The `trio`-side task crashed!\n'
            f'{trio_err}'
        )
        delivered, report = maybe_signal_aio_task(
            aio_task,
            aio_taskc,
            # so the relay carries a "<trio_err> -> caused ->
            # TrioCancelled" chain when it eventually re-raises
            # on the aio side.
            cause=trio_err,
        )
        if not delivered:
            wait_on_aio_task = False
        log.cancel(report)

    finally:
        # record wtv `trio`-side error transpired
        if trio_err:
            assert chan._trio_err is trio_err
            # if chan._trio_err is not trio_err:
            #     await tractor.pause(shield=True)

        ya_trio_exited: bool = chan._trio_exited
        graceful_trio_exit: bool = (
            ya_trio_exited
            and
            not chan._trio_err   # XXX CRITICAL, `asyncio.Task.cancel()` is cucked man..
        )

        # XXX NOTE! XXX by default always cancel the `asyncio` task if
        # we've made it this far and it's not done.
        # TODO, how to detect if there's an out-of-band error that
        # caused the exit?
        if (
            not aio_task.done()
            and (
                cancel_aio_task_on_trio_exit
                # and
                # chan._aio_err  # TODO, if it's not .done() is this possible?

            # did the `.open_channel_from()` parent caller already
            # (gracefully) exit scope before this translator was
            # invoked?
            # => since we couple the lifetime of the `asyncio.Task`
            #   to the `trio` parent task, it should should also be
            #   terminated via either,
            #
            #   1. raising an explicit `TrioTaskExited|TrioCancelled`
            #      in task via `asyncio.Task._fut_waiter.set_exception()`
            #
            #   2. or (worst case) by cancelling the aio task using
            #      the std-but-never-working `asyncio.Task.cancel()`
            #      (which i can't figure out why that nor
            #      `Task.set_exception()` seem to never ever do the
            #      rignt thing! XD).
                or
                graceful_trio_exit
            )
        ):
            report: str = (
                'trio-side exited silently!'
            )
            assert not chan._aio_err, (
                'WTF why duz asyncio have err but not dun?!'
            )

            # if the `trio.Task` terminated without raising
            # `trio.Cancelled` (curently handled above) there's
            # 2 posibilities,
            #
            # i. it raised a `trio_err`
            # ii. it did a "silent exit" where the
            #    `open_channel_from().__aexit__()` phase ran without
            #    any raise or taskc (task cancel) and no final result
            #    was collected (yet) from the aio side.
            #
            # SO, ensure the asyncio-side is notified and terminated
            # by a dedicated exc-as-signal which distinguishes
            # various aio-task-state at termination cases.
            #
            # Consequently if the aio task doesn't absorb said
            # exc-as-signal, the trio side should then see the same exc
            # propagate up through the .open_channel_from() call to
            # the parent task.
            #
            # if the `trio.Task` already exited (only can happen for
            # the `open_channel_from()` use case) block due to to
            # either plain ol' graceful `__aexit__()` or due to taskc
            # or an error, we ensure the aio-side gets signalled via
            # an explicit exception and its `Queue` is shutdown.
            if ya_trio_exited:
                # XXX py3.13+ ONLY..
                # raise `QueueShutDown` on next `Queue.get/put()`
                if _py_313:
                    chan._to_aio.shutdown()

                # XXX CRITICAL ordering: capture `_fut_waiter`
                # BEFORE the checkpoint. `asyncio.Task._wakeup`
                # clears `_fut_waiter = None` as part of wakeup,
                # so re-reading after the checkpoint loses the
                # ref even though the exc is still in-flight on
                # the (now-`done()`) original fut. The helper
                # uses `pre_captured_fut` to recover that.
                pre_cp_fut: asyncio.Future|None = aio_task._fut_waiter

                # pump this event-loop (well `Runner` but ya)
                # so the aio side can error on next tick and we
                # sync task states from here onward.
                await trio.lowlevel.checkpoint()

                if graceful_trio_exit:
                    relay_exc = TrioTaskExited(
                        f'the `trio.Task` gracefully exited but '
                        f'its `asyncio` peer is not done?\n'
                        f')>\n'
                        f' |_{trio_task}\n'
                        f'\n'
                        f'>>\n'
                        f' |_{aio_task!r}\n'
                    )
                else:
                    relay_exc = TrioTaskExited(
                        f'The `trio`-side task crashed!\n'
                        f'{trio_err}'
                    )

                delivered, signal_report = maybe_signal_aio_task(
                    aio_task,
                    relay_exc,
                    pre_captured_fut=pre_cp_fut,
                    # XXX historically this branch called
                    # `aio_task.cancel()` when `_fut_waiter`
                    # was None — required to actually terminate
                    # aio tasks that aren't parked on a poke-able
                    # future (e.g. the `aio_echo_server` loop in
                    # `test_echoserver_detailed_mechanics`). Opt
                    # into the fallback so we don't regress.
                    allow_cancel_fallback=True,
                    # carry the trio-side exc (if any) as the
                    # cause so the aio-side relay shows the
                    # real root-cause chain when re-raised.
                    cause=trio_err,
                )
                report += signal_report

            log.warning(report)

        # sync with the `asyncio.Task`'s completion to ensure any
        # error is captured and relayed (via
        # `channel._aio_err/._trio_to_raise`) BEFORE calling
        # `maybe_raise_aio_side_err()` below!
        #
        # NOTE, `wait_on_aio_task` may have been flipped to `False`
        # by `maybe_signal_aio_task()` above when delivery
        # failed (e.g. `_fut_waiter is None`) — in that case we
        # skip the wait since the aio task won't process our
        # relay exc and `_aio_task_complete` may never set.
        #
        if wait_on_aio_task:
            await chan._aio_task_complete.wait()
            log.debug(
                'asyncio-task is done and unblocked trio-side!\n'
            )

        # NOTE, was a `maybe_raise_aio_side_err()` closure that
        # i moved inline BP
        '''
        Raise any `trio`-side-caused cancellation or legit task
        error normally propagated from the caller of either,
          - `open_channel_from()`
          - `run_task()`

        '''
        # ===== cross-loop cause-chain matrix =====
        # How `(trio_err, aio_err, trio_to_raise)` resolve into ONE
        # terminal `raise X [from Y]` (or an early `return`).
        #
        # legend (the possible `X` / `Y` operands):
        # - trio_err        : `chan._trio_err`, the trio-side exc.
        # - aio_err         : `chan._aio_err`, the aio-side exc.
        # - trio_to_raise   : `chan._trio_to_raise`, a tractor-chosen
        #                     relay exc (`AsyncioCancelled`/`AsyncioTaskExited`).
        # - raise_from      : `trio_err if (aio_err is trio_to_raise)
        #                      else aio_err` (the chosen `__cause__`).
        # - relay-echo      : an `aio_err` that is one of OUR OWN
        #                     `TrioTaskExited|TrioCancelled` signals,
        #                     synth'd + delivered to the aio-side by
        #                     `maybe_signal_aio_task()`; its `__cause__`
        #                     is ALREADY `trio_err`.
        # - "(bare)"        : raised with NO explicit `from` clause.
        #
        # this block (final-raise in `translate_aio_errors`):
        #   condition                            =>  raises         from
        #   -----------------------------------      -------------  -----------
        #   not suppress_graceful_exits          =>  trio_to_raise  raise_from
        #   AsyncioTaskExited + trio Cancelled/None  => return (aio-exit ignored)
        #   AsyncioTaskExited + trio EoC         =>  trio_err       (bare)
        #   AsyncioCancelled  + trio Cancelled   =>  return (co-cancel ignored)
        #   trio_to_raise match catch-all        =>  trio_to_raise  raise_from
        #   aio_err is relay-echo  ◄── the GUARD  =>  trio_err       (bare)
        #   aio_err independent (real aio fail)  =>  trio_err       aio_err
        #   aio_err independent, no trio_err     =>  aio_err        (bare)
        #   only trio_err                        =>  trio_err       (bare)
        #
        # sibling block (`signal_trio_when_done()`, the aio done-cb):
        #   AsyncioTaskExited relay-out          =>  trio_to_raise  aio_err
        #   plain aio_err re-raise               =>  aio_err  (__cause__ preset)
        #
        # INVARIANT: a relay-echo must NEVER become `trio_err.__cause__`
        #  (it's ALREADY caused-BY `trio_err`) → doing so would CYCLE
        #  (`trio_err ◄─► relay`). So the guard raises the root
        #  `trio_err` bare; the relay still keeps its own correct
        #  "relay ◄ trio_err" chain for any aio-side inspection.
        # ===== / cross-loop cause-chain matrix =====
        aio_err: BaseException|None = chan._aio_err
        trio_to_raise: (
            AsyncioCancelled|
            AsyncioTaskExited|
            Exception|  # relayed from aio-task
            None
        ) = chan._trio_to_raise

        raise_from: Exception = (
            trio_err if (aio_err is trio_to_raise)
            else aio_err
        )

        if not suppress_graceful_exits:
            raise trio_to_raise from raise_from

        if trio_to_raise:
            match (
                trio_to_raise,
                trio_err,
            ):
                case (
                    AsyncioTaskExited(),
                    trio.Cancelled()|
                    None,
                ):
                    log.info(
                        'Ignoring aio exit signal since trio also exited!'
                    )
                    return

                case (
                    AsyncioTaskExited(),
                    trio.EndOfChannel(),
                ):
                    raise trio_err

                case (
                    AsyncioCancelled(),
                    trio.Cancelled(),
                ):
                    if not aio_done_before_trio:
                        log.info(
                            'Ignoring aio cancelled signal since trio was also cancelled!'
                        )
                        return
                case _:
                    raise trio_to_raise from raise_from

        # Check if the asyncio-side is the cause of the trio-side
        # error.
        elif (
            aio_err is not None
            and
            type(aio_err) is not AsyncioCancelled
        ):
            # XXX, if `aio_err` is one of OUR OWN relay-signals
            # (`TrioTaskExited`/`TrioCancelled`) that we delivered
            # to the aio-side via `maybe_signal_aio_task()`, AND
            # its `__cause__` already points back at `trio_err`,
            # then it's just a derivative ECHO of the trio-side
            # error, NOT an independent asyncio failure.
            #
            # Raising `trio_err from aio_err` here would invert
            # (and cyclically tangle) the cause chain since the
            # relay was itself caused-by `trio_err`:
            #
            #   trio_err.__cause__ = aio_err   (from `raise .. from`)
            #   aio_err.__cause__  = trio_err  (set in `maybe_signal_aio_task`)
            #
            # So raise the REAL root `trio_err` alone; the relay's
            # own `__cause__` chain still correctly reads
            # "TrioTaskExited <- trio_err" for aio-side inspection.
            if (
                trio_err is not None
                and
                isinstance(aio_err, (TrioTaskExited, TrioCancelled))
                and
                aio_err.__cause__ is trio_err
            ):
                raise trio_err

            # always raise from any captured asyncio error
            if trio_err:
                raise trio_err from aio_err

            # XXX NOTE! above in the `trio.ClosedResourceError`
            # handler we specifically set the
            # `aio_err = AsyncioCancelled` such that it is raised
            # as that special exc here!
            raise aio_err

        if trio_err:
            raise trio_err

        # ^^TODO?? case where trio_err is not None and
        # aio_err is AsyncioTaskExited => raise eg!
        # -[x] maybe use a match bc this get's real
        #     complex fast XD
        #  => i did this above for silent exit cases ya?


async def run_task(
    func: Callable,
    *,

    qsize: int = 2**10,
    **kwargs,

) -> Any:
    '''
    Run an `asyncio`-compat async function or generator in a task,
    return or stream the result back to `trio`.

    '''
    # simple async func
    chan: LinkedTaskChannel = _run_asyncio_task(
        func,
        qsize=1,
        **kwargs,
    )
    with chan._from_aio:
        async with translate_aio_errors(
            chan,
            wait_on_aio_task=True,
            suppress_graceful_exits=chan._suppress_graceful_exits,
        ):
            # return single value that is the output from the
            # ``asyncio`` function-as-task. Expect the mem chan api
            # to do the job of handling cross-framework cancellations
            # / errors via closure and translation in the
            # `translate_aio_errors()` in the above ctx mngr.

            return await chan._from_aio.receive()
            # return await chan.receive()


@acm
async def open_channel_from(
    target: Callable[..., Any],
    suppress_graceful_exits: bool = True,
    **target_kwargs,

) -> AsyncIterator[
    tuple[LinkedTaskChannel, Any]
]:
    '''
    Start an `asyncio.Task` as `target()` and open an
    inter-loop (linked) channel for streaming between
    it and the current `trio.Task`.

    A pair `(chan: LinkedTaskChannel, Any)` is delivered
    to the caller where the 2nd element is the value
    provided by the `asyncio.Task`'s unblocking call
    to `chan.started_nowait()`.

    '''
    chan: LinkedTaskChannel = _run_asyncio_task(
        target,
        qsize=2**8,
        provide_channels=True,
        suppress_graceful_exits=suppress_graceful_exits,
        **target_kwargs,
    )
    # TODO, tuple form here?
    async with chan._from_aio:
        async with translate_aio_errors(
            chan,
            wait_on_aio_task=True,
            suppress_graceful_exits=suppress_graceful_exits,
        ):
            # sync to a "started()"-like first delivered value from the
            # ``asyncio`` task.
            try:
                with (cs := chan._trio_cs):
                    first = await chan.receive()

                    # deliver stream handle upward
                    yield chan, first
            except trio.Cancelled as taskc:
                if cs.cancel_called:
                    if isinstance(chan._trio_to_raise, AsyncioCancelled):
                        log.cancel(
                            f'trio-side was manually cancelled by aio side\n'
                            f'|_c>}}{cs!r}?\n'
                        )
                    # TODO, maybe a special `TrioCancelled`???

                raise taskc

            finally:
                chan._trio_exited = True

                # when the aio side is still ongoing but trio exits
                # early we signal with a special exc (kinda like
                # a `Return`-msg for IPC ctxs)
                aio_task: asyncio.Task = chan._aio_task
                if not aio_task.done():
                    # capture the in-flight trio-side exc (if any)
                    # so the relay's `__cause__` chain shows the
                    # real root cause when the aio task re-raises.
                    # `sys.exc_info()[1]` is non-`None` only when
                    # the `try` body raised (graceful exit -> None).
                    trio_exc: BaseException|None = sys.exc_info()[1]
                    _, report = maybe_signal_aio_task(
                        aio_task,
                        TrioTaskExited(
                            f'but the child `asyncio` task is still running?\n'
                            f'>>\n'
                            f' |_{aio_task!r}\n'
                        ),
                        cause=trio_exc,
                    )
                    log.cancel(report)
                else:
                    chan._to_trio.close()


class AsyncioRuntimeTranslationError(RuntimeError):
    '''
    We failed to correctly relay runtime semantics and/or maintain SC
    supervision rules cross-event-loop.

    '''


def run_trio_task_in_future(
    async_fn,
    *args,
) -> asyncio.Future:
    '''
    Run an async-func as a `trio` task from an `asyncio.Task` wrapped
    in a `asyncio.Future` which is returned to the caller.

    Another astounding feat by the great @oremanj !!

    Bo

    '''
    result_future = asyncio.Future()
    cancel_scope = trio.CancelScope()
    finished: bool = False

    # monkey-patch the future's `.cancel()` meth to
    # allow cancellation relay to `trio`-task.
    cancel_message: str|None = None
    orig_cancel = result_future.cancel

    def wrapped_cancel(
        msg: str|None = None,
    ):
        nonlocal cancel_message
        if finished:
            # We're being called back after the task completed
            if msg is not None:
                return orig_cancel(msg)
            elif cancel_message is not None:
                return orig_cancel(cancel_message)
            else:
                return orig_cancel()

        if result_future.done():
            return False

        # Forward cancellation to the Trio task, don't mark
        # future as cancelled until it completes
        cancel_message = msg
        cancel_scope.cancel()
        return True

    result_future.cancel = wrapped_cancel

    async def trio_task() -> None:
        nonlocal finished
        try:
            with cancel_scope:
                try:
                    # TODO: type this with new tech in 3.13
                    result: Any = await async_fn(*args)
                finally:
                    finished = True

            # Propagate result or cancellation to the Future
            if cancel_scope.cancelled_caught:
                result_future.cancel()

            elif not result_future.cancelled():
                result_future.set_result(result)

        except BaseException as exc:
            # the result future gets all the non-Cancelled
            # exceptions. Any Cancelled need to keep propagating
            # out of this stack frame in order to reach the cancel
            # scope for which they're intended.
            cancelled: BaseException|None
            rest: BaseException|None
            if isinstance(exc, BaseExceptionGroup):
                cancelled, rest = exc.split(trio.Cancelled)

            elif isinstance(exc, trio.Cancelled):
                cancelled, rest = exc, None

            else:
                cancelled, rest = None, exc

            if not result_future.cancelled():
                if rest:
                    result_future.set_exception(rest)
                else:
                    result_future.cancel()

            if cancelled:
                raise cancelled

    trio.lowlevel.spawn_system_task(
        trio_task,
        name=async_fn,
    )
    return result_future


def run_as_asyncio_guest(
    trio_main: Callable,
    # ^-NOTE-^ when spawned with `infected_aio=True` this func is
    # normally `Actor._async_main()` as is passed by some boostrap
    # entrypoint like `._entry._trio_main()`.

    _sigint_loop_pump_delay: float = 0,

) -> None:
    # ^-TODO-^ technically whatever `trio_main` returns.. we should
    # try to use func-typevar-params at leaast by 3.13!
    # -[ ] https://typing.readthedocs.io/en/latest/spec/callables.html#callback-protocols
    # -[ ] https://peps.python.org/pep-0646/#using-type-variable-tuples-in-functions
    # -[ ] https://typing.readthedocs.io/en/latest/spec/callables.html#unpack-for-keyword-arguments
    # -[ ] https://peps.python.org/pep-0718/
    '''
    Entry for an "infected ``asyncio`` actor".

    Entrypoint for a Python process which starts the ``asyncio`` event
    loop and runs ``trio`` in guest mode resulting in a system where
    ``trio`` tasks can control ``asyncio`` tasks whilst maintaining
    SC semantics.

    '''
    # Uh, oh.
    #
    # :o
    #
    # looks like your stdlib event loop has caught a case of "the trios" !
    #
    # :O
    #
    # Don't worry, we've heard you'll barely notice.
    #
    # :)
    #
    # You might hallucinate a few more propagating errors and feel
    # like your digestion has slowed, but if anything get's too bad
    # your parents will know about it.
    #
    # B)
    #
    async def aio_main(trio_main):
        '''
        Main `asyncio.Task` which calls
        `trio.lowlevel.start_guest_run()` to "infect" the `asyncio`
        event-loop by embedding the `trio` scheduler allowing us to
        boot the `tractor` runtime and connect back to our parent.

        '''
        loop = asyncio.get_running_loop()
        trio_done_fute = asyncio.Future()
        startup_msg: str = (
            'Starting `asyncio` guest-loop-run\n'
            '-> got running loop\n'
            '-> built a `trio`-done future\n'
        )

        # TODO: is this evern run or needed?
        # -[ ] pretty sure it never gets run for root-infected-aio
        #     since this main task is always the parent of any
        #     eventual `open_root_actor()` call?
        if debug_mode():
            log.error(
                'Attempting to enter non-required `greenback` init '
                'from `asyncio` task ???'
            )
            # XXX make it obvi we know this isn't supported yet!
            assert 0
            # await debug.maybe_init_greenback(
            #     force_reload=True,
            # )

        def trio_done_callback(main_outcome: Outcome):
            log.runtime(
                f'`trio` guest-run finishing with outcome\n'
                f'>) {main_outcome}\n'
                f'|_{trio_done_fute}\n'
            )

            # import pdbp; pdbp.set_trace()
            if isinstance(main_outcome, Error):
                error: BaseException = main_outcome.error

                # show an dedicated `asyncio`-side tb from the error
                tb_str: str = ''.join(traceback.format_exception(error))
                log.exception(
                    'Guest-run errored!?\n\n'
                    f'{main_outcome}\n'
                    f'{error}\n\n'
                    f'{tb_str}\n'
                )
                trio_done_fute.set_exception(error)

                # raise inline
                main_outcome.unwrap()

            else:
                trio_done_fute.set_result(main_outcome)

            log.info(
                f'`trio` guest-run finished with,\n'
                f')>\n'
                f'|_{trio_done_fute}\n'
            )

        startup_msg += (
            f'-> created {trio_done_callback!r}\n'
            f'-> scheduling `trio_main`: {trio_main!r}\n'
        )

        # start the infection: run trio on the asyncio loop in "guest mode"
        log.runtime(
            f'{startup_msg}\n\n'
            +
            'Infecting `asyncio`-process with a `trio` guest-run!\n'
        )

        # TODO, somehow bootstrap this!
        _runtime_vars['_is_infected_aio'] = True

        trio.lowlevel.start_guest_run(
            trio_main,
            run_sync_soon_threadsafe=loop.call_soon_threadsafe,
            done_callback=trio_done_callback,
        )
        fute_err: BaseException|None = None
        try:
            out: Outcome = await asyncio.shield(trio_done_fute)
            # out: Outcome = await trio_done_fute
            # ^TODO still don't really understand why the `.shield()`
            # is required ... ??
            # https://docs.python.org/3/library/asyncio-task.html#asyncio.shield
            # ^ seems as though in combo with the try/except here
            # we're BOLDLY INGORING cancel of the trio fute?
            #
            # I guess it makes sense bc we don't want `asyncio` to
            # cancel trio just because they can't handle SIGINT
            # sanely? XD .. kk

            # XXX, sin-shield causes guest-run abandons on SIGINT..
            # out: Outcome = await trio_done_fute

            # NOTE will raise (via `Error.unwrap()`) from any
            # exception packed into the guest-run's `main_outcome`.
            return out.unwrap()

        except (
            # XXX special SIGINT-handling is required since
            # `asyncio.shield()`-ing seems to NOT handle that case as
            # per recent changes in 3.11:
            # https://docs.python.org/3/library/asyncio-runner.html#handling-keyboard-interruption
            #
            # NOTE: further, apparently ONLY need to handle this
            # special SIGINT case since all other `asyncio`-side
            # errors can be processed via our `chan._aio_err`
            # relaying (right?); SIGINT seems to be totally diff
            # error path in `asyncio`'s runtime..?
            asyncio.CancelledError,

        ) as _fute_err:
            fute_err = _fute_err
            err_message: str = (
                'main `asyncio` task '
                'was cancelled!\n'
            )

            # TODO, handle possible edge cases with
            # `open_root_actor()` closing before this is run!
            #
            actor: tractor.Actor = tractor.current_actor()

            log.exception(
                err_message
                +
                'Cancelling `trio`-side `tractor`-runtime..\n'
                f'c(>\n'
                f'  |_{actor}.cancel_soon()\n'
            )

            # XXX WARNING XXX the next LOCs are super important!
            #
            # SINCE without them, we can get guest-run ABANDONMENT
            # cases where `asyncio` will not schedule or wait on the
            # guest-run `trio.Task` nor invoke its registered
            # `trio_done_callback()` before final shutdown!
            #
            # This is particularly true if the `trio` side has tasks
            # in shielded sections when an OC-cancel (SIGINT)
            # condition occurs!
            #
            # We now have the
            # `test_infected_asyncio.test_sigint_closes_lifetime_stack()`
            # suite to ensure we do not suffer this issues
            # (hopefully) ever again.
            #
            # The original abandonment issue surfaced as 2 different
            # race-condition dependent types scenarios all to do with
            # `asyncio` handling SIGINT from the system:
            #
            # - "silent-abandon" (WORST CASE):
            #  `asyncio` abandons the `trio` guest-run task silently
            #  and no `trio`-guest-run or `tractor`-actor-runtime
            #  teardown happens whatsoever..
            #
            # - "loud-abandon" (BEST-ish CASE):
            #   the guest run get's abaondoned "loudly" with `trio`
            #   reporting a console traceback and further tbs of all
            #   the (failed) GC-triggered shutdown routines which
            #   thankfully does get dumped to console..
            #
            # The abandonment is most easily reproduced if the `trio`
            # side has tasks doing shielded work where those tasks
            # ignore the normal `Cancelled` condition and continue to
            # run, but obviously `asyncio` isn't aware of this and at
            # some point bails on the guest-run unless we take manual
            # intervention..
            #
            # To repeat, *WITHOUT THIS* stuff below the guest-run can
            # get race-conditionally abandoned!!
            #
            # XXX SOLUTION XXX
            # ------ - ------
            # XXX FIRST PART:
            # ------ - ------
            # the obvious fix to the "silent-abandon" case is to
            # explicitly cancel the actor runtime such that no
            # runtime tasks are even left unaware that the guest-run
            # should be terminated due to OS cancellation.
            #
            actor.cancel_soon()

            # ------ - ------
            # XXX SECOND PART:
            # ------ - ------
            # Pump the `asyncio` event-loop to allow
            # `trio`-side to `trio`-guest-run to complete and
            # teardown !!
            #
            # oh `asyncio`, how i don't miss you at all XD
            while not trio_done_fute.done():
                log.runtime(
                    'Waiting on main guest-run `asyncio` task to complete..\n'
                    f'|_trio_done_fut: {trio_done_fute}\n'
                )
                await asyncio.sleep(_sigint_loop_pump_delay)

                # XXX is there any alt API/approach like the internal
                # call below but that doesn't block indefinitely..?
                # loop._run_once()

            try:
                return trio_done_fute.result()
            except (
                asyncio.InvalidStateError,
                # asyncio.CancelledError,
                # ^^XXX `.shield()` call above prevents this??

            )as state_err:

                # XXX be super dupere noisy about abandonment issues!
                aio_task: asyncio.Task = asyncio.current_task()
                message: str = (
                    'The `asyncio`-side task likely exited before the '
                    '`trio`-side guest-run completed!\n\n'
                )
                if fute_err:
                    message += (
                        f'The main {aio_task}\n'
                        f'STOPPED due to {type(fute_err)}\n\n'
                    )

                message += (
                    f'Likely something inside our guest-run-as-task impl is '
                    f'not effectively waiting on the `trio`-side to complete ?!\n'
                    f'This code -> {aio_main!r}\n\n'

                    'Below you will likely see a '
                    '"RuntimeWarning: Trio guest run got abandoned.." !!\n'
                )
                raise AsyncioRuntimeTranslationError(message) from state_err

        # XXX, should never get here ;)
        # else:
        #     import pdbp; pdbp.set_trace()

    # might as well if it's installed.
    try:
        import uvloop
        loop = uvloop.new_event_loop()
        asyncio.set_event_loop(loop)
    except ImportError:
        log.runtime('`uvloop` not available..')

    return asyncio.run(
        aio_main(trio_main),
    )