Struct ActorRef

pub struct ActorRef<T: Actor> { /* private fields */ }

A type-safe reference to an actor of type T.

ActorRef<T> provides type-safe message passing to actors, ensuring that only messages that the actor can handle are sent, and that reply types are correctly typed. It wraps an UntypedActorRef and provides compile-time type safety through Rust’s type system and trait bounds.

Type Safety Benefits

• Compile-Time Message Validation: Only messages implementing Message<M> for actor T are accepted
• Automatic Reply Type Inference: Return types are inferred from trait implementations
• Zero Runtime Overhead: Type safety is enforced at compile time with no performance cost
• IDE Support: Full autocomplete and type checking support
• Prevention of Runtime Type Errors: Eliminates downcasting failures and type mismatches

Message Passing Methods

• Asynchronous Methods:

  • ask: Send a message and await a typed reply.
  • ask_with_timeout: Send a message and await a typed reply with a timeout.
  • tell: Send a message without waiting for a reply.
  • tell_with_timeout: Send a message without waiting for a reply with a timeout.

• Blocking Methods for Tokio Blocking Contexts:

  • ask_blocking: Send a message and block until a typed reply is received.
  • tell_blocking: Send a message and block until it is sent.

  These methods are for use within tokio::task::spawn_blocking contexts.

• Control Methods:

  • stop: Gracefully stop the actor.
  • kill: Immediately terminate the actor.

• Utility Methods:

  • identity: Get the unique ID of the actor.
  • is_alive: Check if the actor is still running.
  • untyped_actor_ref: Access the underlying UntypedActorRef.

Recommended Usage

Use ActorRef<T> by default for all actor communication. It provides the same functionality as UntypedActorRef but with compile-time guarantees that prevent type-related runtime errors.

When to use ActorRef<T>:

• Default choice for actor communication
• When you know the actor type at compile time
• When you want compile-time message validation
• When working with strongly-typed actor systems

When to use UntypedActorRef:

• Collections of heterogeneous actors (Vec<UntypedActorRef>, HashMap<String, UntypedActorRef>)
• Plugin systems with dynamically loaded actors
• Generic actor management interfaces
• When you need type erasure for dynamic scenarios

Implementations

impl<T: Actor> ActorRef<T>

pub fn untyped_actor_ref(&self) -> &UntypedActorRef

Returns a reference to the underlying UntypedActorRef for cloning or other operations.

pub fn identity(&self) -> Identity

Returns the unique ID of the actor.

pub fn is_alive(&self) -> bool

Checks if the actor is still alive by verifying if its channels are open.

pub async fn tell<M>(&self, msg: M) -> Result<()>

where T: Message<M>, M: Send + 'static,

Sends a message to the actor without awaiting a reply (fire-and-forget).

The message is sent to the actor’s mailbox for processing. This method returns immediately.

Type safety: Only messages that the actor T can handle via Message<M> trait are accepted.

pub async fn tell_with_timeout<M>( &self, msg: M, timeout: Duration, ) -> Result<()>

where T: Message<M>, M: Send + 'static,

Sends a message to the actor without awaiting a reply (fire-and-forget) with a timeout.

Similar to ActorRef::tell, but allows specifying a timeout for the send operation. The message is sent to the actor’s mailbox, and this method will return once the message is sent or timeout if the send operation doesn’t complete within the specified duration.

pub async fn ask<M>(&self, msg: M) -> Result<T::Reply>

where T: Message<M>, M: Send + 'static, T::Reply: Send + 'static,

Sends a message to the actor and awaits a reply.

The message is sent to the actor’s mailbox, and this method will wait for the actor to process the message and send a reply.

Type safety: The return type R is automatically inferred from the Message<M> trait implementation, ensuring compile-time type safety for replies.

pub async fn ask_with_timeout<M>( &self, msg: M, timeout: Duration, ) -> Result<T::Reply>

where T: Message<M>, M: Send + 'static, T::Reply: Send + 'static,

Sends a message to the actor and awaits a reply with a timeout.

Similar to ActorRef::ask, but allows specifying a timeout for the operation. The message is sent to the actor’s mailbox, and this method will wait for the actor to process the message and send a reply, or timeout if the reply doesn’t arrive within the specified duration.

pub fn kill(&self) -> Result<()>

Sends an immediate termination signal to the actor.

The actor will stop processing messages and shut down as soon as possible. The actor’s final result will indicate it was killed.

pub async fn stop(&self) -> Result<()>

Sends a graceful stop signal to the actor.

The actor will process all messages currently in its mailbox and then stop. New messages sent after this call might be ignored or fail. The actor’s final result will indicate normal completion.

pub fn tell_blocking<M>(&self, msg: M, timeout: Option<Duration>) -> Result<()>

where T: Message<M>, M: Send + 'static,

Synchronous version of ActorRef::tell that blocks until the message is sent.

This method is intended for use within tokio::task::spawn_blocking contexts.

pub fn ask_blocking<M>( &self, msg: M, timeout: Option<Duration>, ) -> Result<T::Reply>

where T: Message<M>, M: Send + 'static, T::Reply: Send + 'static,

Synchronous version of ActorRef::ask that blocks until the reply is received.

This method is intended for use within tokio::task::spawn_blocking contexts.

Trait Implementations

impl<T: Actor> Clone for ActorRef<T>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug + Actor> Debug for ActorRef<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.