Module actor 

Actor framework — a lightweight actor model built on [Mailbox].

This module provides a minimal actor system where actors communicate via Arc<Message> over pre-allocated ring-buffer mailboxes. The mailbox replaces tokio’s mpsc channels, eliminating per-message allocation and reducing scheduler overhead through batch draining.

Architecture

• Actor trait — defines the message handling interface
• ActorContext — per-actor context with peer ID, router address, and child actor management
• Addr — a clonable, hashable address for sending messages to an actor

Mailbox

All actors use crate::mailbox::mailbox — a bounded VecDeque protected by parking_lot::Mutex with tokio::sync::Notify for wakeups. Messages are wrapped in Arc<Message> so fanout is a refcount bump (~2 ns), not a deep clone.

• Default capacity (65536) — ActorContext::start_actor creates an actor with a generous mailbox. Backpressure only under extreme load.
• Bounded — ActorContext::start_actor_bounded creates an actor with a smaller capacity. When full, Addr::send returns Err(()), applying backpressure. Used for storage write actors.

Message Flow

Sender → Addr.send(msg) → Mailbox (bounded VecDeque<Arc<Message>>)
                               ↓
                     Actor.handle(Arc<Message>, ctx)
                               ↓
                         Actor can:
                         - spawn child actors
                         - send to router
                         - spawn child tasks

Arc<Message> Semantics

Addr::send accepts impl Into<Arc<Message>>, so existing call sites that pass Message::Put(put) still compile — the message is wrapped in Arc inside send. For fanout paths (e.g. relay), callers can pass Arc::clone(&msg) to skip the allocation entirely — all subscribers share the same Arc.

Shutdown

Actors are stopped via a stop signal channel. When the context’s stop() method is called, all child tasks are aborted and stop signals are sent to all child actors.

Structs

ActorContext

Per-actor context providing access to runtime services.

Addr

A clonable, hashable address for sending messages to an actor.

Traits

Actor

The core actor trait.