acktor 1.0.11

Pure-Rust actor framework built on top of the Tokio async runtime
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
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

use std::pin::Pin;

use tokio::time::Duration;

use crate::actor::ActorId;
use crate::channel::oneshot::Receiver;
use crate::envelope::DefaultEnvelopeProxy;
use crate::errors::SendError;
use crate::message::Message;

#[cfg(feature = "type-erased-recipient-hook")]
use crate::actor::TypeErasedRecipient;

pub type SendResult<M> = Result<Receiver<<M as Message>::Result>, SendError<M>>;

pub type SendResultFuture<'a, M> = Pin<
    Box<dyn Future<Output = Result<Receiver<<M as Message>::Result>, SendError<M>>> + Send + 'a>,
>;

pub type DoSendResult<M> = Result<(), SendError<M>>;

pub type DoSendResultFuture<'a, M> =
    Pin<Box<dyn Future<Output = Result<(), SendError<M>>> + Send + 'a>>;

pub type ClosedResultFuture<'a> = Pin<Box<dyn Future<Output = ()> + Send + 'a>>;

/// Describes how to retrieve the index of a sender.
pub trait SenderId {
    /// Returns the index of the sender.
    fn index(&self) -> ActorId;

    /// Returns `true` if this sender refers to an actor in another process.
    ///
    /// The MSB of the ActorId is reserved by [`acktor-ipc`] crate to tag remote addresses.
    ///
    /// [`acktor-ipc`]: https://docs.rs/acktor-ipc/latest/acktor_ipc
    #[cfg(feature = "ipc")]
    #[cfg_attr(docsrs, doc(cfg(feature = "ipc")))]
    #[inline]
    fn is_remote(&self) -> bool {
        self.index() >> 63 != 0
    }
}

impl SenderId for ActorId {
    #[inline]
    fn index(&self) -> ActorId {
        *self
    }
}

/// Describes how to send a message.
pub trait Sender<M, EP = DefaultEnvelopeProxy<M>>: SenderId
where
    M: Message,
{
    /// Completes when the receiver has been closed.
    fn closed(&self) -> ClosedResultFuture<'_>;

    /// Checks if the channel has been closed.
    fn is_closed(&self) -> bool;

    /// Returns the current capacity of the channel.
    fn capacity(&self) -> usize;

    /// Sends a message, waiting until there is capacity, and returns a [`Receiver`] which can be
    /// used to receive the message response.
    fn send(&self, msg: M) -> SendResultFuture<'_, M>;

    /// Sends a message, waiting until there is capacity, without expecting a response.
    fn do_send(&self, msg: M) -> DoSendResultFuture<'_, M>;

    /// Attempts to immediately send a message and returns a [`Receiver`] which can be used to
    /// receive the message response.
    fn try_send(&self, msg: M) -> SendResult<M>;

    /// Attempts to immediately send a message without expecting a response.
    fn try_do_send(&self, msg: M) -> DoSendResult<M>;

    /// Sends a message, waiting until there is capacity, but only for a limited time, and returns
    /// a [`Receiver`] which can be used to receive the message response.
    fn send_timeout(&self, msg: M, timeout: Duration) -> SendResultFuture<'_, M>;

    /// Sends a message, waiting until there is capacity, but only for a limited time, without
    /// expecting a response.
    fn do_send_timeout(&self, msg: M, timeout: Duration) -> DoSendResultFuture<'_, M>;

    /// Blocking send to call outside of asynchronous contexts.
    ///
    /// This method is intended for use cases where you are sending from synchronous code to
    /// asynchronous code.
    ///
    /// # Panics
    ///
    /// This function panics if called within an asynchronous execution context.
    fn blocking_send(&self, msg: M) -> SendResult<M>;

    /// Blocking do_send to call outside of asynchronous contexts.
    ///
    /// This method is intended for use cases where you are sending from synchronous code to
    /// asynchronous code.
    ///
    /// # Panics
    ///
    /// This function panics if called within an asynchronous execution context.
    fn blocking_do_send(&self, msg: M) -> DoSendResult<M>;

    /// Returns a type-erased trait object which can be downcast into a concrete
    /// [`Recipient<M>`][super::recipient::Recipient], where `M` is a specific message type chosen
    /// by the user who overrides the
    /// [`Actor::type_erased_recipient_fn`][crate::actor::Actor::type_erased_recipient_fn] method.
    ///
    /// See [`Actor::type_erased_recipient_fn`][crate::actor::Actor::type_erased_recipient_fn] for
    /// details.
    #[cfg(feature = "type-erased-recipient-hook")]
    #[cfg_attr(docsrs, doc(cfg(feature = "type-erased-recipient-hook")))]
    fn type_erased_recipient(&self) -> Option<TypeErasedRecipient> {
        None
    }
}