<!-- filepath: /Volumes/Workspace/rust/rsactor/docs/FAQ.md -->
# 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`, optional `on_idle`, 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_idle` 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)
```rust
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
```rust
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`:
```rust
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.
```rust
let result = actor_ref.ask(MyMessage).await?;
```
2. **`ask_with_timeout`**: Send a message, await a reply with a specified timeout.
```rust
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).
```rust
actor_ref.tell(MyMessage).await?;
```
4. **`tell_with_timeout`**: Send a message without waiting for a reply, with a timeout.
```rust
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).
```rust
// 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).
```rust
// Without timeout (blocks indefinitely)
actor_ref.blocking_tell(MyMessage, None)?;
// With timeout
actor_ref.blocking_tell(MyMessage, Some(Duration::from_secs(5)))?;
```
**Note:** The earlier `ask_blocking` / `tell_blocking` methods have been removed. Use `blocking_ask` / `blocking_tell` instead.
**Q8: How do I stop an actor?**
A8: To stop an actor, you can use:
1. **Graceful Stop**:
```rust
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**:
```rust
actor_ref.kill();
```
This drops any messages still queued in the mailbox and terminates as soon as the actor returns to its message loop, calling `on_stop(killed=true)` before terminating. It is **cooperative, not preemptive**: a handler (or `on_idle`) that is *already running* finishes first — `kill()` cannot interrupt an in-flight `.await`, so a handler blocked forever blocks `kill()` too. See **Q: When should I use the priority channel vs the regular mailbox vs `kill()`?** for how to guard against hangs (timeouts, the `deadlock-detection` feature, isolating blocking work).
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.
```rust
// 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
```rust
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
```rust
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:
```rust
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_idle` handler is called for each event yielded by a `Stream` registered via `ActorRef::subscribe_idle`, but only while the mailbox is empty. Messages always have priority over idle events.
* 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_idle(&mut self, event: Self::IdleEvent, actor_weak: &ActorWeak<Self>) -> Result<(), Self::Error>`: Called for each event yielded by a `Stream` registered via `ActorRef::subscribe_idle`, but only while the mailbox is empty.
* Requires the associated type `Actor::IdleEvent` (set to `()` when there is no idle work; `#[derive(Actor)]` fills this in automatically).
* Requires the idle channel to be enabled at spawn time via `SpawnOptions::new().with_idle()`. Without it, `subscribe_idle` returns `Error::IdleChannelNotEnabled` and `on_idle` is never called. Check at runtime with `actor_ref.has_idle_channel()`.
* If `on_idle` returns `Err(e)`, the actor terminates due to a runtime error, resulting in `ActorResult::Failed` with `phase: FailurePhase::OnIdle`.
* `on_stop(&mut self, actor_weak: &ActorWeak<Self>, killed: bool) -> Result<(), Self::Error>`: Called when the actor is stopping (including after `on_idle` 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`), an optional secondary error (`secondary_error: Option<E>`, the `on_stop` cleanup error when the phase is `OnIdleThenOnStop`), the phase in which the failure occurred (`phase: FailurePhase`), and a boolean `killed` indicating whether the actor was killed.
* The `FailurePhase` can be `OnStart`, `OnIdle`, `OnStop`, or `OnIdleThenOnStop`.
**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, secondary_error: None, phase: FailurePhase::OnStart, killed: false }`. Since the actor wasn't created, the `actor` field is `None`.
* **Lifecycle - `on_idle`:** If `on_idle` 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, secondary_error: None, phase: FailurePhase::OnIdle, killed: false }`. The `actor` field contains the actor's state.
* **Panics:** If a message handler or `on_idle` 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_idle`, 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
**Q: When should I use the priority channel vs the regular mailbox vs `kill()`?**
A: Use this decision tree:
| Need | Use |
| -------------------------------------------------------------- | ---------------------------- |
| Normal application messages (any volume) | `tell` / `ask` |
| **Short, infrequent** control-plane messages that must skip a backed-up mailbox (health checks, pause/resume, config reload, dynamic feature toggles) | `tell_priority` / `ask_priority` |
| Tear the actor down right now, dropping pending work | `kill()` |
| Tear the actor down, but finish what's already queued | `stop()` |
The priority channel is **opt-in**: you must spawn the actor with
`spawn_with_options(args, SpawnOptions::new().with_priority())`. Default
`spawn()` and `spawn_with_mailbox_capacity()` do **not** create the priority
channel — calling `tell_priority` on such an actor returns
`Error::PriorityChannelNotEnabled` (a configuration error; not recorded as a
dead letter). Check at runtime with `actor_ref.has_priority_channel()`.
A few important properties:
- **Capacity is fixed at 1.** The priority channel exists to serialize "short
and rare" signals, not to stream traffic. The slot is freed the instant the
actor calls `recv()`, so admission resumes immediately at the next
`select!` iteration. The reply channel for `ask_priority` is a separate
`oneshot`, so the single mpsc slot does not bottleneck `ask_priority`
concurrency.
- **`Duration` is mandatory.** A wedged actor would otherwise block the
sender indefinitely. The timeout fires admission failures predictably and
records a dead letter (`DeadLetterReason::Timeout`).
- **Priority < kill.** `kill()` still wins biased select against the
priority channel, so a kill is delivered even when the priority slot is
full.
- **`stop()` drains the priority queue first.** Before `on_stop` runs, the
priority receiver is closed (refusing new sends) and any in-flight
priority message is processed. So a priority message sent immediately
before `stop()` is not lost. `kill()` does **not** drain.
- **Starvation is your responsibility.** The priority branch is biased above
the regular mailbox, so a flood of priority messages will starve regular
handlers. Reserve the priority channel for short, infrequent signals; the
`metrics` feature exposes `priority_message_count` separately from
`message_count` so you can detect abuse.
See `examples/priority_signal.rs` for a worked example with health checks
and pause/resume signals.
**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`:
```rust
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:
```rust
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:
```rust
#[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:
```rust
#[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;
}
```
3. **Test lifecycle methods**:
For testing lifecycle hooks, spawn the actor and observe behavior:
```rust
#[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;
// 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:
```rust
#[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:
```rust
// 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:
```rust
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:
```rust
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:
```rust
// 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**:
```rust
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**:
```rust
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
```rust
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
```rust
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_idle` method in my actors?**
A22: The `on_idle` method is an idle handler in the `rsActor` framework. Instead of being polled in a loop, it is driven by `Stream`s you register with `ActorRef::subscribe_idle`. The runtime drives those streams and calls `on_idle` once for each event they yield, but only while the mailbox is empty — messages always have priority over idle events, ensuring the actor stays responsive. The handler returns `Result<(), Error>`; returning `Err(e)` terminates the actor with `phase: FailurePhase::OnIdle`.
To use `on_idle` you must:
* Declare the associated type `Actor::IdleEvent`, the type of event the streams yield. Set it to `()` when there is no idle work; `#[derive(Actor)]` fills it in as `()` automatically.
* Enable the idle channel at spawn time, since it is **opt-in**: spawn with `spawn_with_options(args, SpawnOptions::new().with_idle())`. Without `with_idle()`, `subscribe_idle` returns `Error::IdleChannelNotEnabled` and `on_idle` is never called. Check at runtime with `actor_ref.has_idle_channel()`.
* Register one or more streams with `actor_ref.subscribe_idle(stream)`, typically in `on_start` (it is also valid from message handlers). Map each stream's items to your `IdleEvent` type.
Here's how to use it effectively:
* **Periodic Tasks:** Subscribe interval streams that yield tick events. Each tick is delivered to `on_idle` only while the mailbox is empty:
```rust
use futures::stream::StreamExt;
use tokio_stream::wrappers::IntervalStream;
use std::time::Duration;
#[derive(Debug, Clone, Copy)]
enum Tick {
Fast,
Slow,
}
struct MyActor {
// ... other fields ...
}
impl Actor for MyActor {
type Args = ();
type Error = anyhow::Error;
type IdleEvent = Tick;
// Subscribe periodic streams in on_start
async fn on_start(_args: Self::Args, actor_ref: &ActorRef<Self>) -> Result<Self, Self::Error> {
actor_ref.subscribe_idle(
IntervalStream::new(tokio::time::interval(Duration::from_millis(500)))
.map(|_| Tick::Fast),
)?;
actor_ref.subscribe_idle(
IntervalStream::new(tokio::time::interval(Duration::from_secs(5)))
.map(|_| Tick::Slow),
)?;
Ok(MyActor { /* ... initialize fields ... */ })
}
// Idle handler - called for each yielded event while the mailbox is empty
async fn on_idle(&mut self, event: Tick, _actor_weak: &ActorWeak<Self>) -> Result<(), Self::Error> {
match event {
Tick::Fast => self.process_high_frequency_work(), // every 500ms
Tick::Slow => self.process_low_frequency_work(), // every 5s
}
Ok(())
}
}
```
* **Consuming Events:** Subscribe a stream wrapping a channel or other event source and handle each item in `on_idle`. Do not loop inside a single `on_idle` call — return after handling one event and the runtime will call you again for the next:
```rust
use futures::stream::StreamExt;
use tokio_stream::wrappers::ReceiverStream;
struct EventProcessorActor {
// ... other fields ...
}
impl Actor for EventProcessorActor {
type Args = mpsc::Receiver<Event>;
type Error = anyhow::Error;
type IdleEvent = Event;
async fn on_start(events_rx: Self::Args, actor_ref: &ActorRef<Self>) -> Result<Self, Self::Error> {
actor_ref.subscribe_idle(ReceiverStream::new(events_rx))?;
Ok(EventProcessorActor { /* ... */ })
}
async fn on_idle(&mut self, event: Event, _actor_weak: &ActorWeak<Self>) -> Result<(), Self::Error> {
self.process_event(event)?;
Ok(())
}
}
```
* **Background Processing:** Map a stream to a unit event and drain a work queue one item per call. Returning `Ok(())` lets the runtime deliver the next event:
```rust
async fn on_idle(&mut self, _event: (), _actor_weak: &ActorWeak<Self>) -> Result<(), Self::Error> {
// Process one batch of work items per call
if let Some(work_item) = self.queue.pop() {
self.process_work_item(work_item)?;
}
Ok(())
}
```
* **Combine multiple sources:** Subscribe several streams, each mapped to a variant of a shared `IdleEvent` enum. The runtime merges them and dispatches each yielded event to `on_idle`:
```rust
#[derive(Debug)]
enum IdleEvent {
Command(Command),
HealthCheck,
}
async fn on_start(_args: Self::Args, actor_ref: &ActorRef<Self>) -> Result<Self, Self::Error> {
actor_ref.subscribe_idle(command_stream.map(IdleEvent::Command))?;
actor_ref.subscribe_idle(
IntervalStream::new(tokio::time::interval(Duration::from_secs(10)))
.map(|_| IdleEvent::HealthCheck),
)?;
Ok(Self { /* ... */ })
}
async fn on_idle(&mut self, event: IdleEvent, _actor_weak: &ActorWeak<Self>) -> Result<(), Self::Error> {
match event {
IdleEvent::Command(cmd) => self.handle_command(cmd)?,
IdleEvent::HealthCheck => self.perform_health_check()?,
}
Ok(())
}
```
**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:
```rust
let mailbox_capacity = 100;
let (actor_ref, handle) = spawn_with_mailbox_capacity::<MyActor>(args, mailbox_capacity);
```
When the mailbox is full, the no-timeout `tell` and `ask` operations **wait for space** (admission) rather than returning an error — the bounded mailbox applies backpressure by suspending the sender. To get error-based backpressure, use `tell_with_timeout` / `ask_with_timeout` (which fail with `Error::Timeout` when admission doesn't complete in time) or the priority variants (whose timeout is mandatory).
⚠️ **Never issue a no-timeout `tell`/`stop` to the actor's own `ActorRef` from inside one of its handlers when the mailbox may be full.** The only consumer of the mailbox is the actor's own loop, which is parked awaiting that handler — the wait can never be satisfied and `kill()` cannot interrupt it. Use `tell_with_timeout`, enlarge the mailbox, or send from a spawned task. (With the `deadlock-detection` feature enabled, this situation panics immediately instead of hanging; a full-mailbox self-`ask` is likewise detected.)
2. **Rate Limiting**:
Implement rate limiting within the actor:
```rust
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:
```rust
// 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:
```rust
// 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:
```rust
// 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:
```rust
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.*
