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 ActorAddr (given by actor_id in the following example):

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

port.post(&client, 123);
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(actor_id);

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

port.post(&client, 123u64);
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 PortAddr which globally names the port.
3. Mailbox provides interfaces to deliver serialized messages to ports named by their PortAddr.

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

Undeliverable-message log invariants (UM-*)

The undelivered_message_abandoned log at UndeliverableMailboxSender::post_unchecked is a user-facing surface: it fires when a message could not be delivered and could not be returned to its sender. The following invariants govern its shape so the log stays scannable and its downstream consumers (Scuba, alerts) stay stable.

• UM-1 (bounded abandoned-message log). The log must not emit unbounded envelope.headers().to_string() or envelope.data().to_string(). Payload observability is provided by message_type (data.typename()) and data_len (data.len()) — cheap, bounded, and type-safe.

• UM-2 (stable compatibility fields). The actor_name and actor_id fields stay on the log with their current values and types. Readability improvements are strictly additive on this surface; renames or removals require a separate migration diff that coordinates with downstream consumers.

• UM-3a (destination naming). When the envelope carries no OPERATION_ENDPOINT, the format string names the transport destination: "message not delivered to <dest>".

• UM-3b (operation naming). When the envelope carries OPERATION_ENDPOINT, the format string names the operation: "abandoned message for <endpoint>".

  OPERATION_* keys live in hyperactor::mailbox::headers because the readers (this log, the undeliverable formatter) live in hyperactor and can’t depend upward on monarch_hyperactor. Keys whose consumers are not at this layer don’t belong here.

Re-exports

pub use mailbox_admin_message::MailboxAdminMessage;

pub use mailbox_admin_message::MailboxAdminMessageHandler;

Modules

headers

For message headers and latency tracking. Message headers and latency tracking functionality for the mailbox system.

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.

FallbackMailboxRouter

A router that first checks a MailboxRouter for a matching prefix route, falling back to a default sender when none is found.

LostMessage

For Undeliverable, a message type for delivery failures. Metadata for a message that could not be delivered and could not be returned.

Mailbox

A mailbox coordinates message delivery to actors through typed Ports 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 PortAddr into a Sink.

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.

Undeliverable

An undeliverable M-typed message.

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.

Type Aliases

Data

Type alias for bytestring data used throughout the system.