Trait Actor 

pub trait Actor:
    Sized
    + Send
    + 'static {
    type Context: ActorContext<Self>;
    type Error: Into<BoxError> + Display + Send + 'static;

    // Provided methods
    fn pre_start(&mut self, ctx: &mut Self::Context) -> Result<(), Self::Error> { ... }
    fn post_start(
        &mut self,
        ctx: &mut Self::Context,
    ) -> impl Future<Output = Result<(), Self::Error>> + Send { ... }
    fn stopping(
        &mut self,
        ctx: &mut Self::Context,
    ) -> impl Future<Output = Result<Stopping, Self::Error>> + Send { ... }
    fn post_stop(
        &mut self,
        ctx: &mut Self::Context,
    ) -> impl Future<Output = Result<(), Self::Error>> + Send { ... }
    fn run<S>(
        self,
        label: S,
    ) -> Result<(Address<Self>, JoinHandle<()>), Self::Error>
       where S: AsRef<str> { ... }
    fn create<S, F>(
        label: S,
        f: F,
    ) -> Result<(Address<Self>, JoinHandle<()>), Self::Error>
       where S: AsRef<str>,
             F: FnOnce(&mut Self::Context) -> Result<Self, Self::Error> { ... }
    fn create_in_span<S, F>(
        label: S,
        parent_span: Option<&Span>,
        f: F,
    ) -> Result<(Address<Self>, JoinHandle<()>), Self::Error>
       where S: AsRef<str>,
             F: FnOnce(&mut Self::Context) -> Result<Self, Self::Error> { ... }
    fn type_erased_recipient_fn() -> Option<TypeErasedRecipientFn<Self>> { ... }
}

An actor.

Required Associated Types

type Context: ActorContext<Self>

The execution context type for this actor.

type Error: Into<BoxError> + Display + Send + 'static

The error type returned by lifecycle hooks and message handlers.

Provided Methods

fn pre_start(&mut self, ctx: &mut Self::Context) -> Result<(), Self::Error>

Invoked before an actor is spawned into the tokio runtime. The actor should be in Unstarted state.

This method is used to perform initialization tasks or spawn child actors. In the default Context implementation, it is not spawned into the tokio runtime and it is outside of the processing loop. Thus it will be invoked only once synchronously. The actor will enter the Starting state after this method returns.

Panics in this method propagate to the caller of run.

fn post_start( &mut self, ctx: &mut Self::Context, ) -> impl Future<Output = Result<(), Self::Error>> + Send

Invoked after an actor is spawned into the tokio runtime. The actor should be in Starting state.

This method is used to perform additional initialization. In the default Context implementation, it is spawned into the tokio runtime and it is outside of the processing loop, which means it will be invoked once and only once, asynchronously. The actor will enter the Running state after this method returns.

Panics in this method terminates the actor immediately and will be notified to the supervisor if there is one.

fn stopping( &mut self, ctx: &mut Self::Context, ) -> impl Future<Output = Result<Stopping, Self::Error>> + Send

Invoked when an actor is being stopped. The actor should be in Stopping state.

This method is used to make decisions about whether to stop or to restart the actor.

fn post_stop( &mut self, ctx: &mut Self::Context, ) -> impl Future<Output = Result<(), Self::Error>> + Send

Invoked after an actor is stopped. The actor should be in Stopped state.

This method is used to perform cleanup tasks or spawn new actors.

fn run<S>( self, label: S, ) -> Result<(Address<Self>, JoinHandle<()>), Self::Error>

where S: AsRef<str>,

Starts an actor and spawns it to the tokio runtime, returns its actor address and the join handle.

fn create<S, F>( label: S, f: F, ) -> Result<(Address<Self>, JoinHandle<()>), Self::Error>

where S: AsRef<str>, F: FnOnce(&mut Self::Context) -> Result<Self, Self::Error>,

Creates a new actor, starts it and spawns it to the tokio runtime, returns its actor address and the join handle.

fn create_in_span<S, F>( label: S, parent_span: Option<&Span>, f: F, ) -> Result<(Address<Self>, JoinHandle<()>), Self::Error>

where S: AsRef<str>, F: FnOnce(&mut Self::Context) -> Result<Self, Self::Error>,

Like create but allows the caller to specify the parent tracing span.

• Some(&span) — use span as the parent.
• None — create the span as a new root (no parent).

Use this when you want to control an actor’s span hierarchy independently of whatever span happens to be entered at the call site.

fn type_erased_recipient_fn() -> Option<TypeErasedRecipientFn<Self>>

Available on crate feature type-erased-recipient-hook only.

Opt-in hook that turns an Address<A> into a type-erased trait object which can be downcast into a concrete Recipient<M>, where M is a specific message type chosen in the overridden implementation of this method.

Sometimes users may need to convert a Recipient<N> backed by an Address<A> into a Recipient<M>. If the actor type A is known, users can retrieve the Address<A> by downcasting the trait object in the Recipient<N>, and then the Address<A> can be converted into a Recipient<M>. However, if the concrete actor type A is not known (e.g., in a function receives a Recipient<N> backed by several different actor types), this approach does not work.

This hook allows users to provide a function f, which defines a two-step conversion from an Address<A> to a Recipient<M> first, with M being a specific message type chosen by the user, and then to a type-erased Box<dyn Any + Send + Sync>. Returning Some(f) causes Address::new to bake f into every address for this actor. To convert a Recipient<N> into a Recipient<M>, users can use the Sender::type_erased_recipient method, which will invoke the function f and return the type-erased trait object, and convert the type-erased trait object back into a Recipient<M> by downcasting.

Crates that extend actors with extra capabilities based on this feature can provide a macro which overrides this method automatically for their users to avoid boilerplate.

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