Trait messages::actor::Actor

source · [−]
pub trait Actor: Unpin + Send + Sync + Sized + 'static {
    fn started<'life0, 'async_trait>(
        &'life0 mut self
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
    where
        'life0: 'async_trait,
        Self: 'async_trait,
    { ... }

    fn stopping<'life0, 'async_trait>(
        &'life0 mut self
    ) -> Pin<Box<dyn Future<Output = ActorAction> + Send + 'async_trait>>
    where
        'life0: 'async_trait,
        Self: 'async_trait,
    { ... }

    fn stopped(&mut self) { ... }

    fn run<'async_trait>(
        self
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
    where
        Self: 'async_trait,
    { ... }

    fn create_and_run<'async_trait, F>(
        f: F
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
    where
        F: FnOnce(&Context<Self>) -> Self + Send,
        F: 'async_trait,
        Self: 'async_trait,
    { ... }
}
Expand description

Actor is an entity capable of receiving and processing messages.

Each actor runs in an associated Context object that is capable of managing the message delivery and maintaing the actor state.

Minimal implementation of an actor doesn’t require any methods on it and can be used on (almost) any type as a marker.

However, optional methods for better control of the actor lifespan are provided:

  • started method is called once Context was launched and is about to start processing incoming messages.
  • stopping method is called after either Address::stop method was executed, or all the Address objects connected to an actor were dropped.
  • stopped method is a notification signaling that the Context future is finishing its execution and after this call Actor object will be dropped.

Stopping

Actor can stop in the following scenarios:

Prerequisites

As actors must be suitable for using in the multithreaded runtimes, each type implementing Actor must be Send, Sync and 'static.

Additionally, it must implement Unpin

Extensions

When one of the runtime features is enabled in this crate, there is also an extension trait available: RuntimeActorExt, which provides more convenient interface for spawning actors, e.g. RuntimeActorExt::spawn.

Examples

This example assumes that messages is used with rt-tokio feature enabled.


struct Ping;

#[async_trait]
impl Actor for Ping {
    async fn started(&mut self) {
        println!("Actor was started");
    }

    async fn stopping(&mut self) -> ActorAction {
        println!("Actor is stopping");
        ActorAction::Stop
    }

    fn stopped(&mut self) {
        println!("Actor is stopped");
    }
}

#[tokio::main]
async fn main() {
   let mut addr = Ping.spawn();
   addr.stop().await;
   addr.wait_for_stop().await;  
}

Provided methods

Method called after Context::run method was invoked.

It is guaranteed to be called before any message will be passed to an actor.

Method called once actor finished processing messages. It can happen either after Address::stop was called or all the Address objects will be dropped.

It is guaranteed that after invocation of this method there will be no messages passed to the actor (unless ActorAction::KeepRunning).

Final notification about actor life end. Invoking this method will only be followed by the destruction of a Context object.

Creates Context object and starts the message processing loop.

Future returned by this method should not normally be directly awaited, but rather is expected to be used in some kind of spawn function of the used runtime (e.g. tokio::spawn or async_std::task::spawn).

Alternative to run function that should be used if an actor needs access to the Context object to be created (e.g. to know its own address).

Implementors