Skip to main content

Actor

beam::actor

Trait Actor 

Source 
pub trait Actor:
    Send
    + Sync
    + 'static {
    // Required method
    fn handle<'life0, 'life1, 'async_trait>(
        &'life0 mut self,
        message: Arc<Message>,
        context: &'life1 ActorContext,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;

    // Provided methods
    fn handle_batch<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 mut self,
        batch: &'life1 mut Vec<Arc<Message>>,
        context: &'life2 ActorContext,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn pre_start<'life0, 'life1, 'async_trait>(
        &'life0 mut self,
        _context: &'life1 ActorContext,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn stopping<'life0, 'life1, 'async_trait>(
        &'life0 mut self,
        _context: &'life1 ActorContext,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn subscribe_to_everything(&self) -> bool { ... }
    fn is_relay_server(&self) -> bool { ... }
    fn try_clone_storage(&self) -> Option<Box<dyn Actor>> { ... }
}
Expand description

The core actor trait.

Implementors define how to handle [Message] values and optionally configure lifecycle hooks (pre_start, stopping).

§Lifecycle

  1. pre_start — called once before the actor begins processing messages
  2. handle — called for each message received
  3. stopping — called once after the actor’s message loop exits

§Example

use beam::actor::{Actor, ActorContext};
use beam::message::Message;
use async_trait::async_trait;
use std::sync::Arc;

struct EchoActor;

#[async_trait]
impl Actor for EchoActor {
    async fn handle(&mut self, msg: Arc<Message>, _ctx: &ActorContext) {
        // Process message — &*msg gives &Message
    }
}

Required Methods§

Source

fn handle<'life0, 'life1, 'async_trait>( &'life0 mut self, message: Arc<Message>, context: &'life1 ActorContext, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Handle an incoming message.

Messages are wrapped in Arc<Message> so that fanout paths (e.g. relay) can share a single allocation across all subscribers. Use &*msg or msg.as_ref() to access the inner [Message].

Provided Methods§

Source

fn handle_batch<'life0, 'life1, 'life2, 'async_trait>( &'life0 mut self, batch: &'life1 mut Vec<Arc<Message>>, context: &'life2 ActorContext, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Handle a batch of messages drained from the mailbox.

Override to process multiple messages in a single call, enabling batch optimizations like coalescing WebSocket writes. The default implementation calls handle for each message.

Implementors that override this must drain all messages from batch (e.g. via batch.drain(..) or batch.clear()).

Source

fn pre_start<'life0, 'life1, 'async_trait>( &'life0 mut self, _context: &'life1 ActorContext, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Called once before the actor starts processing messages.

Override to initialize state, spawn child actors, or establish connections. Defaults to a no-op.

Source

fn stopping<'life0, 'life1, 'async_trait>( &'life0 mut self, _context: &'life1 ActorContext, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Called once after the actor’s message loop exits.

Override for cleanup logic. Defaults to a no-op.

Source

fn subscribe_to_everything(&self) -> bool

Whether this actor wants to receive all messages (not just addressed to it). Used by the Multicast adapter.

Defaults to false.

Source

fn is_relay_server(&self) -> bool

Whether this actor is a relay server (WsServer) that accepts incoming WebSocket connections and fans out to individual WsConn clients.

The Router uses this to distinguish WsServer (which handles per-connection echo-back via msg.is_from(conn)) from OutgoingWebsocketManager (which sends to a single remote relay and must be skipped on echo-back).

Defaults to false.

Source

fn try_clone_storage(&self) -> Option<Box<dyn Actor>>

Attempts to produce a clone of this actor for storage read/write splitting.

Storage adapters override this to return a boxed clone, enabling the [crate::router::Router] to start separate read and write actors that share the same underlying database. Non-storage actors return None (the default).

When the Router receives Some, it starts two actors: one registered in read_adapters (receives only Get), one in write_adapters (receives Put, BatchPut, Flush). Both share the same underlying data store via Arc, so reads see committed writes immediately.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§