Trait simpl_actor::ActorRef

pub trait ActorRef: Clone {
    // Required methods
    fn id(&self) -> u64;
    fn is_alive(&self) -> bool;
    async fn link_child<R: ActorRef>(&self, child: &R);
    async fn unlink_child<R: ActorRef>(&self, child: &R);
    async fn link_together<R: ActorRef>(&self, actor_ref: &R);
    async fn unlink_together<R: ActorRef>(&self, actor_ref: &R);
    async fn notify_link_died(
        &self,
        id: u64,
        reason: ActorStopReason
    ) -> Result<(), ActorError>;
    async fn stop_gracefully(&self) -> Result<(), ActorError>;
    fn stop_immediately(&self) -> Result<(), ActorError>;
    async fn wait_for_stop(&self);
}

Provides functionality to stop and wait for an actor to complete based on an actor ref.

This trait is automatically implemented by the #[actor] macro.

Required Methods

fn id(&self) -> u64

Returns the actor identifier.

fn is_alive(&self) -> bool

Returns whether the actor is currently alive.

async fn link_child<R: ActorRef>(&self, child: &R)

Links this actor with a child, notifying the child actor if the parent dies through Actor::on_link_died, but not visa versa.

async fn unlink_child<R: ActorRef>(&self, child: &R)

Unlinks the actor with a previously linked actor.

async fn link_together<R: ActorRef>(&self, actor_ref: &R)

Links two actors with one another, notifying eachother if either actor dies through Actor::on_link_died.

This operation is atomic.

async fn unlink_together<R: ActorRef>(&self, actor_ref: &R)

Unlinks two previously linked actors.

This operation is atomic.

async fn notify_link_died( &self, id: u64, reason: ActorStopReason ) -> Result<(), ActorError>

Notifies the actor that one of its links died.

This is called automatically when an actor dies.

async fn stop_gracefully(&self) -> Result<(), ActorError>

Signals the actor to stop after processing all messages currently in its mailbox.

This method sends a special stop message to the end of the actor’s mailbox, ensuring that the actor will process all preceding messages before stopping. Any messages sent after this stop signal will be ignored and dropped. This approach allows for a graceful shutdown of the actor, ensuring all pending work is completed before termination.

fn stop_immediately(&self) -> Result<(), ActorError>

Signals the actor to stop immediately, bypassing its mailbox.

This method instructs the actor to terminate as soon as it finishes processing the current message, if any. Messages in the mailbox that have not yet been processed will be ignored and dropped. This method is useful for immediate shutdown scenarios where waiting for the mailbox to empty is not feasible or desired.

Note: If the actor is in the middle of processing a message, it will complete that message before stopping.

async fn wait_for_stop(&self)

Waits for the actor to finish processing and stop.

This method suspends execution until the actor has stopped, ensuring that any ongoing processing is completed and the actor has fully terminated. This is particularly useful in scenarios where it’s necessary to wait for an actor to clean up its resources or complete its final tasks before proceeding.

Note: This method does not initiate the stop process; it only waits for the actor to stop. You should signal the actor to stop using stop_gracefully or stop_immediately before calling this method.

Examples

// Assuming `actor.stop_gracefully().await` has been called earlier
actor.wait_for_stop().await;

Object Safety

This trait is not object safe.

Implementors