Trait Actor 

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

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

    // Provided methods
    fn name(&self) -> String { ... }
    fn runtime_handle(&self) -> Handle { ... }
    fn yield_after_each_message(&self) -> bool { ... }
    fn queue_capacity(&self) -> QueueCapacity { ... }
    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 on_drained_messages<'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 + Serialize + 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 runtime_handle(&self) -> Handle

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 50 microseconds should use the ActorRunner::DedicatedThread.

fn yield_after_each_message(&self) -> bool

If set to true, the actor will yield after every single message.

For actors that are calling .await regularly, returning false can yield better performance.

fn queue_capacity(&self) -> QueueCapacity

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

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 on_drained_messages<'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,

This function is called after a series of one, or several messages have been processed and no more message is available.

It is a great place to have the actor “sleep”.

Quickwit’s Indexer actor for instance use on_drained_messages to schedule indexing in such a way that an indexer drains all of its available messages and sleeps for some amount of time.

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

impl<A: Actor> Actor for Supervisor<A>

type ObservableState = SupervisorState