Module mailbox

Mailboxes are the central message-passing mechanism in Hyperactor.

Each actor owns a mailbox to which other actors can deliver messages. An actor can open one or more typed ports in the mailbox; messages are in turn delivered to specific ports.

Mailboxes are associated with an ActorId (given by actor_id in the following example):

let mbox = Mailbox::new_detached(actor_id);
let (port, mut receiver) = mbox.open_port::<u64>();

port.send(123).unwrap();
assert_eq!(receiver.recv().await.unwrap(), 123u64);

Mailboxes also provide a form of one-shot ports, called [OncePort], that permits at most one message transmission:

let mbox = Mailbox::new_detached(actor_id);

let (port, receiver) = mbox.open_once_port::<u64>();

port.send(123u64).unwrap();
assert_eq!(receiver.recv().await.unwrap(), 123u64);

[OncePort]s are correspondingly used for RPC replies in the actor system.

Remote ports and serialization

Mailboxes allow delivery of serialized messages to named ports:

1. Ports restrict message types to (serializable) Messages.
2. Each [Port] is associated with a PortId which globally names the port.
3. Mailbox provides interfaces to deliver serialized messages to ports named by their PortId.

While this complicates the interface somewhat, it allows the implementation to avoid a serialization roundtrip when passing messages locally.

Re-exports

pub use mailbox_admin_message::MailboxAdminMessage;

pub use mailbox_admin_message::MailboxAdminMessageHandler;

pub use durable_mailbox_sender::log;

Modules

durable_mailbox_sender

For [DurableMailboxSender] a sender with a write-ahead log.

mailbox_admin_message

For MailboxAdminMessage, a message type for mailbox administration.

Structs

BoxedMailboxSender

Convenience boxing implementation for MailboxSender. Most APIs are parameterized on MailboxSender implementations, and it’s thus difficult to work with dyn values. BoxedMailboxSender bridges this gap by providing a concrete MailboxSender which dispatches using an underlying (boxed) dyn.

DialMailboxRouter

A dynamic mailbox router that supports remote delivery.

Mailbox

A mailbox coordinates message delivery to actors through typed [Port]s associated with the mailbox.

MailboxClient

A mailbox server client that transmits messages on a Tx channel.

MailboxError

Errors that occur during mailbox operations. Each error is associated with the mailbox’s actor id.

MailboxMuxer

An in-memory mailbox muxer. This is used to route messages to different underlying senders.

MailboxRouter

MailboxRouter routes messages to the sender that is bound to its nearest prefix.

MailboxSenderError

Errors that that occur during mailbox sending operations. Each error is associated with the port ID of the operation.

MailboxServerHandle

Represents a running MailboxServer. The handle composes a [‘tokio::task::JoinHandle’] and may be joined in the same manner.

MessageEnvelope

An envelope that carries a message destined to a remote actor. The envelope contains a serialized message along with its destination and sender.

MessageMetadata

Metadata about a message sent via a MessageEnvelope.

OncePortHandle

A one-shot port handle to which M-typed messages can be delivered.

OncePortReceiver

A receiver of M-typed messages from [OncePort]s.

PanickingMailboxSender

A perpetually closed mailbox sender. Panics if any messages are posted. Useful for tests, or where there is no meaningful mailbox sender implementation available.

PortHandle

A port to which M-typed messages can be delivered. Ports may be serialized to be sent to other actors. However, when a port is deserialized, it may no longer be used to send messages directly to a mailbox since it is no longer associated with a local mailbox ([Mailbox::send] will fail). However, the runtime may accept remote Ports, and arrange for these messages to be delivered indirectly through inter-node message passing.

PortReceiver

A receiver of M-typed messages, used by actors to receive messages on open ports.

PortSink

Wrapper to turn PortRef into a Sink.

SerializedSenderError

Error that that occur during SerializedSender’s send operation.

Undeliverable

For Undeliverable, a message type for delivery failures. An undeliverable M-typed message (in practice M is MessageEnvelope).

UndeliverableMailboxSender

A mailbox sender for undeliverable messages. This will simply record any undelivered messages.

UnroutableMailboxSender

A MailboxSender that reports any envelope as undeliverable due to routing failure.

WeakMailboxRouter

A version of MailboxRouter that holds a weak reference to the underlying state. This allows router references to be circular: an entity holding a reference to the router may also contain the router itself.

Enums

DeliveryError

Delivery errors occur during message posting.

MailboxErrorKind

The kinds of mailbox errors. This enum is marked non-exhaustive to allow for extensibility.

MailboxSenderErrorKind

The kind of mailbox sending errors.

MailboxServerError

Errors that occur during mailbox serving.

PortLocation

PortLocation describes the location of a port. This is used in errors to provide a uniform data type for ports that may or may not be bound.

UndeliverableMessageError

Errors that occur during message delivery and return.

Traits

BoxableMailboxSender

Extension trait that creates a boxed clone of a MailboxSender.

IntoBoxedMailboxSender

Extension trait that rehomes a MailboxSender into a BoxedMailboxSender.

MailboxSender

MailboxSenders can send messages through ports to mailboxes. It provides a unified interface for message delivery in the system.

MailboxServer

Serve a port on the provided channel::Rx. This dispatches all channel messages directly to the port.

Message

Message collects the necessary requirements for messages that are deposited into mailboxes.

PortSender

PortSender extends MailboxSender by providing typed endpoints for sending messages over ports.

RemoteMessage

RemoteMessage extends Message by requiring that the messages also be serializable, and can thus traverse process boundaries. RemoteMessages must also specify a globally unique type name (a URI).

Functions

custom_monitored_return_handle

Now that monitored return handles are rare, it’s becoming helpful to get insights into where they are getting used (so that they can be eliminated and replaced with something better).

monitored_return_handle

Accessor to the shared monitored undeliverable message port handle. Initialization spawns the undeliverable message port monitor that forwards incoming messages to the undeliverable mailbox sender.

open_once_port

Open a one-shot port given a capability. This is a public method primarily to enable macro-generated clients.

open_port

Open a port given a capability.

supervise_undeliverable_messages

Spawns a task that listens for undeliverable messages and posts a corresponding ActorSupervisionEvent to the given supervision port.

Type Aliases

Data

Type alias for bytestring data used throughout the system.