async-actor 0.1.0

A simple actor framework for Rust
Documentation 
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
97

use crate::Actor;

use async_channel::{Sender as MultiSender, WeakSender as WeakMultiSender};
use async_oneshot_channel::{Sender as OneshotSender, WeakSender as WeakOneshotSender};

#[derive(Debug)]
/// A handle to an actor, that allows messages to be sent to the actor.
///
/// As long as one ActorRef exists, the actor will continue to run.
pub struct ActorRef<A: Actor> {
    pub(crate) sender: MultiSender<A::Message>,
    pub(crate) stop: OneshotSender<A::Message>,
}

impl<A: Actor> ActorRef<A> {
    /// Sends a message to the actor. If the mailbox is full, the message will be returned in [`Err`].
    pub async fn send(&self, msg: A::Message) -> Result<(), A::Message> {
        self.sender.send(msg).await.map_err(|e| e.0)
    }

    /// Stops the actor by sending a stop message to it. If a stop message has already been sent,
    /// the stop message will be returned in [`Err`].
    pub fn stop(&self, stop: A::Message) -> Result<(), A::Message> {
        self.stop.send(stop)
    }

    /// Creates a [`WeakActorRef`] from this [`ActorRef`], which can be used as a handle to the actor that
    /// doesn't keep the actor alive, if it is the last handle to the actor.
    pub fn downgrade(&self) -> WeakActorRef<A> {
        WeakActorRef {
            sender: self.sender.downgrade(),
            stop: self.stop.downgrade(),
        }
    }
}

impl<A: Actor> Clone for ActorRef<A> {
    fn clone(&self) -> Self {
        Self {
            sender: self.sender.clone(),
            stop: self.stop.clone(),
        }
    }
}

#[derive(Debug)]
/// A reference to an actor that allows messages to be sent to the actor.
///
/// If the actor has been dropped, this [`WeakActorRef`] will not be able to send messages to the actor,
/// and will not be able to be upgraded.
pub struct WeakActorRef<A: Actor> {
    sender: WeakMultiSender<A::Message>,
    stop: WeakOneshotSender<A::Message>,
}

impl<A: Actor> WeakActorRef<A> {
    /// Attempts to upgrade this [`WeakActorRef`] to an [`ActorRef`]. If the actor has been dropped,
    /// this will return [`None`].
    pub fn upgrade(&self) -> Option<ActorRef<A>> {
        Some(ActorRef {
            sender: self.sender.upgrade()?,
            stop: self.stop.upgrade()?,
        })
    }

    /// Sends a message to the actor. If the actor has been dropped, or the mailbox is full,
    /// the message will be returned in [`Err`].
    pub async fn send(&self, msg: A::Message) -> Result<(), A::Message> {
        match self.upgrade() {
            Some(actor_ref) => actor_ref.send(msg).await,
            None => Err(msg),
        }
    }

    /// Stops the actor by sending a stop message to it. If the actor has been dropped, or the mailbox is full,
    /// the stop message will be returned in [`Err`].
    pub fn stop(&self, stop: A::Message) -> Result<(), A::Message> {
        self.stop.send(stop)
    }
}

impl<A: Actor> Clone for WeakActorRef<A> {
    fn clone(&self) -> Self {
        Self {
            sender: self.sender.clone(),
            stop: self.stop.clone(),
        }
    }
}

impl<A: Actor> TryInto<ActorRef<A>> for WeakActorRef<A> {
    type Error = ();

    fn try_into(self) -> Result<ActorRef<A>, Self::Error> {
        self.upgrade().ok_or(())
    }
}