Trait actix::prelude::Actor [−] [src]

pub trait Actor: Sized + 'static {
    type Context: ActorContext;
    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<Addr>(self) -> Addr
    where
        Self: Actor<Context = Context<Self>> + ActorAddress<Self, Addr>,
    { ... }

    fn start_default<Addr>() -> Addr
    where
        Self: Default + Actor<Context = Context<Self>> + ActorAddress<Self, Addr>,
    { ... }

    fn create<Addr, F>(f: F) -> Addr
    where
        Self: Actor<Context = Context<Self>> + ActorAddress<Self, Addr>,
        F: FnOnce(&mut Context<Self>) -> Self + 'static,
    { ... }
}

Actors are objects which encapsulate state and behavior.

Actors run within specific execution context Context. Context object is available only during execution. Each actor has separate execution context. Also execution context controls lifecycle of an actor.

Actors communicate exclusively by exchanging messages. Sender actor can wait for response. Actors are not referenced directly, but by non thread safe Addr<Unsync, A> or thread safe address Addr<Syn, A> To be able to handle specific message actor has to provide Handler<M> implementation for this message. All messages are statically typed. Message could be handled in asynchronous fashion. Actor can spawn other actors or add futures or streams to execution context. Actor trait provides several methods that allow to control actor lifecycle.

Actor lifecycle

Started

Actor starts in Started state, during this state started method get called.

Running

After Actor's method started get called, actor transitions to Running state. Actor can stay in running state indefinitely long.

Stopping

Actor execution state changes to stopping state in following situations,

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

Actor could restore from stopping state to running state by creating new address or adding evented object, like future or stream, in Actor::stopping method.

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

Stopped

If actor does not modify execution context during stopping state actor state changes to Stopped. This state is considered final and at this point actor get dropped.

Associated Types

Actor execution context type

Provided Methods

Method is called when actor get polled first time.

Method is called after an actor is in Actor::Stopping state. There could be several reasons for stopping. Context::stop get called by the actor itself. All addresses to current actor get dropped and no more evented objects left in the context.

Actor could restore from stopping state by returning Running::Continue value.

Method is called after an actor is stopped, it can be used to perform any needed cleanup work or spawning more actors. This is final state, after this call actor get dropped.

Start new asynchronous actor, returns address of newly created actor.

Examples

use actix::*;

// initialize system
System::new("test");

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

let addr: Addr<Unsync, _> = MyActor.start();

Start new asynchronous actor, returns address of newly created actor.

Use create method, if you need Context object during actor initialization.

Examples

use actix::*;

// initialize system
System::new("test");

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

let addr: Addr<Unsync, _> = MyActor::create(|ctx: &mut Context<MyActor>| {
    MyActor{val: 10}
});

Implementors