# Introduction
Welcome to the rsActor User Guide!
`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.
This guide will walk you through the core concepts, features, and usage patterns of `rsActor` to help you build robust and concurrent applications.
**Note:** This project is actively evolving. While core APIs are stable, some features may be refined in future releases.
## Core Features
* **Minimalist Actor System**: Focuses on core actor model primitives without unnecessary complexity.
* **Message Passing**: Comprehensive communication patterns (`ask`, `tell`, timeout variants, blocking versions).
* **Clean Lifecycle Management**: `on_start`, `on_run`, and `on_stop` hooks provide intuitive actor lifecycle control.
* **Graceful Termination**: Actors can be stopped gracefully or killed immediately, with differentiated cleanup via the `killed` parameter.
* **Rich Result Types**: `ActorResult` enum captures detailed completion states and error information.
* **Macro-Assisted Development**: `#[message_handlers]` and `#[derive(Actor)]` reduce boilerplate significantly.
* **Type Safety**: Compile-time type safety with `ActorRef<T>` prevents runtime type errors.
* **Handler Traits**: `TellHandler` and `AskHandler` enable type-erased message sending for heterogeneous actor collections.
* **Actor Control**: `ActorControl` trait provides type-erased lifecycle management.
* **Weak References**: `ActorWeak<T>` prevents circular dependencies without memory leaks.
* **Dead Letter Tracking**: Automatic logging of undelivered messages with structured tracing.
* **Optional Metrics**: Per-actor performance metrics (message count, processing time, error count) via the `metrics` feature.
* **Optional Tracing Instrumentation**: `#[tracing::instrument]` spans for observability via the `tracing` feature.
* **Minimal Constraints**: Only `Send` trait required for actor structs, enabling flexible internal state management.