# Getting Started with rsActor
This guide will help you get started with rsActor, a lightweight, Tokio-based actor framework for Rust.
## Installation
Add rsActor to your `Cargo.toml`:
```toml
[dependencies]
rsactor = "0.12" # Check crates.io for the latest version
# Optional: Enable tracing support for detailed observability
# rsactor = { version = "0.12", features = ["tracing"] }
```
## Your First Actor
Let's create a simple counter actor that demonstrates the core concepts:
### Option A: Using the Actor Derive Macro (Recommended for Simple Actors)
```rust
use rsactor::{Actor, ActorRef, message_handlers, spawn};
// 1. Define message types
struct Increment;
struct GetCount;
// 2. Define your actor struct and derive Actor
#[derive(Actor)]
struct CounterActor {
count: u32,
}
// 3. Use the message_handlers macro for automatic message handling
#[message_handlers]
impl CounterActor {
#[handler]
async fn handle_increment(&mut self, _msg: Increment, _: &ActorRef<Self>) -> () {
self.count += 1;
}
#[handler]
async fn handle_get_count(&mut self, _msg: GetCount, _: &ActorRef<Self>) -> u32 {
self.count
}
}
// 4. Usage
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let actor = CounterActor { count: 0 };
let (actor_ref, _join_handle) = spawn::<CounterActor>(actor);
// Send messages to the actor
actor_ref.tell(Increment).await?;
let count = actor_ref.ask(GetCount).await?;
println!("Count: {}", count); // Prints: Count: 1
actor_ref.stop().await?;
Ok(())
}
```
### Option B: Manual Actor Implementation (for Complex Initialization)
For actors that need complex initialization logic:
```rust
use rsactor::{Actor, ActorRef, ActorWeak, message_handlers, spawn};
use anyhow::Result;
// Define actor struct
struct CounterActor {
count: u32,
name: String,
}
// Implement Actor trait for complex initialization
impl Actor for CounterActor {
type Args = (u32, String); // Tuple of initial count and name
type Error = anyhow::Error;
// on_start is required - this is where the actor instance is created
async fn on_start(args: Self::Args, actor_ref: &ActorRef<Self>) -> Result<Self, Self::Error> {
let (initial_count, name) = args;
println!("CounterActor '{}' (ID: {}) starting with count: {}",
name, actor_ref.identity(), initial_count);
Ok(CounterActor {
count: initial_count,
name,
})
}
// on_run is optional - idle handler called when message queue is empty
async fn on_run(&mut self, _actor_weak: &ActorWeak<Self>) -> Result<bool, Self::Error> {
// Called when there are no messages to process
tokio::time::sleep(std::time::Duration::from_secs(1)).await;
println!("Actor '{}' heartbeat - current count: {}", self.name, self.count);
Ok(true) // Return true to continue idle processing, false to disable it
}
// on_stop is optional - called when the actor is terminating
async fn on_stop(&mut self, actor_weak: &ActorWeak<Self>, killed: bool) -> Result<(), Self::Error> {
println!("Actor '{}' stopping (killed: {}), final count: {}",
self.name, killed, self.count);
Ok(())
}
}
// Define message types
struct IncrementMsg(u32);
struct GetCountMsg;
// Use message_handlers macro
#[message_handlers]
impl CounterActor {
#[handler]
async fn handle_increment(&mut self, msg: IncrementMsg, _: &ActorRef<Self>) -> u32 {
self.count += msg.0;
println!("Actor '{}' incremented by {}, new count: {}",
self.name, msg.0, self.count);
self.count
}
#[handler]
async fn handle_get_count(&mut self, _msg: GetCountMsg, _: &ActorRef<Self>) -> u32 {
self.count
}
}
#[tokio::main]
async fn main() -> Result<()> {
// Spawn actor with initialization arguments
let (actor_ref, join_handle) = spawn::<CounterActor>((10, "MyCounter".to_string()));
// Allow actor to run and emit heartbeats
tokio::time::sleep(std::time::Duration::from_millis(2500)).await;
// Send messages
let new_count = actor_ref.ask(IncrementMsg(5)).await?;
println!("Received count: {}", new_count);
let current_count = actor_ref.ask(GetCountMsg).await?;
println!("Current count: {}", current_count);
// Gracefully stop the actor
actor_ref.stop().await?;
// Wait for actor to complete and check the result
match join_handle.await? {
rsactor::ActorResult::Completed { actor, killed } => {
println!("Actor completed successfully. Final count: {}, killed: {}",
actor.count, killed);
}
rsactor::ActorResult::Failed { error, phase, .. } => {
println!("Actor failed during {:?}: {}", phase, error);
}
}
Ok(())
}
```
## Core Concepts
### Actor Lifecycle
1. **`on_start`** (required): Creates the actor instance from initialization arguments
2. **`on_run`** (optional): Idle handler called when message queue is empty, returns `bool` to control continuation
3. **`on_stop`** (optional): Cleanup logic when the actor terminates
### Message Passing
- **`tell`**: Fire-and-forget messaging
- **`ask`**: Request-reply messaging
- **`tell_with_timeout`/`ask_with_timeout`**: Variants with timeout support
- **`blocking_tell`/`blocking_ask`**: Blocking variants for use from any thread (no runtime context required)
### Actor Termination
- **`stop()`**: Graceful shutdown - processes remaining messages
- **`kill()`**: Immediate termination - stops processing immediately
### Type Safety
rsActor provides strong compile-time type safety:
```rust
// This will compile - CounterActor handles IncrementMsg
let count: u32 = actor_ref.ask(IncrementMsg(5)).await?;
// This will NOT compile - CounterActor doesn't handle this message type
// let result = actor_ref.ask("invalid message").await?; // Compile error!
```
## Next Steps
- Learn about [advanced features](./Architecture.md) like actor lifecycle management
- Explore [tracing support](./tracing.md) for production observability
- Check out the [examples](../examples/) directory for more complex use cases
- Read the [FAQ](./FAQ.md) for common questions and best practices
## Optional Features
### Tracing Support
Enable comprehensive observability:
```toml
[dependencies]
rsactor = { version = "0.12", features = ["tracing"] }
tracing-subscriber = "0.3"
```
Initialize tracing in your application:
```rust
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Initialize tracing
tracing_subscriber::fmt()
.with_max_level(tracing::Level::DEBUG)
.with_target(false)
.init();
// Your actor code here...
Ok(())
}
```
This provides detailed logs of actor lifecycle events, message handling, and performance metrics.
