acktor/
lib.rs

1//! A pure-Rust actor framework built on top of the [Tokio](https://tokio.rs) async runtime,
2//! inspired by [Actors with Tokio](https://ryhl.io/blog/actors-with-tokio/) by Alice Ryhl.
3//!
4//! `acktor` builds on the patterns described in Alice Ryhl's blog post and extends them into a
5//! structured library. Each actor runs as an independent `tokio` task with its own mailbox,
6//! processing messages one at a time. Actors communicate exclusively through message passing —
7//! there is no shared mutable state. The framework provides lifecycle hooks, supervision, an
8//! observer pattern, and support for periodic tasks.
9//!
10//! # Quick Start
11//!
12//! An example `Counter` actor that handles arithmetic messages might be the following:
13//!
14//! ```rust
15//! use acktor::{Actor, Context, Signal, message::{Handler, Message}};
16//!
17//! #[derive(Debug)]
18//! struct Counter(i64);
19//!
20//! impl Actor for Counter {
21//!     type Context = Context<Self>;
22//!     type Error = String;
23//! }
24//!
25//! #[derive(Debug)]
26//! enum CounterMsg {
27//!     Increment,
28//!     Get,
29//! }
30//!
31//! impl Message for CounterMsg {
32//!     type Result = i64;
33//! }
34//!
35//! impl Handler<CounterMsg> for Counter {
36//!     type Result = i64;
37//!
38//!     async fn handle(&mut self, msg: CounterMsg, _ctx: &mut Self::Context) -> i64 {
39//!         match msg {
40//!             CounterMsg::Increment => self.0 += 1,
41//!             CounterMsg::Get => {}
42//!         }
43//!         self.0
44//!     }
45//! }
46//!
47//! async fn run() {
48//!     let (addr, handle) = Counter(0).run("counter").unwrap();
49//!
50//!     // fire-and-forget
51//!     addr.do_send(CounterMsg::Increment).await.unwrap();
52//!
53//!     // request-reply
54//!     let result = addr.send(CounterMsg::Get).await.unwrap().await.unwrap();
55//!     println!("Counter: {result}"); // Counter: 1
56//!
57//!     addr.do_send(Signal::Stop).await.unwrap();
58//!     handle.await.unwrap();
59//! }
60//! ```
61
62#![cfg_attr(docsrs, feature(doc_cfg))]
63
64pub mod errors {
65    //! Re-exports some error types from tokio.
66
67    pub use tokio::sync::mpsc::error::{SendError, TryRecvError, TrySendError};
68}
69
70mod utils;
71
72mod actor;
73pub use actor::{Actor, ActorContext, ActorState, Stopping};
74
75mod context;
76pub use context::{Context, DEFAULT_MAILBOX_CAPACITY};
77
78pub mod address;
79pub mod envelope;
80pub mod message;
81
82pub mod cron;
83
84pub mod observer;
85pub mod supervisor;
86
87mod signal;
88pub use signal::Signal;
89
90#[cfg(feature = "derive")]
91#[cfg_attr(docsrs, doc(cfg(feature = "derive")))]
92pub mod derive {
93    //! Derive macros for defining messages and message responses.
94
95    /// Implements the [`Message`][crate::message::Message] trait for a type.
96    pub use acktor_derive::Message;
97
98    /// Implements the [`MessageResponse`][crate::message::MessageResponse] trait for a type.
99    pub use acktor_derive::MessageResponse;
100}
101
102pub mod report {
103    //! Error reporting macro.
104    //!
105    //! This module provides a macro to report errors and their sources in a recursive way.
106
107    pub use acktor_macros::report;
108}
109
110pub mod debug_trace {
111    //! Debug trace macro.
112
113    pub use acktor_macros::debug_trace;
114}
acktor/lib.rs

acktor/
lib.rs
