atomic_actor/lib.rs
1//! An `Actor` similar to `actix::Actor` but can handle `Message`s with `async`/`await`.
2//!
3//! This is an `Actor` implementation that mimics the API of `actix`, with several simplications for ease of use.
4//!
5//! # Example
6//!
7//! The primary purpose of this library is to enable `Handler`s to handle `Message`s with `async fn`:
8//!
9//! ```rust
10//! use async_trait::async_trait;
11//! use atomic_actor::*;
12//!
13//! struct I32Actor(i32);
14//!
15//! impl Actor for I32Actor {
16//! type Context = Context<Self>;
17//! }
18//!
19//! #[async_trait]
20//! impl Handler<Vec<i32>> for I32Actor {
21//! type Result = i32;
22//!
23//! async fn handle(&mut self, message: Vec<i32>, _: &mut Context<Self>) -> i32 {
24//! for value in message {
25//! async { self.0 += value }.await;
26//! }
27//! self.0
28//! }
29//! }
30//!
31//! #[tokio::main]
32//! async fn main() {
33//! let addr = I32Actor(0).start();
34//! assert_eq!(addr.send(vec![1, 2, 3]).unwrap().await, 6);
35//! }
36//! ```
37//!
38//! `actix` also allows asyncronous message handling through `ActorFuture` and friends.
39//! However, the returned `ActorFuture` can not reference the `Actor`, and only gets
40//! access to it on every poll, which prevents the use of `async` and `await` language features.
41//!
42//! # Differences from `actix`
43//!
44//! - `Handler::handle` is an `async fn`.
45//!
46//! For this to be sound, `Message`s sent to the same `Actor` must be processed sequentially, hence the name `atomic-actor`.
47//!
48//! - There's no `Message` trait. All types that are `'static + Send` can be used as `Message`s.
49//!
50//! - `Actor` has no lifecycle. Once started, it'll run until all `Addr`s are dropped.
51//!
52//! - `Context` is very simple, can only be used to get a new `Addr` of the actor.
53//!
54//! - Communication channel betwen `Addr` and the worker thread is unbounded. We may add option for using bounded channel in the future.
55
56mod actor;
57mod addr;
58mod context;
59mod handler;
60mod task;
61
62pub use actor::*;
63pub use addr::*;
64pub use context::*;
65pub use handler::*;