# 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)
```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
let result = actor_ref.blocking_ask(MyMessage, None)?;
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
actor_ref.blocking_tell(MyMessage, None)?;
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**:
```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 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.
```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_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`:
```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 || {
process_file_synchronously(&file_path)
}).await??;
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 || {
let result = actor_ref.blocking_ask(
Query { id: 123 },
Some(Duration::from_secs(5))
);
});
```
**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);
let result = actor_ref.ask(Increment(5)).await.unwrap();
assert_eq!(result, 5);
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() {
let (actor_ref, _handle) = spawn::<CounterActor>(0);
let result = actor_ref.ask(Increment(5)).await.unwrap();
assert_eq!(result, 5);
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:
```rust
#[tokio::test]
async fn test_lifecycle() {
let (actor_ref, handle) = spawn::<CounterActor>(10);
let count = actor_ref.ask(GetCount).await.unwrap();
assert_eq!(count, 10);
actor_ref.stop().await.unwrap();
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
let (child_ref, child_handle) = spawn::<ChildActor>(child_args);
tokio::spawn(async move {
match child_handle.await {
Ok(ActorResult::Completed { .. }) => {
}
Ok(ActorResult::Failed { error, .. }) => {
let (new_child_ref, new_child_handle) = spawn::<ChildActor>(child_args);
}
Err(join_error) => {
}
}
});
```
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();
let supervisor_ref = self.self_ref.clone();
tokio::spawn(async move {
let result = child_handle.await;
supervisor_ref.tell(ChildTerminated {
id: child_id,
result,
args, }).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,
})
}
}
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);
}
}
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_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:
```rust
struct MyActor {
fast_interval: tokio::time::Interval,
slow_interval: tokio::time::Interval,
}
async fn on_start(args: Self::Args, actor_ref: &ActorRef<Self>) -> Result<Self, Self::Error> {
Ok(MyActor {
fast_interval: tokio::time::interval(std::time::Duration::from_millis(500)),
slow_interval: tokio::time::interval(std::time::Duration::from_secs(5)),
})
}
async fn on_run(&mut self, _: &ActorWeak<Self>) -> Result<bool, Self::Error> {
tokio::select! {
_ = self.fast_interval.tick() => {
self.process_high_frequency_work();
}
_ = self.slow_interval.tick() => {
self.process_low_frequency_work();
}
}
Ok(true) }
```
* **Consuming Events:** The `on_run` method is ideal for processing events from channels or streams:
```rust
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) }
else => {
Ok(false)
}
}
}
}
```
* **Background Processing:** Use `on_run` for background processing tasks:
```rust
async fn on_run(&mut self, _actor_weak: &ActorWeak<Self>) -> Result<bool, Self::Error> {
if let Some(work_item) = self.queue.pop() {
self.process_work_item(work_item)?;
Ok(true) } else {
Ok(false)
}
}
```
* **Combine multiple sources with `tokio::select!`:** You can wait on multiple event sources concurrently:
```rust
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) }
_ = self.health_check_interval.tick() => {
self.perform_health_check()?;
Ok(true) }
else => {
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:
```rust
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:
```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 {
self.limiter.acquire_one().await;
self.process(msg)
}
}
```
3. **Flow Control with Acknowledgments**:
Use explicit acknowledgments to implement flow control:
```rust
for item in items {
actor_ref.ask(ProcessItem { item }).await?;
}
impl Message<ProcessItem> for ProcessingActor {
type Reply = ();
async fn handle(&mut self, msg: ProcessItem, _actor_ref: &ActorRef<Self>) -> Self::Reply {
self.process(msg.item);
}
}
```
4. **Batching**:
Process items in batches to reduce message overhead:
```rust
actor_ref.ask(ProcessBatch { items: batch_of_items }).await?;
impl Message<ProcessBatch> for BatchProcessorActor {
type Reply = BatchResult;
async fn handle(&mut self, msg: ProcessBatch, _actor_ref: &ActorRef<Self>) -> Self::Reply {
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
let new_count: u32 = actor_ref.ask(IncrementMsg(5)).await?;
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};
let controls: Vec<Box<dyn ActorControl>> = vec![
(&actor1).into(),
(&actor2).into(),
];
for control in &controls {
control.stop().await?;
}
let handlers: Vec<Box<dyn TellHandler<PingMsg>>> = vec![
(&actor1).into(),
(&actor2).into(),
];
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.*
