Trait Actor

pub trait Actor:
    Send
    + Sync
    + Sized
    + 'static {
    type ObservableState: Send + Sync + Clone + Debug;

    // Required method
    fn observable_state(&self) -> Self::ObservableState;

    // Provided methods
    fn name(&self) -> String { ... }
    fn runner(&self) -> ActorRunner { ... }
    fn queue_capacity(&self) -> QueueCapacity { ... }
    fn span(&self, _ctx: &ActorContext<Self>) -> Span { ... }
    fn initialize<'life0, 'life1, 'async_trait>(
        &'life0 mut self,
        _ctx: &'life1 ActorContext<Self>,
    ) -> Pin<Box<dyn Future<Output = Result<(), ActorExitStatus>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn finalize<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 mut self,
        _exit_status: &'life1 ActorExitStatus,
        _ctx: &'life2 ActorContext<Self>,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
}

An actor has an internal state and processes a stream of messages. Each actor has a mailbox where the messages are enqueued before being processed.

While processing a message, the actor typically

• update its state;
• emits one or more messages to other actors.

Required Associated Types

type ObservableState: Send + Sync + Clone + Debug

Piece of state that can be copied for assert in unit test, admin, etc.

Required Methods

fn observable_state(&self) -> Self::ObservableState

Extracts an observable state. Useful for unit tests, and admin UI.

This function should return quickly.

Provided Methods

fn name(&self) -> String

A name identifying the type of actor.

Ideally respect the CamelCase convention.

It does not need to be “instance-unique”, and can be the name of the actor implementation.

fn runner(&self) -> ActorRunner

The runner method makes it possible to decide the environment of execution of the Actor.

Actor with a handler that may block for more than 50microsecs should use the ActorRunner::DedicatedThread.

fn queue_capacity(&self) -> QueueCapacity

The Actor’s incoming mailbox queue capacity. It is set when the actor is spawned.

fn span(&self, _ctx: &ActorContext<Self>) -> Span

Creates a span associated to all logging happening during the lifetime of an actor instance.

fn initialize<'life0, 'life1, 'async_trait>( &'life0 mut self, _ctx: &'life1 ActorContext<Self>, ) -> Pin<Box<dyn Future<Output = Result<(), ActorExitStatus>> + Send + 'async_trait>>

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

Initialize is called before running the actor.

This function is useful for instance to schedule an initial message in a looping actor.

It can be compared just to an implicit Initial message.

Returning an ActorExitStatus will therefore have the same effect as if it was in process_message (e.g. the actor will stop, the finalize method will be called. the kill switch may be activated etc.)

fn finalize<'life0, 'life1, 'life2, 'async_trait>( &'life0 mut self, _exit_status: &'life1 ActorExitStatus, _ctx: &'life2 ActorContext<Self>, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Hook that can be set up to define what should happen upon actor exit. This hook is called only once.

It is always called regardless of the reason why the actor exited. The exit status is passed as an argument to make it possible to act conditionnally upon it. For instance, it is often better to do as little work as possible on a killed actor. It can be done by checking the exit_status and performing an early-exit if it is equal to ActorExitStatus::Killed.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors