Struct UntypedActorRef

pub struct UntypedActorRef { /* private fields */ }

A type-erased reference to an actor, allowing messages to be sent to it without type safety.

UntypedActorRef provides a way to interact with actors without having direct access to the actor instance itself. It holds a sender channel to the actor’s mailbox. This is the internal implementation that handles the actual message passing.

Creating UntypedActorRef

UntypedActorRef instances are typically not created directly, but obtained from a typed ActorRef<T>:

// Get a reference to the untyped actor ref
let untyped_ref = actor_ref.untyped_actor_ref();

// Make a clone if needed
let cloned_untyped_ref = untyped_ref.clone();

Type Safety Warning

Developer Responsibility: When using UntypedActorRef, you are responsible for ensuring that message types match the target actor at runtime. Incorrect message types will result in runtime errors instead of compile-time errors.

Recommended Usage: Use ActorRef<T> by default for compile-time type safety. Only use UntypedActorRef when you specifically need type erasure for:

• Collections of heterogeneous actors (Vec<UntypedActorRef>, HashMap<String, UntypedActorRef>)
• Plugin systems with dynamically loaded actors
• Generic actor management interfaces

Message Passing Methods

• Asynchronous Methods:

  • ask: Send a message and await a reply.
  • ask_with_timeout: Send a message and await a 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 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.

Implementations

impl UntypedActorRef

pub const 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. Returns true only if both mailbox and terminate channels are open.

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

where 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 via the actor’s handle method implementation. This method returns immediately.

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

where M: Send + 'static,

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

Similar to UntypedActorRef::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, R>(&self, msg: M) -> Result<R>

where M: Send + 'static, R: 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 via its handle method and send a reply back.

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

where M: Send + 'static, R: Send + 'static,

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

Similar to UntypedActorRef::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. This will trigger the actor’s on_stop method with killed = true.

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. This will trigger the actor’s on_stop method with killed = false.

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

where M: Send + 'static,

Blocking Functions for Tokio Tasks

These functions are intended for scenarios where CPU-intensive or other blocking operations are performed within a tokio::task::spawn_blocking task, and communication with actors is necessary. They allow such tasks to interact with the actor system synchronously, without using async/await directly within the blocking task.

Example

The following example illustrates using UntypedActorRef::tell_blocking. A similar approach applies to UntypedActorRef::ask_blocking.

let actor_clone = actor_ref.clone();
tokio::task::spawn_blocking(move || {
    // Perform CPU-intensive work

    // Send results to actor
    actor_clone.tell_blocking(MyMessage("Work completed"), Some(Duration::from_secs(1)))
        .expect("Failed to send message");
});

For more comprehensive examples, including UntypedActorRef::ask_blocking, refer to examples/actor_blocking_tasks.rs.

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

where M: Send + 'static, R: Send + 'static,

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

The message is sent to the actor’s mailbox, and this method will block until the actor processes the message and sends a reply or the timeout expires.

Examples

For a complete example, see examples/actor_blocking_tasks.rs.

let actor_ref_clone = actor_ref.clone();
let result = tokio::task::spawn_blocking(move || {
    let timeout = Some(Duration::from_secs(2));
    // Send query and wait for reply
    let response: QueryReply = actor_ref_clone
        .ask_blocking(QueryMessage, timeout)
        .unwrap();
    // Process response...
    response.0
});

Refer to the examples/actor_blocking_tasks.rs file for a runnable demonstration.

Trait Implementations

impl Clone for UntypedActorRef

fn clone(&self) -> UntypedActorRef

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for UntypedActorRef

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

Formats the value using the given formatter.