tyractorsaur/actor/
actor.rs

1use crate::message::serialized_message::SerializedMessage;
2use std::panic::UnwindSafe;
3
4/// Core trait to define Actors
5///
6///
7/// # Guaranteed Execution Order
8///
9/// 1. [ActorFactory.new_actor](../prelude/trait.ActorFactory.html#tymethod.new_actor)
10/// 2. [pre_start](../prelude/trait.Actor.html#method.pre_start)
11/// 3. Start processing [Handler Implementations](../prelude/trait.Handler.html#tymethod.handle)
12/// 4. [on_actor_stop](../prelude/trait.Actor.html#method.on_actor_stop)
13/// 5. Stops accepting new messages, but will continue to work through all existing Messages in Mailbox
14/// 6. [post_stop](../prelude/trait.Actor.html#method.post_stop)
15///
16/// # Examples
17///
18/// Basic usage:
19///
20/// ```rust
21/// use tyractorsaur::prelude::{TyractorsaurConfig, ActorSystem, Actor, ActorFactory, ActorContext, SerializedMessage};
22///
23/// struct TestActor {}
24///
25/// impl Actor for TestActor {}
26/// ```
27///
28/// # Architecture
29///
30/// ## Actor Lifecycle
31///
32/// ```text
33///                                 ┌──────────────────────────┐
34///                                 │                          │
35///                                 │                          │
36///                          ┌──────▼──────┐                   │
37///                          │             │                   │
38///                          │  new_actor  │                   │
39///                          │             │                   │
40///                          └──────┬──────┘                   │
41///                                 │                          │
42///                          ┌──────▼──────┐                   │
43///                          │             │                   │
44///                          │  pre_start  │                   │
45///                          │             │                   │
46///                          └──────┬──────┘                   │
47///                                 │                          │
48///                       ┌─────────▼─────────┐                │
49///                       │                   ◄─────┐          │
50///                       │  handle messages  │     │loop      │panic &&
51///                       │                   ├─────┘          │
52///                       └──┬──────┬─────┬──▲┘                │RestartPolicy == Always
53///                          │      │     │  │                 │
54///                          │      │     │  │                 │
55///                          │      │     │  │                 │
56///         ┌────────────────▼┐     │    ┌▼──┴──────────────┐  │
57///         │                 │     │    │                  │  │
58///         │  on_actor_stop  │     │    │  on_system_stop  │  │
59///         │                 │     │    │                  │  │
60///         └────┬────────────┘     │    └──────────────────┘  │
61///              │                  │                          │
62///              │                  │                          │
63///              │                  │                          │
64///              │                  │panic                     │
65/// ┌────────────▼───────┐          │                          │
66/// │                    │   ┌──────▼──────┐                   │
67/// │  handle remaining  │   │             │                   │
68/// │                    ├───►  post_stop  │                   │
69/// │      messages      │   │             │                   │
70/// │                    │   └──────┬──────┘                   │
71/// └────────────────────┘          │                          │
72///                                 │                          │
73///                                 │                          │
74///                                 └──────────────────────────┘
75/// ```
76pub trait Actor: Send + Sync + UnwindSafe {
77    /// executed before the first message is handled
78    ///
79    /// re-executed after actor restart before first message is handled
80    fn pre_start(&mut self) {}
81    /// executed after the last message is handled
82    ///
83    /// also executed in case the actor panics while it handles a message
84    fn post_stop(&mut self) {}
85    /// executed when Actor handles internal ActorStopMessage
86    ///
87    /// After this is called, the Actor will not accept any more messages, but messages within the mailbox will still be processed
88    fn on_actor_stop(&mut self) {}
89    /// executed when Actor handles internal SystemStopMessage initiated by [ActorSystem.stop](../prelude/struct.ActorSystem.html#method.stop)
90    ///
91    /// Without any custom implementation, the [ActorSystem.stop](../prelude/struct.ActorSystem.html#method.stop) will always end in timeout
92    fn on_system_stop(&mut self) {}
93    /// executed when [ActorSystem.send_to_address](../prelude/struct.ActorSystem.html#method.send_to_address) is called
94    ///
95    /// # Important Note
96    ///
97    /// This is the only function that is not necessarily executed on the thread_pool of the Actor
98    /// It is executed on whatever thread calls [ActorSystem.send_to_address](../prelude/struct.ActorSystem.html#method.send_to_address)
99    fn handle_serialized_message(&self, _msg: SerializedMessage) {}
100}
tyractorsaur/actor/actor.rs

tyractorsaur/actor/
actor.rs
