Trait Actor

pub trait Actor:
    Sized
    + Unpin
    + 'static {
    type Context: ActorContext;

    // Provided methods
    fn started(&mut self, ctx: &mut Self::Context) { ... }
    fn stopping(&mut self, ctx: &mut Self::Context) -> Running { ... }
    fn stopped(&mut self, ctx: &mut Self::Context) { ... }
    fn start(self) -> Addr<Self>
       where Self: Actor<Context = Context<Self>> { ... }
    fn start_default() -> Addr<Self>
       where Self: Actor<Context = Context<Self>> + Default { ... }
    fn start_in_arbiter<F>(wrk: &ArbiterHandle, f: F) -> Addr<Self>
       where Self: Actor<Context = Context<Self>>,
             F: FnOnce(&mut Context<Self>) -> Self + Send + 'static { ... }
    fn create<F>(f: F) -> Addr<Self>
       where Self: Actor<Context = Context<Self>>,
             F: FnOnce(&mut Context<Self>) -> Self { ... }
}

Actors are objects which encapsulate state and behavior.

Actors run within a specific execution context Context<A>. The context object is available only during execution. Each actor has a separate execution context. The execution context also controls the lifecycle of an actor.

Actors communicate exclusively by exchanging messages. The sender actor can wait for a response. Actors are not referenced directly, but by address Addr To be able to handle a specific message actor has to provide a Handler<M> implementation for this message. All messages are statically typed. A message can be handled in asynchronous fashion. An actor can spawn other actors or add futures or streams to the execution context. The actor trait provides several methods that allow controlling the actor lifecycle.

Actor lifecycle

Started

An actor starts in the Started state, during this state the started method gets called.

Running

After an actor’s started method got called, the actor transitions to the Running state. An actor can stay in the running state for an indefinite amount of time.

Stopping

The actor’s execution state changes to stopping in the following situations:

• Context::stop gets called by actor itself
• all addresses to the actor get dropped
• no evented objects are registered in its context.

An actor can return from the stopping state to the running state by creating a new address or adding an evented object, like a future or stream, in its Actor::stopping method.

If an actor changed to a stopping state because Context::stop() got called, the context then immediately stops processing incoming messages and calls the Actor::stopping() method. If an actor does not return back to a running state, all unprocessed messages get dropped.

Stopped

If an actor does not modify execution context while in stopping state, the actor state changes to Stopped. This state is considered final and at this point the actor gets dropped.

Required Associated Types

type Context: ActorContext

Actor execution context type

Provided Methods

fn started(&mut self, ctx: &mut Self::Context)

Called when an actor gets polled the first time.

fn stopping(&mut self, ctx: &mut Self::Context) -> Running

Called after an actor is in Actor::Stopping state.

There can be several reasons for stopping:

• Context::stop gets called by the actor itself.
• All addresses to the current actor get dropped and no more evented objects are left in the context.

An actor can return from the stopping state to the running state by returning Running::Continue.

fn stopped(&mut self, ctx: &mut Self::Context)

Called after an actor is stopped.

This method can be used to perform any needed cleanup work or to spawn more actors. This is the final state, after this method got called, the actor will be dropped.

fn start(self) -> Addr<Self>

where Self: Actor<Context = Context<Self>>,

Start a new asynchronous actor, returning its address.

Examples

use actix::prelude::*;

struct MyActor;
impl Actor for MyActor {
    type Context = Context<Self>;
}

#[actix::main]
async fn main() {
    // start actor and get its address
    let addr = MyActor.start();
}

fn start_default() -> Addr<Self>

where Self: Actor<Context = Context<Self>> + Default,

Construct and start a new asynchronous actor, returning its address.

This is constructs a new actor using the Default trait, and invokes its start method.

fn start_in_arbiter<F>(wrk: &ArbiterHandle, f: F) -> Addr<Self>

where Self: Actor<Context = Context<Self>>, F: FnOnce(&mut Context<Self>) -> Self + Send + 'static,

Start new actor in arbiter’s thread.

fn create<F>(f: F) -> Addr<Self>

where Self: Actor<Context = Context<Self>>, F: FnOnce(&mut Context<Self>) -> Self,

Start a new asynchronous actor given a Context.

Use this method if you need the Context object during actor initialization.

Examples

use actix::prelude::*;

struct MyActor {
    val: usize,
}
impl Actor for MyActor {
    type Context = Context<Self>;
}

#[actix::main]
async fn main() {
    let addr = MyActor::create(|ctx: &mut Context<MyActor>| MyActor { val: 10 });
}

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 for SyncArbiter<A>

where A: Actor<Context = SyncContext<A>>,

type Context = Context<SyncArbiter<A>>

impl<T: Sized + Unpin + 'static> Actor for Mocker<T>

type Context = Context<Mocker<T>>