103 lines
3.2 KiB
ReStructuredText
103 lines
3.2 KiB
ReStructuredText
|
Errors and cancellation types
|
||
|
|
=============================
|
||
|
|
|
||
|
|
``tractor`` extends trio's "exceptions `always propagate`_" rule
|
||
|
|
across the process boundary: a crash in any actor is serialized as
|
||
|
|
an ``Error`` msg, shuttled over IPC, and re-raised in the linked
|
||
|
|
parent scope as a *boxed* :class:`RemoteActorError` — preserving
|
||
|
|
the original type, traceback text and source-actor identity, even
|
||
|
|
across multi-hop relays (a.k.a. "inceptions").
|
||
|
|
|
||
|
|
The most-used types below are importable from ``tractor``
|
||
|
|
directly; the remainder live in ``tractor._exceptions`` (not yet
|
||
|
|
re-exported at top level).
|
||
|
|
|
||
|
|
.. currentmodule:: tractor
|
||
|
|
|
||
|
|
Boxed remote errors
|
||
|
|
-------------------
|
||
|
|
|
||
|
|
.. autoexception:: RemoteActorError
|
||
|
|
:members: boxed_type,
|
||
|
|
src_uid,
|
||
|
|
relay_uid,
|
||
|
|
pformat
|
||
|
|
|
||
|
|
.. code:: python
|
||
|
|
|
||
|
|
try:
|
||
|
|
async with portal.open_context(ep_fn) as (ctx, first):
|
||
|
|
...
|
||
|
|
except tractor.RemoteActorError as rae:
|
||
|
|
if rae.boxed_type is ValueError:
|
||
|
|
... # remote task raised a `ValueError`
|
||
|
|
|
||
|
|
.. autoexception:: ContextCancelled
|
||
|
|
:show-inheritance:
|
||
|
|
:members: canceller
|
||
|
|
|
||
|
|
.. note::
|
||
|
|
|
||
|
|
Inspect :attr:`ContextCancelled.canceller` (the requesting
|
||
|
|
actor's uid) to distinguish a *self*-requested cancel (absorbed
|
||
|
|
at ``open_context()`` exit) from a *cross*-actor cancel (raised
|
||
|
|
locally) — the full rules live in :doc:`/api/context`.
|
||
|
|
|
||
|
|
Typed-messaging errors
|
||
|
|
----------------------
|
||
|
|
|
||
|
|
.. autoexception:: MsgTypeError
|
||
|
|
:show-inheritance:
|
||
|
|
:members: bad_msg,
|
||
|
|
expected_msg_type
|
||
|
|
|
||
|
|
An "IPC ``TypeError``": a message failed validation against the
|
||
|
|
active msg-spec / ``pld_spec`` (see :doc:`/api/msg`). Raised
|
||
|
|
sender-side for control msgs (``Started``/``Return``) and
|
||
|
|
receiver-side for stream ``Yield`` payloads.
|
||
|
|
|
||
|
|
.. autoexception:: tractor._exceptions.StreamOverrun
|
||
|
|
:show-inheritance:
|
||
|
|
|
||
|
|
The sender out-paced the receiver's buffer on a
|
||
|
|
:class:`~tractor.MsgStream` opened without
|
||
|
|
``allow_overruns=True``; subtypes :class:`trio.TooSlowError`.
|
||
|
|
|
||
|
|
Transport and runtime errors
|
||
|
|
----------------------------
|
||
|
|
|
||
|
|
.. autoexception:: TransportClosed
|
||
|
|
|
||
|
|
.. autoexception:: ModuleNotExposed
|
||
|
|
:show-inheritance:
|
||
|
|
|
||
|
|
Raised when an RPC requests a function from a module not listed
|
||
|
|
in the target actor's ``enable_modules`` allowlist —
|
||
|
|
capability-style access control, not an import bug on your end ;)
|
||
|
|
|
||
|
|
.. autoexception:: tractor._exceptions.NoRuntime
|
||
|
|
:show-inheritance:
|
||
|
|
|
||
|
|
Raised by :func:`tractor.current_actor` (and friends) when no
|
||
|
|
actor runtime is up in the current process.
|
||
|
|
|
||
|
|
.. autoexception:: tractor._exceptions.ActorTooSlowError
|
||
|
|
:show-inheritance:
|
||
|
|
|
||
|
|
A peer actor failed to ack a cancel request within the bounded
|
||
|
|
wait — the SC-sanctioned escalation signal from APIs like
|
||
|
|
``Portal.cancel_actor(raise_on_timeout=True)``. Catch it to
|
||
|
|
escalate (e.g. hard-kill via the supervising
|
||
|
|
:class:`~tractor.ActorNursery`); never just ignore it, that's how
|
||
|
|
zombies happen.
|
||
|
|
|
||
|
|
.. seealso::
|
||
|
|
|
||
|
|
:doc:`/api/context` for how cancellation and errors flow
|
||
|
|
through a :class:`~tractor.Context`, :doc:`/api/devx` for
|
||
|
|
crash-handling REPL tooling (``debug_mode``, post-mortems),
|
||
|
|
and :doc:`/guide/cancellation` for the full SC-cancellation
|
||
|
|
story.
|
||
|
|
|
||
|
|
.. _always propagate: https://trio.readthedocs.io/en/latest/design.html#exceptions-always-propagate
|