90 lines
2.7 KiB
ReStructuredText
90 lines
2.7 KiB
ReStructuredText
|
IPC and logging
|
||
|
|
===============
|
||
|
|
|
||
|
|
Under every portal, context and stream sits a per-peer
|
||
|
|
:class:`~tractor.Channel`: a msgpack-typed messaging link wrapping
|
||
|
|
one OS transport connection. Transports are pluggable per actor
|
||
|
|
via ``enable_transports=['tcp' | 'uds']`` — TCP is the default,
|
||
|
|
UDS (unix domain sockets) gives you port-less, same-host IPC with
|
||
|
|
kernel-provided peer credentials for free — and exactly **one**
|
||
|
|
transport may currently be enabled per actor.
|
||
|
|
|
||
|
|
.. d2:: diagrams/runtime_stack.d2
|
||
|
|
:caption: Where ``Channel`` sits in the runtime stack.
|
||
|
|
:margin:
|
||
|
|
:alt: layered runtime stack from app code down to transports
|
||
|
|
|
||
|
|
Addresses are "unwrapped" tuples at the API edges:
|
||
|
|
``('host', port)`` for TCP, filesystem-path pairs for UDS. For
|
||
|
|
the full layering story — transport protocols, the IPC server,
|
||
|
|
address types and the msg loop — see
|
||
|
|
:doc:`/explain/architecture`.
|
||
|
|
|
||
|
|
.. currentmodule:: tractor
|
||
|
|
|
||
|
|
``Channel``
|
||
|
|
-----------
|
||
|
|
|
||
|
|
.. autoclass:: Channel
|
||
|
|
:members: from_addr,
|
||
|
|
send,
|
||
|
|
recv,
|
||
|
|
aclose,
|
||
|
|
connected,
|
||
|
|
apply_codec,
|
||
|
|
aid,
|
||
|
|
laddr,
|
||
|
|
raddr,
|
||
|
|
closed
|
||
|
|
|
||
|
|
.. deprecated:: 0.1.0a6
|
||
|
|
|
||
|
|
``Channel.uid`` warns; use :attr:`Channel.aid` which carries
|
||
|
|
richer (optional) identity fields beyond the legacy
|
||
|
|
``(name, uuid)`` pair.
|
||
|
|
|
||
|
|
.. note::
|
||
|
|
|
||
|
|
You rarely construct a :class:`Channel` yourself — the runtime
|
||
|
|
hands them out via :attr:`Portal.chan <tractor.Portal.chan>`
|
||
|
|
and :attr:`Context.chan <tractor.Context.chan>`. Treat the
|
||
|
|
send/recv surface as advanced API: normal apps should speak
|
||
|
|
:class:`~tractor.MsgStream` instead.
|
||
|
|
|
||
|
|
Choosing a transport
|
||
|
|
--------------------
|
||
|
|
|
||
|
|
.. literalinclude:: ../../examples/uds_transport_actor_tree.py
|
||
|
|
:caption: examples/uds_transport_actor_tree.py
|
||
|
|
:language: python
|
||
|
|
|
||
|
|
Logging
|
||
|
|
-------
|
||
|
|
|
||
|
|
``tractor.log`` provides the structured, colorized console
|
||
|
|
logging used across the runtime — with actor-name + task-aware
|
||
|
|
record headers and extra log levels below :data:`logging.DEBUG`
|
||
|
|
(``'transport'``, ``'runtime'``, ``'cancel'``, ``'devx'``) for
|
||
|
|
spelunking the runtime itself. Use it for your app too: it's
|
||
|
|
already distributed-system aware.
|
||
|
|
|
||
|
|
.. currentmodule:: tractor.log
|
||
|
|
|
||
|
|
.. autofunction:: get_logger
|
||
|
|
|
||
|
|
.. autofunction:: get_console_log
|
||
|
|
|
||
|
|
.. note::
|
||
|
|
|
||
|
|
The ``TRACTOR_LOGLEVEL`` env var overrides any caller-passed
|
||
|
|
``loglevel`` (e.g. to ``open_root_actor()``) so you can crank
|
||
|
|
console verbosity without touching code; subactors inherit
|
||
|
|
the root's level by default.
|
||
|
|
|
||
|
|
.. seealso::
|
||
|
|
|
||
|
|
:doc:`/explain/architecture` for the transport/server
|
||
|
|
internals, :doc:`/api/discovery` for how channel addresses
|
||
|
|
get registered and found, and :doc:`/api/msg` for the codec
|
||
|
|
layer every channel speaks.
|