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
use either::Either;
use std::future::Future;
use crate::{ActorRef, ActorRun, Mailbox, WeakActorRef};
pub trait Actor: Send + Sized + 'static {
type Error: Send;
type Message: Send;
#[allow(unused_variables)]
/// Called when the actor is started, and before any messages are processed.
/// Useful for initialization/setup logic that should run in the same async
/// context as the actor, and not in the Actor struct's constructor.
///
/// `this` is a [`WeakActorRef`], which can be used to send
/// messages to itself, or to stop itself. As this is a weak reference, the
/// actor may have already been dropped by external code, so it may not be
/// possible to use the weak reference.
fn on_start(
&mut self,
this: &WeakActorRef<Self>,
) -> impl Future<Output = Result<(), Self::Error>> + Send {
async { Ok(()) }
}
/// Called when a message is received by the actor. This is where the
/// actor's main logic should be implemented.
///
/// `this` is a [`WeakActorRef`], which can be used to send
/// messages to itself, or to stop itself. As this is a weak reference, the
/// actor may have already been dropped by external code, so it may not be
/// possible to use the weak reference.
fn on_msg(
&mut self,
this: &WeakActorRef<Self>,
msg: Self::Message,
) -> impl Future<Output = Result<(), Self::Error>> + Send;
#[allow(unused_variables)]
/// Called when the actor is stopped. This is the place to perform any
/// cleanup logic, such as closing connections, etc. This method is called
/// after the actor has received a stop message, or after the last [`ActorRef`]
/// to the actor is dropped.
///
/// If the actor is stopped by dropping the last [`ActorRef`] to it, `stop` is [`None`].
/// Otherwise, `stop` contains the stop message that was sent to the actor.
fn on_stop(
&mut self,
stop: Option<Self::Message>,
) -> impl Future<Output = Result<(), Self::Error>> + Send {
async { Ok(()) }
}
/// Runs the actor with the given mailbox. Unless you have a specific reason to,
/// the default implementation of this method should be used. You should not need to
/// call this method directly either, see [`Actor::into_future`] instead.
fn run_with(
&mut self,
mailbox: Mailbox<Self>,
) -> impl Future<Output = Result<(), Self::Error>> + Send {
async move {
let this = mailbox.this.clone();
self.on_start(&this).await?;
loop {
match mailbox.recv().await {
Either::Left(stop) => {
mailbox.receiver.close();
// Consume all remaining messages in the mailbox
while let Ok(msg) = mailbox.receiver.recv().await {
self.on_msg(&this, msg).await?;
}
self.on_stop(stop).await?;
break Ok(());
}
Either::Right(msg) => {
if let Some(msg) = msg {
self.on_msg(&this, msg).await?;
} else {
self.on_stop(None).await?;
break Ok(());
}
}
}
}
}
}
/// Creates a future that runs the actor, and returns an [`ActorRef`] to the actor.
///
/// `mailbox_size` is the size of the mailbox used by the actor. If `None`, the mailbox
/// will be unbounded.
fn into_future(self, mailbox_size: Option<usize>) -> (ActorRef<Self>, ActorRun<Self>) {
ActorRun::new(self, mailbox_size)
}
}