tyra/lib.rs
1//! Tyra is a [configurable](./prelude/struct.TyraConfig.html) typed actor framework
2//!
3//! An [Actor](./prelude/trait.Actor.html) is an object with which you can only interact by sending predefined [messages](./prelude/trait.ActorMessage.html)
4//!
5//! Furthermore Actors are bound to a thread pool and can be moved between executions to any of the threads of said pool.
6//!
7//! [crossbeam-channel](https://github.com/crossbeam-rs/crossbeam) and [flume](https://github.com/zesterer/flume) are used for all internal-messaging
8//!
9//! # Examples
10//!
11//! Basic usage:
12//!
13//! ```rust
14//! use tyra::prelude::*;
15//! use std::process::exit;
16//! use std::time::Duration;
17//! use std::error::Error;
18//!
19//! // define message
20//! struct FooBar {}
21//! impl ActorMessage for FooBar {}
22//!
23//! // define actor
24//! struct HelloWorld {}
25//! impl Actor for HelloWorld {}
26//!
27//! // setup required Factory
28//! struct HelloWorldFactory {}
29//! impl ActorFactory<HelloWorld> for HelloWorldFactory {
30//! fn new_actor(&mut self, _context: ActorContext<HelloWorld>) -> Result<HelloWorld, Box<dyn Error>> {
31//! Ok(HelloWorld {})
32//! }
33//! }
34//!
35//! // each supported message has its own Handler implementation
36//! // this is where the actual work is done
37//! impl Handler<FooBar> for HelloWorld {
38//! fn handle(&mut self, _msg: FooBar, _context: &ActorContext<Self>) -> Result<ActorResult, Box<dyn Error>> {
39//! println!("Message Received!");
40//! Ok(ActorResult::Ok)
41//! }
42//! }
43//!
44//! fn main() {
45//! // create a new actor system with the default config
46//! let actor_config = TyraConfig::new().unwrap();
47//! let actor_system = ActorSystem::new(actor_config);
48//!
49//! // create an actor and send it a message
50//! let factory = HelloWorldFactory {};
51//! let actor = actor_system
52//! .builder()
53//! .spawn("hello-world", factory)
54//! .unwrap();
55//! actor.send(FooBar {}).unwrap();
56//!
57//! // cleanup
58//! actor.stop().unwrap();
59//! actor_system.stop(Duration::from_millis(5000));
60//! exit(actor_system.await_shutdown());
61//! }
62//! ```
63//!
64//! # Architecture
65//!
66//! ## User POV
67//!
68//! ```text
69//! ┌──────────────────────┐
70//! │ │
71//! │ TyraConfig │
72//! │ │
73//! └──────────┬───────────┘
74//! │
75//! ┌───────▼───────┐
76//! │ │
77//! ┌────────────────┤ ActorSystem ├─────────────────┐
78//! │ │ │ │
79//! │ └───────┬───────┘ │
80//! │ │ │
81//! ┌────────▼─────────┐ ┌────────▼─────────┐ ┌─────────▼────────┐
82//! │ │ │ │ │ │
83//! │ ActorBuilder A │ │ ActorBuilder B │ │ ActorBuilder N │
84//! │ │ │ │ │ │
85//! └┬─────────────────┘ └┬─────────────────┘ └┬─────────────────┘
86//! │ │ │
87//! │ ┌────────────┐ │ ┌────────────┐ │ ┌────────────┐
88//! │ │ │ │ │ │ │ │ │
89//! ├─► Actor A1 │ ├──► Actor B1 │ ├──► Actor N1 │
90//! │ │ │ │ │ │ │ │ │
91//! │ └────────────┘ │ └────────────┘ │ └────────────┘
92//! │ │ │
93//! │ ┌────────────┐ │ ┌────────────┐ │ ┌────────────┐
94//! │ │ │ │ │ │ │ │ │
95//! ├─► Actor A2 │ ├──► Actor B2 │ ├──► Actor N2 │
96//! │ │ │ │ │ │ │ │ │
97//! │ └────────────┘ │ └────────────┘ │ └────────────┘
98//! │ │ │
99//! │ ┌────────────┐ │ ┌────────────┐ │ ┌────────────┐
100//! │ │ │ │ │ │ │ │ │
101//! └─► Actor An │ └──► Actor Bn │ └──► Actor Nn │
102//! │ │ │ │ │ │
103//! └────────────┘ └────────────┘ └────────────┘
104//!
105//! ```
106//!
107mod actor;
108mod config;
109mod message;
110mod routers;
111mod system;
112
113/// core components
114pub mod prelude {
115 pub use crate::actor::prelude::*;
116 pub use crate::config::prelude::*;
117 pub use crate::message::prelude::*;
118 pub use crate::system::prelude::*;
119}
120
121/// collection of different router implementations
122pub mod router {
123 pub use crate::routers::prelude::*;
124}