Skip to content

Latest commit

 

History

History
1121 lines (867 loc) · 39.4 KB

FAQ.md

File metadata and controls

1121 lines (867 loc) · 39.4 KB

rsActor FAQ

This FAQ provides answers to common questions about the rsActor framework.

General

Q1: What is rsActor?

A1: rsActor is a lightweight, Tokio-based actor framework in Rust focused on providing a simple and efficient actor model for local, in-process systems. It emphasizes clean message-passing semantics and straightforward actor lifecycle management while maintaining high performance for Rust applications.

Q2: What are the main design goals or philosophy behind rsActor?

A2: The primary goals are simplicity and efficiency for in-process actor systems. It leverages Tokio for its asynchronous runtime and provides core actor primitives with minimal boilerplate. Key features include:

  • Type Safety: Strong compile-time type safety through ActorRef<T>
  • Performance: Zero-cost abstractions with efficient message passing
  • Simplicity: Clean APIs with optional derive macros for reduced boilerplate
  • Observability: Optional tracing support for production debugging

Q3: How does rsActor compare to other Rust actor frameworks like Actix or Kameo?

A3:

  • Scope: rsActor is designed for local, in-process actors only and does not support remote actors or clustering, unlike some more comprehensive frameworks.
  • Simplicity: It aims for a smaller API surface and less complexity compared to frameworks like Actix, with a focus on essential actor model features.
  • Type Safety: Provides strong compile-time type safety through ActorRef<T> while maintaining flexibility.
  • Features: Compared to Kameo, rsActor provides:
    • Concrete ActorRef<T> with compile-time type safety
    • Optional tracing support for production observability
    • Straightforward lifecycle management with on_start, on_run, and on_stop hooks
    • Both #[message_handlers] macro and manual Message<T> trait implementation
  • Error Handling: Uses ActorResult enum to indicate startup or runtime failures with detailed error information and failure phases.

Actor Definition and Usage

Q4: How do I define an actor?

A4: To define an actor, you can choose between two approaches:

Option A: Using the Actor Derive Macro and Message Handlers Macro (Recommended)

  1. Create a struct for your actor's state and derive Actor.
  2. Define the message types your actor will handle.
  3. Use the #[message_handlers] attribute macro with #[handler] method attributes to automatically implement message handling.

Option B: Manual Implementation (for complex initialization)

  1. Create a struct for your actor's state.
  2. Define a struct or tuple for your actor's initialization arguments (this will be Actor::Args).
  3. Implement the Actor trait for your state struct. This involves:
    • Defining an associated type Args (the type of arguments your on_start method will take).
    • Defining an associated type Error (the error type your actor's lifecycle methods can return).
    • Implementing an on_start method which initializes your actor from the arguments.
    • Implementing on_run and on_stop methods, which are optional and have default implementations.
  4. Define the message types your actor will handle.
  5. For each message type, implement the Message<MessageType> trait for your actor struct.
  6. Use the #[message_handlers] macro to implement message handling, or the deprecated impl_message_handler! macro.

Q5: Is there a simple example of an actor?

A5: Here are examples using both approaches:

Recommended Approach (Using Derive and Message Handlers Macros)

use rsactor::{Actor, ActorRef, message_handlers, spawn};

// Define actor struct with derive macro
#[derive(Actor)]
struct SimpleActor {
    counter: u32,
}

// Define message types
struct Increment(u32);
struct GetCount;

// Use message_handlers macro with handler attributes
#[message_handlers]
impl SimpleActor {
    #[handler]
    async fn handle_increment(&mut self, msg: Increment, _: &ActorRef<Self>) -> u32 {
        self.counter += msg.0;
        self.counter
    }

    #[handler]
    async fn handle_get_count(&mut self, _msg: GetCount, _: &ActorRef<Self>) -> u32 {
        self.counter
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create and spawn actor
    let actor = SimpleActor { counter: 0 };
    let (actor_ref, _handle) = spawn(actor);

    // Send messages
    let new_count = actor_ref.ask(Increment(5)).await?;
    println!("New count: {}", new_count);

    let current_count = actor_ref.ask(GetCount).await?;
    println!("Current count: {}", current_count);

    // Gracefully stop the actor
    actor_ref.stop().await?;
    Ok(())
}

Manual Implementation Approach

use rsactor::{Actor, ActorRef, Message, impl_message_handler, spawn, ActorResult};
use anyhow::Result;

// Define actor struct
struct SimpleActor {
    counter: u32,
}

// Implement Actor trait
impl Actor for SimpleActor {
    type Args = u32; // Starting counter value
    type Error = anyhow::Error;

    async fn on_start(initial_counter: Self::Args, _actor_ref: &ActorRef<Self>) -> Result<Self, Self::Error> {
        Ok(SimpleActor { counter: initial_counter })
    }
}

// Define message type
struct Increment(u32);

// Implement message handler
impl Message<Increment> for SimpleActor {
    type Reply = u32; // Return new counter value

    async fn handle(&mut self, msg: Increment, _actor_ref: &ActorRef<Self>) -> Self::Reply {
        self.counter += msg.0;
        self.counter
    }
}

// Use macro to implement MessageHandler trait (deprecated approach)
impl_message_handler!(SimpleActor, [Increment]);

#[tokio::main]
async fn main() -> Result<()> {
    // Spawn actor with initial counter value of 0
    let (actor_ref, _join_handle) = spawn::<SimpleActor>(0);

    // Send Increment message and await reply
    let new_value = actor_ref.ask(Increment(5)).await?;
    println!("New counter value: {}", new_value);

    Ok(())
}

Q6: How do I spawn an actor?

A6: To spawn an actor, you use the spawn function provided by rsActor:

let (actor_ref, join_handle) = spawn::<MyActor>(args);

This function returns a tuple containing:

  • An ActorRef<MyActor> which you can use to send messages to the actor.
  • A JoinHandle<ActorResult<MyActor>> which you can use to await the actor's completion and get its final state or error information.

The args parameter is of type MyActor::Args and will be passed to the actor's on_start method.

Q7: How do I send messages to an actor?

A7: rsActor provides several methods for sending messages to actors:

  1. ask: Send a message and await a reply.

    let result = actor_ref.ask(MyMessage).await?;

  2. ask_with_timeout: Send a message, await a reply with a specified timeout.

    let result = actor_ref.ask_with_timeout(MyMessage, Duration::from_secs(1)).await?;

  3. tell: Send a message without waiting for a reply (fire-and-forget).

    actor_ref.tell(MyMessage).await?;

  4. tell_with_timeout: Send a message without waiting for a reply, with a timeout.

    actor_ref.tell_with_timeout(MyMessage, Duration::from_secs(1)).await?;

  5. blocking_ask: Blocking version of ask for use from any thread (no runtime context required).

    // Without timeout (blocks indefinitely)
let result = actor_ref.blocking_ask(MyMessage, None)?;

// With timeout
let result = actor_ref.blocking_ask(MyMessage, Some(Duration::from_secs(5)))?;

  6. blocking_tell: Blocking version of tell for use from any thread (no runtime context required).

    // Without timeout (blocks indefinitely)
actor_ref.blocking_tell(MyMessage, None)?;

// With timeout
actor_ref.blocking_tell(MyMessage, Some(Duration::from_secs(5)))?;

Note: The ask_blocking and tell_blocking methods are deprecated since v0.10.0. Use blocking_ask and blocking_tell instead.

Q8: How do I stop an actor?

A8: To stop an actor, you can use:

  1. Graceful Stop:

    actor_ref.stop().await?;

    This sends a stop signal to the actor and waits for it to shut down cleanly. The actor will continue processing its current message, then call on_stop before terminating.

  2. Immediate Kill:

    actor_ref.kill();

    This abruptly stops the actor. The actor will not finish processing its current message, but will call on_stop(killed=true) before terminating.

  3. From within the actor: An actor can stop itself by calling actor_ref.stop() or actor_ref.kill() within its own methods.

Q9: How do I define message types?

A9: Message types in rsActor are just regular Rust types (structs or enums) that can carry the data needed for the actor to process the request. Message types should be Send + 'static to be safely sent across threads.

// Simple message with no data
struct Ping;

// Message with data
struct AddUser {
    id: u64,
    name: String,
    email: Option<String>,
}

// Enum message type
enum DatabaseCommand {
    Insert(Record),
    Delete(u64),
    Query(QueryParams),
}

Q10: How do I handle messages in an actor?

A10: There are two approaches to handle messages:

Recommended Approach: Using #[message_handlers] Macro

use rsactor::{Actor, ActorRef, message_handlers};

#[derive(Actor)]
struct UserManagerActor {
    users: std::collections::HashMap<u64, User>,
    next_id: u64,
}

#[message_handlers]
impl UserManagerActor {
    #[handler]
    async fn handle_add_user(&mut self, msg: AddUser, _: &ActorRef<Self>) -> Result<UserId, UserError> {
        let user = User {
            id: self.next_id,
            name: msg.name,
            email: msg.email,
        };

        self.next_id += 1;
        self.users.insert(user.id, user.clone());

        Ok(user.id)
    }

    #[handler]
    async fn handle_ping(&mut self, _msg: Ping, _: &ActorRef<Self>) -> String {
        "Pong".to_string()
    }
}

Manual Implementation: Using Message<T> Trait

impl Message<AddUser> for UserManagerActor {
    // Define what this message handler returns
    type Reply = Result<UserId, UserError>;

    // Implement the message handler
    async fn handle(&mut self, msg: AddUser, _actor_ref: &ActorRef<Self>) -> Self::Reply {
        let user = User {
            id: self.next_id,
            name: msg.name,
            email: msg.email,
        };

        self.next_id += 1;
        self.users.insert(user.id, user.clone());

        Ok(user.id)
    }
}

// Use macro to implement MessageHandler trait (deprecated approach)
impl_message_handler!(UserManagerActor, [Ping, AddUser, RemoveUser, GetUser]);

Then you must also use the impl_message_handler! macro to register all the message types your actor can handle:

impl_message_handler!(UserManagerActor, [Ping, AddUser, RemoveUser, GetUser]);

This macro implements the MessageHandler trait, which is what allows the actor runtime to dispatch messages to the appropriate handler methods.

Note: The #[message_handlers] approach is recommended as it automatically generates the Message<T> implementations and MessageHandler trait implementation, reducing boilerplate and potential errors.

Actor Lifecycle

Q11: What is the lifecycle of an actor?

A11: The lifecycle of an actor in rsActor follows these stages:

  1. Creation and Initialization:

    • Actor is spawned with arguments via spawn::<Actor>(args).
    • The framework calls on_start(args, actor_ref) to create the actor instance.
    • If on_start returns Ok(actor_instance), the actor enters the running state.
    • If on_start returns Err(e), the actor fails to start, and the JoinHandle resolves with an error.

  2. Running:

    • The actor processes messages from its mailbox.
    • The on_run idle handler is called when the message queue is empty.
    • This continues until the actor is stopped or encounters an error.

  3. Termination:

    • When the actor is stopping (either due to stop(), kill(), or an error), the framework calls on_stop(actor_ref, killed).
    • After on_stop completes, the actor is destroyed, and the JoinHandle is resolved with an ActorResult.

The actor's lifecycle methods are:

  • on_start(args: Self::Args, actor_ref: &ActorRef<Self>) -> Result<Self, Self::Error>: Called when the actor is starting. Creates and returns the actor instance.
  • on_run(&mut self, actor_weak: &ActorWeak<Self>) -> Result<bool, Self::Error>: Called when the message queue is empty (idle handler).
    • If on_run returns Ok(true), the actor continues calling on_run when idle.
    • If on_run returns Ok(false), idle processing is disabled; the actor only processes messages.
    • If on_run returns Err(e), the actor terminates due to a runtime error, resulting in ActorResult::Failed with phase: FailurePhase::OnRun.
  • on_stop(&mut self, actor_weak: &ActorWeak<Self>, killed: bool) -> Result<(), Self::Error>: Called when the actor is stopping (including after on_run errors). The killed parameter is true if the actor was killed, and false if it was stopped gracefully.

Q12: What is the ActorResult enum?

A12: The ActorResult enum represents the outcome of an actor's lifecycle when awaiting its JoinHandle. It has two variants:

  1. ActorResult::Completed:

    • Indicates that the actor completed successfully.
    • Contains the final actor state (actor: A) and a boolean killed indicating whether the actor was killed or stopped gracefully.
    • Returned when an actor is successfully stopped or killed.

  2. ActorResult::Failed:

    • Indicates that the actor failed during its lifecycle.
    • Contains the optional actor state (actor: Option<A>), the error that caused the failure (error: E), the phase in which the failure occurred (phase: FailurePhase), and a boolean killed indicating whether the actor was killed.
    • The FailurePhase can be OnStart, OnRun, or OnStop.

Q13: How do I handle errors in actors?

A13: Error handling in rsActor happens at several levels:

  • Lifecycle - on_start: If on_start returns Err(e), the actor never starts, and the JoinHandle will resolve to ActorResult::Failed { actor: None, error: e, phase: FailurePhase::OnStart, killed: false }. Since the actor wasn't created, the actor field is None.
  • Lifecycle - on_run: If on_run returns Err(e), the actor will terminate after calling on_stop for cleanup, and the JoinHandle will resolve to ActorResult::Failed { actor: Some(actor_state), error: e, phase: FailurePhase::OnRun, killed: false }. The actor field contains the actor's state.
  • Panics: If a message handler or on_run panics, the Tokio task hosting the actor will terminate. Awaiting the JoinHandle will then result in an Err (typically a tokio::task::JoinError indicating a panic). It's generally recommended to handle errors gracefully within your actor logic and return Result types from on_start and on_run, and use Result as reply types for messages where appropriate, rather than relying on panics.
  • Message Handling: For message handling, the Message<T>::handle method can return any type as its Reply, including a Result type. If your message handler might fail, it's a good practice to use a Result type as the Reply type.
  • Sending Messages: The methods for sending messages (ask, tell, etc.) return Result<R, rsactor::Error>, where R is the reply type of the message. These methods can fail if the actor has stopped, the mailbox is full, or a timeout occurs.

Advanced Usage

Q14: Can I use rsActor with blocking code?

A14: Yes, rsActor provides mechanisms for working with blocking code:

  1. Within Message Handlers: If a message handler needs to perform blocking operations, you can use tokio::task::spawn_blocking:

    impl Message<ProcessFile> for FileProcessorActor {
    type Reply = Result<Stats, FileError>;

    async fn handle(&mut self, msg: ProcessFile, _actor_ref: &ActorRef<Self>) -> Self::Reply {
        let file_path = msg.path.clone();
        let result = tokio::task::spawn_blocking(move || {
            // Perform blocking file operations
            process_file_synchronously(&file_path)
        }).await??; // Unwrap both the JoinError and the inner Result

        Ok(result)
    }
}

  2. Sending Messages from Blocking Contexts: If you need to send messages to actors from within a blocking context, use the blocking_ask and blocking_tell methods:

    tokio::task::spawn_blocking(move || {
    // Some blocking work...

    // Send message and get response, blocking until response is received
    let result = actor_ref.blocking_ask(
        Query { id: 123 },
        Some(Duration::from_secs(5))
    );

    // Process result...
});

Q15: How do I test actors?

A15: Testing actors can be done in several ways:

  1. Integration-style tests: Spawn the actor and interact with it directly:

    #[tokio::test]
async fn test_counter_actor() {
    let (actor_ref, _handle) = spawn::<CounterActor>(0);

    // Test increment
    let result = actor_ref.ask(Increment(5)).await.unwrap();
    assert_eq!(result, 5);

    // Test get count
    let count = actor_ref.ask(GetCount).await.unwrap();
    assert_eq!(count, 5);
}

  2. Test message handlers directly: You can instantiate your actor struct and call the Message trait's handle method directly by spawning a temporary actor:

    #[tokio::test]
async fn test_message_handlers() {
    // Spawn a real actor for testing
    let (actor_ref, _handle) = spawn::<CounterActor>(0);

    // Test increment handler via the actor
    let result = actor_ref.ask(Increment(5)).await.unwrap();
    assert_eq!(result, 5);

    // Test current count
    let count = actor_ref.ask(GetCount).await.unwrap();
    assert_eq!(count, 5);

    actor_ref.stop().await.unwrap();
}

  3. Test lifecycle methods: For testing lifecycle hooks, spawn the actor and observe behavior:

    #[tokio::test]
async fn test_lifecycle() {
    // Spawn actor - on_start is called automatically
    let (actor_ref, handle) = spawn::<CounterActor>(10); // Initial count = 10

    // Verify initialization worked
    let count = actor_ref.ask(GetCount).await.unwrap();
    assert_eq!(count, 10);

    // Stop actor gracefully - on_stop is called
    actor_ref.stop().await.unwrap();

    // Await handle to get ActorResult
    let result = handle.await.unwrap();
    assert!(result.is_completed());
}

Q16: Can I use custom error types?

A16: Yes, you can use any error type that implements Send + Debug + 'static as the Actor::Error type:

#[derive(Debug, thiserror::Error)]
enum MyActorError {
    #[error("Database error: {0}")]
    DbError(#[from] sqlx::Error),

    #[error("File not found: {0}")]
    FileNotFound(String),

    #[error("Network timeout")]
    NetworkTimeout,
}

struct MyActor {
    // ...
}

impl Actor for MyActor {
    type Args = Config;
    type Error = MyActorError;

    async fn on_start(args: Self::Args, _actor_ref: &ActorRef<Self>) -> Result<Self, Self::Error> {
        // ...
    }
}

Q17: How do I handle actor supervision?

A17: rsActor does not have a built-in supervision system like some other actor frameworks (e.g., Akka). However, you can implement a simple supervision pattern by:

  1. Monitoring the JoinHandle of child actors:

    // Spawn child actor
let (child_ref, child_handle) = spawn::<ChildActor>(child_args);

// Monitor the child's JoinHandle in another task
tokio::spawn(async move {
    match child_handle.await {
        Ok(ActorResult::Completed { .. }) => {
            // Child completed normally
        }
        Ok(ActorResult::Failed { error, .. }) => {
            // Child failed, take some action (e.g., restart)
            let (new_child_ref, new_child_handle) = spawn::<ChildActor>(child_args);
            // ...
        }
        Err(join_error) => {
            // Child panicked
        }
    }
});

  2. Creating a supervisor actor that manages child actors:

    struct SupervisorActor {
    children: HashMap<ActorId, ChildInfo>,
}

impl SupervisorActor {
    async fn spawn_child(&mut self, args: ChildArgs) -> Result<ActorRef<ChildActor>> {
        let (child_ref, child_handle) = spawn::<ChildActor>(args.clone());
        let child_id = child_ref.identity();

        // Monitor child in background task
        let supervisor_ref = self.self_ref.clone();
        tokio::spawn(async move {
            let result = child_handle.await;
            // Notify supervisor about child termination
            supervisor_ref.tell(ChildTerminated {
                id: child_id,
                result,
                args, // Keep args for possible restart
            }).await;
        });

        self.children.insert(child_id, ChildInfo { ref: child_ref.clone() });
        Ok(child_ref)
    }
}

Q18: How to communicate between actors?

A18: Actors communicate by sending messages to each other:

impl Message<ProcessOrder> for OrderProcessorActor {
    type Reply = Result<OrderStatus, OrderError>;

    async fn handle(&mut self, msg: ProcessOrder, _actor_ref: &ActorRef<Self>) -> Self::Reply {
        // Process order locally
        let order = self.validate_order(&msg.order)?;

        // Send message to another actor for inventory check
        let inventory_status = self.inventory_actor.ask(CheckInventory {
            items: order.items.clone(),
        }).await?;

        if !inventory_status.all_available {
            return Err(OrderError::ItemsOutOfStock(inventory_status.missing_items));
        }

        // Send message to payment actor
        let payment_result = self.payment_actor.ask(ProcessPayment {
            amount: order.total_amount,
            payment_method: msg.payment_method,
        }).await?;

        if let Err(e) = payment_result {
            return Err(OrderError::PaymentFailed(e));
        }

        // Update order status
        self.orders.insert(order.id, order.clone());

        Ok(OrderStatus::Completed(order))
    }
}

Q19: How do I implement request-response patterns?

A19: The request-response pattern is built into rsActor through the ask method and Message<T>::Reply type:

// Request message
struct GetUserDetails {
    user_id: UserId,
}

// Response is defined as the Reply type
impl Message<GetUserDetails> for UserManagerActor {
    type Reply = Result<UserDetails, UserError>;

    async fn handle(&mut self, msg: GetUserDetails, _actor_ref: &ActorRef<Self>) -> Self::Reply {
        match self.users.get(&msg.user_id) {
            Some(user) => Ok(UserDetails::from(user)),
            None => Err(UserError::UserNotFound(msg.user_id)),
        }
    }
}

// Client code:
async fn get_user_profile(
    user_manager: &ActorRef<UserManagerActor>,
    user_id: UserId,
) -> Result<UserDetails, Error> {
    let user_details = user_manager.ask(GetUserDetails { user_id }).await??;
    Ok(user_details)
}

Q20: How do I share actor references between actors?

A20: Actor references can be shared by passing them during actor creation or via messages:

  1. Via constructor arguments:

    struct CoordinatorActor {
    worker_actors: Vec<ActorRef<WorkerActor>>,
}

impl Actor for CoordinatorActor {
    type Args = Vec<ActorRef<WorkerActor>>;
    type Error = anyhow::Error;

    async fn on_start(workers: Self::Args, _actor_ref: &ActorRef<Self>) -> Result<Self, Self::Error> {
        Ok(CoordinatorActor {
            worker_actors: workers,
        })
    }
}

// Spawn workers first, then coordinator:
let worker_refs: Vec<_> = (0..5)
    .map(|i| spawn::<WorkerActor>(WorkerArgs { id: i }).0)
    .collect();

let (coordinator_ref, _) = spawn::<CoordinatorActor>(worker_refs);

  2. Via messages:

    struct RegisterWorker {
    worker: ActorRef<WorkerActor>,
}

impl Message<RegisterWorker> for CoordinatorActor {
    type Reply = ();

    async fn handle(&mut self, msg: RegisterWorker, _actor_ref: &ActorRef<Self>) -> Self::Reply {
        self.worker_actors.push(msg.worker);
    }
}

// Later, register a worker:
let (worker_ref, _) = spawn::<WorkerActor>(worker_args);
coordinator_ref.tell(RegisterWorker { worker: worker_ref }).await?;

Q21: Can I use generics with actors?

A21: Yes, you can define generic actors. Here's an example using both the recommended #[message_handlers] approach and the manual approach:

Recommended Approach: Using #[message_handlers] Macro

use rsactor::{Actor, ActorRef, message_handlers};
use std::fmt::Debug;

// Define a generic actor struct
#[derive(Debug)]
struct GenericActor<T: Send + Debug + Clone + 'static> {
    data: Option<T>,
}

// Implement the Actor trait for the generic actor
impl<T: Send + Debug + Clone + 'static> Actor for GenericActor<T> {
    type Args = Option<T>; // Initial value for data
    type Error = anyhow::Error;

    async fn on_start(args: Self::Args, _actor_ref: &ActorRef<Self>) -> Result<Self, Self::Error> {
        Ok(GenericActor { data: args })
    }
}

// Define message types
#[derive(Debug)]
struct SetValue<T: Send + Debug + 'static>(pub T);

#[derive(Debug, Clone, Copy)]
struct GetValue;

#[derive(Debug, Clone, Copy)]
struct ClearValue;

// Use message_handlers macro for generic actors
#[message_handlers]
impl<T: Send + Debug + Clone + 'static> GenericActor<T> {
    #[handler]
    async fn handle_set_value(&mut self, msg: SetValue<T>, _: &ActorRef<Self>) -> () {
        self.data = Some(msg.0);
    }

    #[handler]
    async fn handle_get_value(&mut self, _msg: GetValue, _: &ActorRef<Self>) -> Option<T> {
        self.data.clone()
    }

    #[handler]
    async fn handle_clear_value(&mut self, _msg: ClearValue, _: &ActorRef<Self>) -> () {
        self.data = None;
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Usage with String - works automatically!
    let (string_actor_ref, _s_handle) = spawn::<GenericActor<String>>(Some("hello".to_string()));
    string_actor_ref.tell(SetValue("world".to_string())).await?;
    let val_s: Option<String> = string_actor_ref.ask(GetValue).await?;
    println!("String actor value: {:?}", val_s); // Should be Some("world")

    // Usage with i32 - works automatically!
    let (int_actor_ref, _i_handle) = spawn::<GenericActor<i32>>(Some(42));
    int_actor_ref.tell(SetValue(100)).await?;
    let val_i: Option<i32> = int_actor_ref.ask(GetValue).await?;
    println!("Integer actor value: {:?}", val_i); // Should be Some(100)

    Ok(())
}

Manual Implementation: Using impl_message_handler! Macro

use rsactor::{Actor, ActorRef, Message, impl_message_handler, spawn, ActorResult};
use anyhow::Result;
use std::fmt::Debug;

// Define a generic actor struct
#[derive(Debug)]
struct GenericActor<T: Send + Debug + Clone + 'static> {
    data: Option<T>,
}

// Implement the Actor trait for the generic actor
impl<T: Send + Debug + Clone + 'static> Actor for GenericActor<T> {
    type Args = Option<T>; // Initial value for data
    type Error = anyhow::Error;

    async fn on_start(args: Self::Args, _actor_ref: &ActorRef<Self>) -> Result<Self, Self::Error> {
        Ok(GenericActor { data: args })
    }
}

// Define message types
// A generic message to set the value
#[derive(Debug)]
struct SetValue<T: Send + Debug + 'static>(pub T);

// A non-generic message to get the value
#[derive(Debug, Clone, Copy)]
struct GetValue;

// A message to clear the value
#[derive(Debug, Clone, Copy)]
struct ClearValue;

// Implement Message trait for SetValue<T>
impl<T: Send + Debug + Clone + 'static> Message<SetValue<T>> for GenericActor<T> {
    type Reply = ();

    async fn handle(&mut self, msg: SetValue<T>, _actor_ref: &ActorRef<Self>) -> Self::Reply {
        self.data = Some(msg.0);
    }
}

// Implement Message trait for GetValue
impl<T: Send + Debug + Clone + 'static> Message<GetValue> for GenericActor<T> {
    type Reply = Option<T>;

    async fn handle(&mut self, _msg: GetValue, _actor_ref: &ActorRef<Self>) -> Self::Reply {
        self.data.clone()
    }
}

// Implement Message trait for ClearValue
impl<T: Send + Debug + Clone + 'static> Message<ClearValue> for GenericActor<T> {
    type Reply = ();

    async fn handle(&mut self, _msg: ClearValue, _actor_ref: &ActorRef<Self>) -> Self::Reply {
        self.data = None;
    }
}

// ---- Unified Macro Usage for Generic Actors ----
// Use the unified syntax with generic constraints in square brackets
// This single macro call handles ALL generic instantiations of GenericActor<T>
impl_message_handler!([T: Send + Debug + Clone + 'static] for GenericActor<T>, [SetValue<T>, GetValue, ClearValue]);

/*
#[tokio::main]
async fn main() -> Result<()> {
    // Usage with String - no additional macro calls needed!
    let (string_actor_ref, _s_handle) = spawn::<GenericActor<String>>(Some("hello".to_string()));
    string_actor_ref.tell(SetValue("world".to_string())).await?;
    let val_s: Option<String> = string_actor_ref.ask(GetValue).await?;
    println!("String actor value: {:?}", val_s); // Should be Some("world")

    // Usage with i32 - works automatically!
    let (int_actor_ref, _i_handle) = spawn::<GenericActor<i32>>(Some(42));
    int_actor_ref.tell(SetValue(100)).await?;
    let val_i: Option<i32> = int_actor_ref.ask(GetValue).await?;
    println!("Integer actor value: {:?}", val_i); // Should be Some(100)

    // Clear the value
    int_actor_ref.tell(ClearValue).await?;
    let val_cleared: Option<i32> = int_actor_ref.ask(GetValue).await?;
    println!("Cleared value: {:?}", val_cleared); // Should be None

    Ok(())
}
*/

The #[message_handlers] macro automatically handles this for you, or you can use the deprecated impl_message_handler! macro which supports two syntax patterns:

  • Generic actors: impl_message_handler!([T: Send + Debug + Clone + 'static] for GenericActor<T>, [SetValue<T>, GetValue, ClearValue]);
  • Non-generic actors: impl_message_handler!(MyActor, [MessageType1, MessageType2]);

With the generic syntax, you specify the generic constraints in square brackets, followed by for and the generic actor type, then the list of message types. This single macro call generates message handling for all possible instantiations of the generic actor, eliminating the need for separate macro calls for each concrete type.

Note: The #[message_handlers] macro approach is recommended over impl_message_handler! as it provides better ergonomics and reduces boilerplate.

Q22: How can I effectively use the on_run method in my actors?

A22: The on_run method is an idle handler in the rsActor framework, called when the actor's message queue is empty. It returns Result<bool, Error> to control idle processing:

  • Ok(true) - Continue calling on_run when idle
  • Ok(false) - Disable idle processing; actor only processes messages
  • Err(e) - Terminate with an error

Here's how to use it effectively:

  • Idle Processing: The on_run method is called when there are no messages to process. Messages always have priority over idle processing, ensuring the actor stays responsive.

  • Periodic Tasks: You can implement periodic tasks by using tokio::time utilities within the on_run. For example:

    struct MyActor {
    // ... other fields ...
    fast_interval: tokio::time::Interval,
    slow_interval: tokio::time::Interval,
}

// Initialize intervals in on_start
async fn on_start(args: Self::Args, actor_ref: &ActorRef<Self>) -> Result<Self, Self::Error> {
    Ok(MyActor {
        // ... initialize other fields ...
        fast_interval: tokio::time::interval(std::time::Duration::from_millis(500)),
        slow_interval: tokio::time::interval(std::time::Duration::from_secs(5)),
    })
}

// Idle handler - called when message queue is empty
async fn on_run(&mut self, _: &ActorWeak<Self>) -> Result<bool, Self::Error> {
    tokio::select! {
        _ = self.fast_interval.tick() => {
            // Handle high-frequency tasks (every 500ms)
            self.process_high_frequency_work();
        }
        _ = self.slow_interval.tick() => {
            // Handle low-frequency tasks (every 5s)
            self.process_low_frequency_work();
        }
    }
    Ok(true) // Continue idle processing
}

  • Consuming Events: The on_run method is ideal for processing events from channels or streams:

    struct EventProcessorActor {
    events_rx: mpsc::Receiver<Event>,
}

impl Actor for EventProcessorActor {
    // ...

    async fn on_run(&mut self, _actor_weak: &ActorWeak<Self>) -> Result<bool, Self::Error> {
        tokio::select! {
            Some(event) = self.events_rx.recv() => {
                self.process_event(event)?;
                Ok(true) // Continue processing
            }
            else => {
                // Channel closed, stop idle processing
                Ok(false)
            }
        }
    }
}

  • Background Processing: Use on_run for background processing tasks:

    async fn on_run(&mut self, _actor_weak: &ActorWeak<Self>) -> Result<bool, Self::Error> {
    // Process one batch of work items
    if let Some(work_item) = self.queue.pop() {
        self.process_work_item(work_item)?;
        Ok(true) // Continue processing
    } else {
        // No work to do, disable idle processing until new work arrives via messages
        Ok(false)
    }
}

  • Combine multiple sources with tokio::select!: You can wait on multiple event sources concurrently:

    async fn on_run(&mut self, actor_weak: &ActorWeak<Self>) -> Result<bool, Self::Error> {
    tokio::select! {
        Some(msg) = self.command_rx.recv() => {
            self.handle_command(msg)?;
            Ok(true) // Continue
        }
        _ = self.health_check_interval.tick() => {
            self.perform_health_check()?;
            Ok(true) // Continue
        }
        else => {
            // All channels are closed, disable idle processing
            Ok(false)
        }
    }
}

Q23: How do I handle backpressure in actors?

A23: Backpressure is important to prevent overwhelming actors with more messages than they can process. rsActor provides several techniques:

  1. Mailbox Capacity: When spawning an actor, you can specify the mailbox size:

    let mailbox_capacity = 100;
let (actor_ref, handle) = spawn_with_mailbox_capacity::<MyActor>(args, mailbox_capacity);

    When the mailbox is full, ask and tell operations will return an error, allowing the sender to implement backpressure strategies.

  2. Rate Limiting: Implement rate limiting within the actor:

    struct RateLimitedActor {
    limiter: RateLimiter,
    // ...
}

impl Actor for RateLimitedActor {
    // ...

    async fn on_start(args: Self::Args, _actor_ref: &ActorRef<Self>) -> Result<Self, Self::Error> {
        Ok(Self {
            limiter: RateLimiter::new(args.rate),
            // ...
        })
    }
}

impl Message<ProcessRequest> for RateLimitedActor {
    type Reply = Result<Response, Error>;

    async fn handle(&mut self, msg: ProcessRequest, _actor_ref: &ActorRef<Self>) -> Self::Reply {
        // Wait for rate limiter to allow processing
        self.limiter.acquire_one().await;

        // Process the request
        self.process(msg)
    }
}

  3. Flow Control with Acknowledgments: Use explicit acknowledgments to implement flow control:

    // Sender side
for item in items {
    actor_ref.ask(ProcessItem { item }).await?;
    // Wait for acknowledgment before sending next item
}

// Actor side
impl Message<ProcessItem> for ProcessingActor {
    type Reply = ();

    async fn handle(&mut self, msg: ProcessItem, _actor_ref: &ActorRef<Self>) -> Self::Reply {
        self.process(msg.item);
        // Return empty acknowledgment
    }
}

  4. Batching: Process items in batches to reduce message overhead:

    // Instead of sending individual items:
actor_ref.ask(ProcessBatch { items: batch_of_items }).await?;

// Actor handles batches more efficiently:
impl Message<ProcessBatch> for BatchProcessorActor {
    type Reply = BatchResult;

    async fn handle(&mut self, msg: ProcessBatch, _actor_ref: &ActorRef<Self>) -> Self::Reply {
        // Process entire batch at once
        self.process_batch(msg.items)
    }
}

Q24: How does rsActor handle type safety for messages and actors?

A24: rsActor provides a comprehensive type safety system for actor messaging through two complementary approaches:

  1. Compile-time Type Safety with ActorRef<T>:

    • The primary actor reference type you'll use in most cases
    • Fully leverages Rust's type system for static verification
    • Only allows sending messages that the actor has explicitly implemented handlers for
    • Automatically infers and enforces correct return types based on message handler implementations
    • Compiler errors occur if you attempt to send an unhandled message type
    • Zero runtime overhead for type checking
    • Example: 
      // This will compile only if CounterActor implements Message<IncrementMsg>
let new_count: u32 = actor_ref.ask(IncrementMsg(5)).await?;

// This would be a compile-time error if CounterActor doesn't handle ResetMsg
actor_ref.tell(ResetMsg).await?;

  2. Type-Erased Actor Management with Traits:

    • ActorControl trait: Type-erased lifecycle management (stop, kill, is_alive)
    • TellHandler<M> / AskHandler<M, R>: Type-erased message sending for specific message types
    • Useful for storing different actor types in collections while maintaining message type safety
    • Example: 
      use rsactor::{ActorControl, TellHandler, AskHandler};

// Store different actor types with unified lifecycle control
let controls: Vec<Box<dyn ActorControl>> = vec![
    (&actor1).into(),
    (&actor2).into(),
];

// Stop all actors gracefully
for control in &controls {
    control.stop().await?;
}

// Or store handlers for specific message types
let handlers: Vec<Box<dyn TellHandler<PingMsg>>> = vec![
    (&actor1).into(),
    (&actor2).into(),
];

// Send same message to all actors that handle it
for handler in &handlers {
    handler.tell(PingMsg).await?;
}

The combination of compile-time type safety with ActorRef<T> and type-erased traits provides both safety and flexibility, making it suitable for a wide range of actor system designs.

This FAQ is based on the state of the rsActor project as of its README.md and src/lib.rs on May 25, 2025. Features and behaviors may change in future versions.