Trait ActorContext 

pub trait ActorContext<A>:
    Sized
    + Send
    + 'static
where
    A: Actor<Context = Self>,
{
    // Required methods
    fn new(label: String) -> Self;
    fn index(&self) -> ActorId;
    fn label(&self) -> &str;
    fn address(&self) -> Address<A>;
    fn take_mailbox(&mut self) -> Option<Mailbox<A>>;
    fn state(&self) -> ActorState;
    fn set_state(&mut self, state: ActorState);
    fn process_loop(
        &mut self,
        actor: &mut A,
        mailbox: &mut Mailbox<A>,
    ) -> impl Future<Output = Result<(), A::Error>> + Send;

    // Provided methods
    fn stop(&mut self) { ... }
    fn terminate(&mut self) { ... }
    fn supervisor(&self) -> Option<&Recipient<SupervisionEvent<A>>> { ... }
    fn set_supervisor(
        &mut self,
        supervisor: Option<Recipient<SupervisionEvent<A>>>,
    ) { ... }
    fn notify_supervisor(
        &mut self,
        event: SupervisionEvent<A>,
    ) -> impl Future<Output = ()> + Send { ... }
    fn try_notify_supervisor(&mut self, event: SupervisionEvent<A>) { ... }
    fn run(
        self,
        actor: A,
        span: Span,
    ) -> Result<(Address<A>, JoinHandle<()>), A::Error> { ... }
    fn process(
        &mut self,
        actor: &mut A,
        mailbox: Mailbox<A>,
    ) -> impl Future<Output = Result<Result<(), A::Error>, Box<dyn Any + Send>>> + Send { ... }
}

The execution context of an actor.

Each actor is associated with a context which manages its lifecycle and communication channels. The actor’s associated type Context defines the specific context type to use. A context type must implement this trait.

Required Methods

fn new(label: String) -> Self

Constructs a new actor context.

fn index(&self) -> ActorId

Returns the index of the actor.

fn label(&self) -> &str

Returns the label of the actor.

fn address(&self) -> Address<A>

Returns the address of the actor.

fn take_mailbox(&mut self) -> Option<Mailbox<A>>

Moves the mailbox of the actor out of the context, leaving None in its place.

Typically the address and the mailbox are created together in the constructor of the context. However, since the process method consumes the mailbox, the context needs to provide a way to move the mailbox out of itself so that it can be passed into the process method.

Example

A typical implementation stores the mailbox as an Option<Mailbox<A>> field and delegates to Option::take:

struct MyContext<A: Actor<Context = Self>> {
    mailbox: Option<Mailbox<A>>,
    // ... other fields (address, state, etc.)
}

impl<A: Actor<Context = Self>> ActorContext<A> for MyContext<A> {
    fn take_mailbox(&mut self) -> Option<Mailbox<A>> {
        self.mailbox.take()
    }

    // ... other trait methods
}

The first call returns Some(mailbox); subsequent calls return None.

fn state(&self) -> ActorState

Returns the state of the actor.

fn set_state(&mut self, state: ActorState)

Sets the state of the actor.

fn process_loop( &mut self, actor: &mut A, mailbox: &mut Mailbox<A>, ) -> impl Future<Output = Result<(), A::Error>> + Send

The message processing loop of the actor.

This method is invoked by process. It is responsible for receiving messages from the mailbox and handling them.

Provided Methods

fn stop(&mut self)

Stops the actor.

This method will switch the actor to the Stopping state.

fn terminate(&mut self)

Terminates the actor.

This method will switch the actor to the Stopped state.

fn supervisor(&self) -> Option<&Recipient<SupervisionEvent<A>>>

Returns a reference to the supervisor of the actor, if any.

Override the supervisor method and the set_supervisor method to opt-in the supervisor feature.

fn set_supervisor(&mut self, supervisor: Option<Recipient<SupervisionEvent<A>>>)

Sets a supervisor.

Override the supervisor method and the set_supervisor method to opt-in the supervisor feature.

fn notify_supervisor( &mut self, event: SupervisionEvent<A>, ) -> impl Future<Output = ()> + Send

Notifies the supervisor for an event.

This method will wait until there is capacity in the mailbox of the supervisor.

fn try_notify_supervisor(&mut self, event: SupervisionEvent<A>)

Notifies the supervisor for an event.

This method will return immediately if there is no capacity in the mailbox of the supervisor.

fn run( self, actor: A, span: Span, ) -> Result<(Address<A>, JoinHandle<()>), A::Error>

Starts the actor and returns its address and a join handle.

This method consumes the context and the actor.

fn process( &mut self, actor: &mut A, mailbox: Mailbox<A>, ) -> impl Future<Output = Result<Result<(), A::Error>, Box<dyn Any + Send>>> + Send

The main processing flow of the actor.

This method is invoked by run. It is responsible for invoking the post_start and the post_stop lifecycle hooks. It is the user’s responsibility to choose where to invoke the stopping lifecycle hook. The default implementation handles the stopping in the process_loop, but users can handle it here by overriding the default implementation.

Return value

The nested Result<Result<(), A::Error>, Box<dyn Any + Send>> encodes three outcomes:

• Ok(Ok(())) — the actor started, ran, and stopped cleanly.
• Ok(Err(error)) — a lifecycle method returned an Actor::Error (from post_start, process_loop, or post_stop).
• Err(panic_payload) — a lifecycle method panicked. The payload is the value caught by catch_unwind. When process_loop panics, post_stop is skipped because the actor’s state is not assumed to be safe to observe after a panic.

If both process_loop and post_stop return errors (neither panics), the process_loop error is returned and the post_stop error is discarded.

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> ActorContext<A> for CronContext<A>

where A: Actor<Context = Self> + CronActor,

Available on crate feature cron only.

impl<A> ActorContext<A> for Context<A>

where A: Actor<Context = Self>,