async_actor/
actor.rs

1use either::Either;
2use std::future::Future;
3
4use crate::{ActorRef, ActorRun, Mailbox, WeakActorRef};
5
6pub trait Actor: Send + Sized + 'static {
7    type Error: Send;
8    type Message: Send;
9
10    #[allow(unused_variables)]
11    /// Called when the actor is started, and before any messages are processed.
12    /// Useful for initialization/setup logic that should run in the same async
13    /// context as the actor, and not in the Actor struct's constructor.
14    ///
15    /// `this` is a [`WeakActorRef`], which can be used to send
16    /// messages to itself, or to stop itself. As this is a weak reference, the
17    /// actor may have already been dropped by external code, so it may not be
18    /// possible to use the weak reference.
19    fn on_start(
20        &mut self,
21        this: &WeakActorRef<Self>,
22    ) -> impl Future<Output = Result<(), Self::Error>> + Send {
23        async { Ok(()) }
24    }
25
26    /// Called when a message is received by the actor. This is where the
27    /// actor's main logic should be implemented.
28    ///
29    /// `this` is a [`WeakActorRef`], which can be used to send
30    /// messages to itself, or to stop itself. As this is a weak reference, the
31    /// actor may have already been dropped by external code, so it may not be
32    /// possible to use the weak reference.
33    fn on_msg(
34        &mut self,
35        this: &WeakActorRef<Self>,
36        msg: Self::Message,
37    ) -> impl Future<Output = Result<(), Self::Error>> + Send;
38
39    #[allow(unused_variables)]
40    /// Called when the actor is stopped. This is the place to perform any
41    /// cleanup logic, such as closing connections, etc. This method is called
42    /// after the actor has received a stop message, or after the last [`ActorRef`]
43    /// to the actor is dropped.
44    ///
45    /// If the actor is stopped by dropping the last [`ActorRef`] to it, `stop` is [`None`].
46    /// Otherwise, `stop` contains the stop message that was sent to the actor.
47    fn on_stop(
48        &mut self,
49        stop: Option<Self::Message>,
50    ) -> impl Future<Output = Result<(), Self::Error>> + Send {
51        async { Ok(()) }
52    }
53
54    /// Runs the actor with the given mailbox. Unless you have a specific reason to,
55    /// the default implementation of this method should be used. You should not need to
56    /// call this method directly either, see [`Actor::into_future`] instead.
57    fn run_with(
58        &mut self,
59        mailbox: Mailbox<Self>,
60    ) -> impl Future<Output = Result<(), Self::Error>> + Send {
61        async move {
62            let this = mailbox.this.clone();
63            self.on_start(&this).await?;
64
65            loop {
66                match mailbox.recv().await {
67                    Either::Left(stop) => {
68                        mailbox.receiver.close();
69                        // Consume all remaining messages in the mailbox
70                        while let Ok(msg) = mailbox.receiver.recv().await {
71                            self.on_msg(&this, msg).await?;
72                        }
73                        self.on_stop(stop).await?;
74                        break Ok(());
75                    }
76                    Either::Right(msg) => {
77                        if let Some(msg) = msg {
78                            self.on_msg(&this, msg).await?;
79                        } else {
80                            self.on_stop(None).await?;
81                            break Ok(());
82                        }
83                    }
84                }
85            }
86        }
87    }
88
89    /// Creates a future that runs the actor, and returns an [`ActorRef`] to the actor.
90    ///
91    /// `mailbox_size` is the size of the mailbox used by the actor. If `None`, the mailbox
92    /// will be unbounded.
93    fn into_future(self, mailbox_size: Option<usize>) -> (ActorRef<Self>, ActorRun<Self>) {
94        ActorRun::new(self, mailbox_size)
95    }
96}
async_actor/actor.rs

async_actor/
actor.rs
