actor12/
lib.rs

1//! # Actor12 Framework
2//!
3//! A lightweight, type-safe actor framework for Rust built on async/await.
4//!
5//! ## Overview
6//!
7//! Actor12 provides a simple yet powerful actor model implementation that leverages
8//! Rust's type system and async capabilities. Actors are isolated units of computation
9//! that communicate through message passing, ensuring thread safety and preventing
10//! data races.
11//!
12//! ## Key Features
13//!
14//! - **Type Safety**: Compile-time guarantees for message types and actor interactions
15//! - **Async/Await**: Built on Tokio for high-performance async execution
16//! - **Flexible Messaging**: Multiple patterns for different use cases
17//! - **Hierarchical Cancellation**: Clean shutdown and resource management
18//! - **Zero-Cost Abstractions**: Minimal runtime overhead
19//!
20//! ## Quick Start
21//!
22//! ```rust,no_run
23//! use actor12::prelude::*;
24//! use actor12::{spawn, Envelope, Multi, MpscChannel};
25//!
26//! // Define your actor
27//! struct Counter {
28//!     count: i32,
29//! }
30//!
31//! impl Actor for Counter {
32//!     type Message = Multi<Self>;
33//!     type Spec = ();
34//!     type Channel = MpscChannel<Self::Message>;
35//!     type Cancel = ();
36//!     type State = ();
37//!
38//!     fn state(_spec: &Self::Spec) -> Self::State {
39//!         ()
40//!     }
41//!
42//!     fn init(_ctx: Init<'_, Self>) -> impl std::future::Future<Output = Result<Self, Self::Cancel>> + Send + 'static {
43//!         std::future::ready(Ok(Counter { count: 0 }))
44//!     }
45//! }
46//!
47//! // Spawn the actor
48//! let link = spawn::<Counter>(());
49//! ```
50//!
51//! ## Architecture
52//!
53//! The framework is built around several core concepts:
54//!
55//! - [`Actor`]: The core trait defining actor behavior
56//! - [`Link`]: Strong reference to an actor for sending messages
57//! - [`Envelope`]: Type-safe message containers for request-response patterns
58//! - [`Handler`]: Trait for polymorphic message handling
59//! - [`Multi`]: Support for handling multiple message types in a single actor
60//!
61//! ## Examples
62//!
63//! See the `examples/` directory for comprehensive usage patterns including:
64//! - Basic request-response communication
65//! - State management
66//! - Multiple message types
67//! - Error handling
68//! - Worker pools
69
70mod actor;
71pub mod cancel;
72mod channel;
73pub mod count;
74mod drop;
75mod envelope;
76mod error;
77mod handler;
78mod link;
79mod multi;
80mod proxy;
81mod weak;
82
83/// Common imports for working with the Actor12 framework.
84///
85/// This module re-exports the most commonly used types and traits,
86/// allowing for convenient imports with `use actor12::prelude::*;`
87pub mod prelude {
88    pub use super::actor::Actor;
89    pub use super::actor::Init;
90    pub use super::actor::InitFuture;
91    pub use super::handler::Exec;
92    pub use super::handler::Handler;
93}
94
95pub use actor::Actor;
96pub use actor::ActorContext;
97pub use actor::Init;
98pub use channel::MpscChannel;
99pub use drop::DropHandle;
100pub use envelope::Envelope;
101pub use envelope::NoReply;
102pub use error::ActorError;
103pub use handler::Call;
104pub use handler::Exec;
105pub use handler::Handler;
106pub use link::DynLink;
107pub use link::Link;
108pub use multi::Multi;
109pub use proxy::Proxy;
110pub use weak::WeakLink;
111
112/// Spawn a new actor instance with the given specification.
113///
114/// This is a convenience function that delegates to the actor's associated
115/// `spawn` method, providing a unified interface for actor creation.
116///
117/// # Arguments
118///
119/// * `spec` - The specification required to initialize the actor
120///
121/// # Returns
122///
123/// A [`Link<A>`] that can be used to send messages to the spawned actor.
124///
125/// # Examples
126///
127/// ```rust,no_run
128/// use actor12::{spawn, Actor, Init, Exec, MpscChannel, Multi};
129///
130/// struct MyActor;
131///
132/// impl Actor for MyActor {
133///     type Message = Multi<Self>;
134///     type Spec = ();
135///     type Channel = MpscChannel<Self::Message>;
136///     type Cancel = ();
137///     type State = ();
138///
139///     fn state(_spec: &Self::Spec) -> Self::State {
140///         ()
141///     }
142///
143///     fn init(_ctx: Init<'_, Self>) -> impl std::future::Future<Output = Result<Self, Self::Cancel>> + Send + 'static {
144///         std::future::ready(Ok(MyActor))
145///     }
146/// }
147///
148/// // Spawn the actor
149/// let link = spawn::<MyActor>(());
150/// ```
151pub fn spawn<A: Actor>(spec: A::Spec) -> Link<A> {
152    A::spawn(spec)
153}
actor12/lib.rs

actor12/
lib.rs
