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

pub trait Actor: Sized + Unpin + '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(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>(arb: &Arbiter, 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.

Associated Types

type Context: ActorContext

Actor execution context type

Loading content...

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::*;

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

fn main() {
    // initialize system
    System::run(|| {
        let addr = MyActor.start(); // <- start actor and get its address
    });
}

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>(arb: &Arbiter, 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::*;

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

fn main() {
    // initialize system
    System::run(|| {
        let addr = MyActor::create(|ctx: &mut Context<MyActor>| MyActor { val: 10 });
    });
}
Loading content...

Implementors

impl Actor for Resolver[src]

type Context = Context<Self>

impl<A> Actor for SyncArbiter<A> where
    A: Actor<Context = SyncContext<A>>, [src]

type Context = Context<Self>

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

type Context = Context<Self>

Loading content...