acktor_ipc/lib.rs
1//! # acktor-ipc
2//!
3//! Interprocess communication for the [`acktor`](https://github.com/asymmetry/acktor) actor
4//! framework.
5//!
6//! # About
7//!
8//! `acktor-ipc` lets actors in different processes talk to each other over a transport of your
9//! choice. It introduces a [`Node`] actor that owns one or more listeners and per-connection
10//! [`Session`] actors that mediate traffic.
11//!
12//! # Concepts
13//!
14//! - **Node** — a long-lived actor that holds the listener(s) for inbound connections, tracks the
15//! active sessions, and owns the registry of remote-addressable / remote-spawnable actor types.
16//! Send `Connect<C>` to it to dial out.
17//! - **Session** — a per-connection actor that wraps a single [`IpcConnection`], routes inbound
18//! frames to the right local actor, forwards outbound messages, and correlates request/response
19//! tags.
20//! - **RemoteAddressable** *(re-exported from `acktor`)* — derive on an actor (with
21//! `#[message(M1, M2, ...)]`) to declare the message types it can receive from other processes.
22//! Messages must implement `MessageId`, [`Encode`], and [`Decode`]; their `Result`s must
23//! implement [`Encode`] + [`Decode`].
24//! - **RemoteSpawnable** *(re-exported from `acktor`)* — implement to allow other processes to
25//! spawn this actor on this node.
26//! - **`#[remote]`** — attribute applied to the `impl Actor for ...` block of a remote-addressable
27//! actor; required so the actor exposes a remote mailbox.
28//!
29//! # Example
30//!
31//! A minimal message definition for IPC looks like:
32//!
33//! ```ignore
34//! use acktor::{Message, MessageId};
35//! use acktor_ipc::{Decode, Encode};
36//! use zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
37//!
38//! #[derive(
39//! Debug, Clone, Copy,
40//! KnownLayout, Immutable, FromBytes, IntoBytes,
41//! Message, MessageId, Encode, Decode,
42//! )]
43//! #[codec(zerocopy)]
44//! #[result_type(())]
45//! #[repr(C)]
46//! pub struct Ping {
47//! pub id: u64,
48//! pub timestamp: i64,
49//! }
50//! ```
51//!
52//! See the `pingpong` example in the repository for a complete client/server walkthrough using
53//! the WebSocket transport.
54//!
55//! # Feature Flags
56//!
57//! Defaults: `derive`.
58//!
59//! | Feature | Purpose |
60//! | ----------- | ---------------------------------------------- |
61//! | `derive` | Re-exports the `#[remote]` attribute macro. |
62//! | `pipe` | Pipe transport (Unix sockets / Windows pipes). |
63//! | `websocket` | WebSocket transport. |
64//!
65//! Neither transport is enabled by default — enable `pipe` and/or `websocket` to pick the
66//! transports you want.
67
68#![cfg_attr(docsrs, feature(doc_cfg))]
69#![allow(clippy::uninlined_format_args)]
70
71pub mod error;
72pub use error::{NodeError, SessionError};
73
74pub mod ipc_method;
75pub use ipc_method::{IpcConnection, IpcListener};
76
77pub(crate) mod remote;
78pub use remote::{RemoteAddressable, RemoteSpawnable, StableId};
79
80mod actor_ref;
81pub use actor_ref::ActorRef;
82
83pub mod node;
84pub use node::{Node, NodeEvent};
85
86pub mod session;
87pub use session::Session;
88
89pub use acktor::codec;
90pub use acktor::codec::{Decode, DecodeContext, DecodeError, Encode, EncodeContext, EncodeError};
91
92#[cfg(feature = "derive")]
93#[cfg_attr(docsrs, doc(cfg(feature = "derive")))]
94pub use acktor_derive::remote;
95
96pub mod double_map;
97
98#[cfg(test)]
99mod test_utils;