Trait Actor 

pub trait Actor
where
    Self: Sized + Send + Sync + 'static,
{
    type Message: Debug + Sized + Send + Sync + 'static;
    type Result: Debug + Sized + Send + 'static;
    type Error: Debug + Display + Send;

    // Required methods
    fn address(&self) -> &str;
    fn handle<'life0, 'async_trait>(
        &'life0 mut self,
        msg: Arc<Self::Message>,
    ) -> Pin<Box<dyn Future<Output = Result<Self::Result, Self::Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;

    // Provided methods
    fn pre_start<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: Send + 'async_trait,
             'life0: 'async_trait { ... }
    fn pre_restart<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: Send + 'async_trait,
             'life0: 'async_trait { ... }
    fn post_stop<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: Send + 'async_trait,
             'life0: 'async_trait { ... }
    fn post_restart<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: Send + 'async_trait,
             'life0: 'async_trait { ... }
    fn run_actor<'life0, 'async_trait>(
        &'life0 mut self,
        actor_system_tx: Sender<ActorSystemCmd>,
        error_handling: ErrorHandling,
        ready_tx: Sender<Result<(), ActorError>>,
        channel_size: Option<usize>,
    ) -> Pin<Box<dyn Future<Output = Result<(), ActorError>> + Send + 'async_trait>>
       where Self: Send + 'async_trait,
             'life0: 'async_trait { ... }
    fn register<'life0, 'async_trait>(
        self,
        actor_system: &'life0 mut ActorSystem,
        error_handling: ErrorHandling,
        blocking: Blocking,
        channel_size: Option<usize>,
    ) -> Pin<Box<dyn Future<Output = Result<(), ActorError>> + Send + 'async_trait>>
       where Self: Send + 'async_trait,
             'life0: 'async_trait { ... }
}

User-implemented unit of work in the actor system.

You provide:

• associated types Message, Result, Error,
• address() so the system can place the actor in its address map,
• handle() to process each inbound message.

The system provides the rest: a typed mailbox, a tokio task host (per Blocking), the lifecycle state machine (LifeCycle), and the optional hooks (pre_start, pre_restart, post_stop, post_restart) that fire at the relevant transitions.

Register an actor with actor.register(&mut system, ...) (see register); never implement run_actor manually — its body is the receive/lifecycle loop the system depends on.

'static + Send + Sync because the actor’s state moves into a tokio task that may outlive the caller.

Required Associated Types

type Message: Debug + Sized + Send + Sync + 'static

Inbound message type. Debug for log output. With multi-node on, must also implement xancode::Codec for cross-node serialization (enforced via MaybeCodec on the send methods).

type Result: Debug + Sized + Send + 'static

Reply type returned from handle. Visible to callers of send_and_recv::<Self>.

type Error: Debug + Display + Send

Error type returned from handle on failure. Combined with the per-actor ErrorHandling policy to decide whether to resume, restart, or stop the actor.

Required Methods

fn address(&self) -> &str

Returns this actor’s address. Must be stable for the actor’s lifetime — the system uses it as the key in its address map.

fn handle<'life0, 'async_trait>( &'life0 mut self, msg: Arc<Self::Message>, ) -> Pin<Box<dyn Future<Output = Result<Self::Result, Self::Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Process one inbound message. Called once per message in the actor’s receive loop. The Arc<Self::Message> is shared with potential broadcast recipients — clone the inner payload if you need to mutate it.

Return Err(...) to trigger this actor’s ErrorHandling policy: Resume drops the message and continues, Restart tears down the mailbox and re-enters via pre_restart / post_restart, Stop runs post_stop and terminates.

Provided Methods

fn pre_start<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: Send + 'async_trait, 'life0: 'async_trait,

Runs once after the actor enters LifeCycle::Starting but before transitioning to Receiving. Use for one-time setup that needs &mut self (e.g. opening a connection, registering with an external service).

fn pre_restart<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: Send + 'async_trait, 'life0: 'async_trait,

Runs after post_stop and before the actor re-enters Starting/Restarting for a restart. Use to release / re-prepare state that needs to be fresh in the next incarnation.

fn post_stop<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: Send + 'async_trait, 'life0: 'async_trait,

Runs as the actor enters LifeCycle::Stopping — either due to Stop error handling, a kill from unregister, or an explicit restart. Last chance to clean up before the task exits.

fn post_restart<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: Send + 'async_trait, 'life0: 'async_trait,

Runs at the top of every restart iteration (after the first run), before pre_start’s normal startup work. Symmetric to pre_restart; use for “what to do once the restart actually begins” rather than “what to do before tearing down”.

fn run_actor<'life0, 'async_trait>( &'life0 mut self, actor_system_tx: Sender<ActorSystemCmd>, error_handling: ErrorHandling, ready_tx: Sender<Result<(), ActorError>>, channel_size: Option<usize>, ) -> Pin<Box<dyn Future<Output = Result<(), ActorError>> + Send + 'async_trait>>

where Self: Send + 'async_trait, 'life0: 'async_trait,

Internal receive/lifecycle loop.

Owns the mailbox, drains messages, applies ErrorHandling, fires the lifecycle hooks, and reports state transitions back to actor_system_loop via ActorSystemCmd. Do not implement this method — use register to wire the actor up.

channel_size is the mailbox capacity under bounded-channel and is ignored under unbounded-channel.

fn register<'life0, 'async_trait>( self, actor_system: &'life0 mut ActorSystem, error_handling: ErrorHandling, blocking: Blocking, channel_size: Option<usize>, ) -> Pin<Box<dyn Future<Output = Result<(), ActorError>> + Send + 'async_trait>>

where Self: Send + 'async_trait, 'life0: 'async_trait,

Register the actor with actor_system and spawn its receive loop.

Consumes self (the actor’s state moves into the spawned task). Awaits until the system confirms registration (or rejects it with AddressAlreadyExist / AddressNotOwned), so on Ok(()) the actor is wired up — though it may still be in LifeCycle::Starting when this returns.

• error_handling: per-actor ErrorHandling policy applied on every handle error.
• blocking: chooses between tokio::spawn (NonBlocking) and spawn_blocking + block_on (Blocking). Pick Blocking if the handler does long synchronous work that would otherwise starve the async runtime.
• channel_size: override the mailbox capacity for this actor. None uses the default (4096). Ignored under unbounded-channel.

Dyn Compatibility

This trait is not dyn compatible.

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

Implementors