Struct ActorRef

Source

pub struct ActorRef { /* private fields */ }

Expand description

A reference to an actor, allowing messages to be sent to it.

ActorRef 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.

§Message Passing Methods

Asynchronous Methods:
- ask: Send a message and await a reply.
- tell: Send a message without waiting for a reply.
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§

Source §

impl ActorRef

Source

pub const fn id(&self) -> usize

Returns the unique ID of the actor.

Source

pub fn is_alive(&self) -> bool

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

Source

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. This method returns immediately.

Source

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 and send a reply.

Source

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 on_stop lifecycle hook will be called with ActorStopReason::Killed.

Source

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 on_stop lifecycle hook will be called with ActorStopReason::Normal if no errors occur during shutdown.

Source

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 tell_blocking. A similar approach applies to 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("Work completed", Some(Duration::from_secs(1)))
        .expect("Failed to send message");
});

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

Source

pub fn ask_blocking<M, R>(&self, msg: M, timeout: Option<Duration>) -> Result<R>
where M: Send + 'static, R: Send + 'static,

Synchronous version of 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.

use rsactor::ActorRef;
use std::time::Duration;
struct QueryMessage;
fn main() -> anyhow::Result<()> {
    let actor_ref: ActorRef = panic!(); // Placeholder
    let result = tokio::task::spawn_blocking(move || {
        let timeout = Some(Duration::from_secs(2));
        let response: String = actor_ref.ask_blocking(QueryMessage, timeout).unwrap();
        // Process response...
        response
    });
    Ok(())
}