actor12 0.0.9

A lightweight actor framework for Rust with async support
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

//! # Actor12 Framework
//!
//! A lightweight, type-safe actor framework for Rust built on async/await.
//!
//! ## Overview
//!
//! Actor12 provides a simple yet powerful actor model implementation that leverages
//! Rust's type system and async capabilities. Actors are isolated units of computation
//! that communicate through message passing, ensuring thread safety and preventing
//! data races.
//!
//! ## Key Features
//!
//! - **Type Safety**: Compile-time guarantees for message types and actor interactions
//! - **Async/Await**: Built on Tokio for high-performance async execution
//! - **Flexible Messaging**: Multiple patterns for different use cases
//! - **Hierarchical Cancellation**: Clean shutdown and resource management
//! - **Zero-Cost Abstractions**: Minimal runtime overhead
//!
//! ## Quick Start
//!
//! ```rust,no_run
//! use actor12::prelude::*;
//! use actor12::{spawn, Envelope, Multi, MpscChannel};
//!
//! // Define your actor
//! struct Counter {
//!     count: i32,
//! }
//!
//! impl Actor for Counter {
//!     type Message = Multi<Self>;
//!     type Spec = ();
//!     type Channel = MpscChannel<Self::Message>;
//!     type Cancel = ();
//!     type State = ();
//!
//!     fn state(_spec: &Self::Spec) -> Self::State {
//!         ()
//!     }
//!
//!     fn init(_ctx: Init<'_, Self>) -> impl std::future::Future<Output = Result<Self, Self::Cancel>> + Send + 'static {
//!         std::future::ready(Ok(Counter { count: 0 }))
//!     }
//! }
//!
//! // Spawn the actor
//! let link = spawn::<Counter>(());
//! ```
//!
//! ## Architecture
//!
//! The framework is built around several core concepts:
//!
//! - [`Actor`]: The core trait defining actor behavior
//! - [`Link`]: Strong reference to an actor for sending messages
//! - [`Envelope`]: Type-safe message containers for request-response patterns
//! - [`Handler`]: Trait for polymorphic message handling
//! - [`Multi`]: Support for handling multiple message types in a single actor
//!
//! ## Examples
//!
//! See the `examples/` directory for comprehensive usage patterns including:
//! - Basic request-response communication
//! - State management
//! - Multiple message types
//! - Error handling
//! - Worker pools

mod actor;
pub mod cancel;
mod channel;
pub mod count;
mod drop;
mod envelope;
mod error;
mod handler;
mod link;
mod multi;
mod proxy;
mod weak;

/// Common imports for working with the Actor12 framework.
///
/// This module re-exports the most commonly used types and traits,
/// allowing for convenient imports with `use actor12::prelude::*;`
pub mod prelude {
    pub use super::actor::Actor;
    pub use super::actor::Init;
    pub use super::actor::InitFuture;
    pub use super::handler::Exec;
    pub use super::handler::Handler;
}

pub use actor::Actor;
pub use actor::ActorContext;
pub use actor::Init;
pub use channel::MpscChannel;
pub use drop::DropHandle;
pub use envelope::Envelope;
pub use envelope::NoReply;
pub use error::ActorError;
pub use handler::Call;
pub use handler::Exec;
pub use handler::Handler;
pub use link::DynLink;
pub use link::Link;
pub use multi::Multi;
pub use proxy::Proxy;
pub use weak::WeakLink;

/// Spawn a new actor instance with the given specification.
///
/// This is a convenience function that delegates to the actor's associated
/// `spawn` method, providing a unified interface for actor creation.
///
/// # Arguments
///
/// * `spec` - The specification required to initialize the actor
///
/// # Returns
///
/// A [`Link<A>`] that can be used to send messages to the spawned actor.
///
/// # Examples
///
/// ```rust,no_run
/// use actor12::{spawn, Actor, Init, Exec, MpscChannel, Multi};
///
/// struct MyActor;
///
/// impl Actor for MyActor {
///     type Message = Multi<Self>;
///     type Spec = ();
///     type Channel = MpscChannel<Self::Message>;
///     type Cancel = ();
///     type State = ();
///
///     fn state(_spec: &Self::Spec) -> Self::State {
///         ()
///     }
///
///     fn init(_ctx: Init<'_, Self>) -> impl std::future::Future<Output = Result<Self, Self::Cancel>> + Send + 'static {
///         std::future::ready(Ok(MyActor))
///     }
/// }
///
/// // Spawn the actor
/// let link = spawn::<MyActor>(());
/// ```
pub fn spawn<A: Actor>(spec: A::Spec) -> Link<A> {
    A::spawn(spec)
}