openraft-rt 0.10.0-alpha.30

Async runtime abstraction traits for Openraft
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

//! Bounded MPSC channel traits.

mod send_error;
mod try_recv_error;

use std::future::Future;

pub use send_error::SendError;
pub use try_recv_error::TryRecvError;

use crate::OptionalSend;
use crate::OptionalSync;

/// Multi-producer, single-consumer channel.
pub trait Mpsc: Sized + OptionalSend {
    /// The sender type for this MPSC channel.
    type Sender<T: OptionalSend>: MpscSender<Self, T>;
    /// The receiver type for this MPSC channel.
    type Receiver<T: OptionalSend>: MpscReceiver<T>;
    /// The weak sender type for this MPSC channel.
    type WeakSender<T: OptionalSend>: MpscWeakSender<Self, T>;

    /// Creates a bounded mpsc channel for communicating between asynchronous tasks with
    /// backpressure.
    #[track_caller]
    fn channel<T: OptionalSend>(buffer: usize) -> (Self::Sender<T>, Self::Receiver<T>);
}

/// Send values to the associated [`MpscReceiver`].
pub trait MpscSender<MU, T>: OptionalSend + OptionalSync + Clone
where
    MU: Mpsc,
    T: OptionalSend,
{
    /// Attempts to send a message, blocks if there is no capacity.
    ///
    /// If the receiving half of the channel is closed, this
    /// function returns an error. The error includes the value passed to `send`.
    #[track_caller]
    fn send(&self, msg: T) -> impl Future<Output = Result<(), SendError<T>>> + OptionalSend;

    /// Converts the [`MpscSender`] to a [`MpscWeakSender`] that does not count
    /// towards RAII semantics, i.e., if all `Sender` instances of the
    /// channel were dropped and only `WeakSender` instances remain,
    /// the channel is closed.
    #[track_caller]
    fn downgrade(&self) -> MU::WeakSender<T>;
}

/// Receive values from the associated [`MpscSender`].
pub trait MpscReceiver<T>: OptionalSend + OptionalSync {
    /// Receives the next value for this receiver.
    ///
    /// This method returns `None` if the channel has been closed and there are
    /// no remaining messages in the channel's buffer.
    #[track_caller]
    fn recv(&mut self) -> impl Future<Output = Option<T>> + OptionalSend;

    /// Tries to receive the next value for this receiver.
    ///
    /// This method returns the [`TryRecvError::Empty`] error if the channel is currently
    /// empty, but there are still outstanding senders.
    ///
    /// This method returns the [`TryRecvError::Disconnected`] error if the channel is
    /// currently empty, and there are no outstanding senders.
    #[track_caller]
    fn try_recv(&mut self) -> Result<T, TryRecvError>;
}

/// A sender that does not prevent the channel from being closed.
///
/// If all [`MpscSender`] instances of a channel were dropped and only
/// `WeakSender` instances remain, the channel is closed.
pub trait MpscWeakSender<MU, T>: OptionalSend + OptionalSync + Clone
where
    MU: Mpsc,
    T: OptionalSend,
{
    /// Tries to convert a [`MpscWeakSender`] into an [`MpscSender`].
    ///
    /// This will return `Some` if there are other `Sender` instances alive and
    /// the channel wasn't previously dropped, otherwise `None` is returned.
    #[track_caller]
    fn upgrade(&self) -> Option<MU::Sender<T>>;
}