messaging/
lib.rs

1use std::sync::mpsc::{Receiver, RecvError, SendError, Sender, TryRecvError};
2
3///
4/// An object that has the ability to act as a two-way channel. This allows for two-way communications across threads, for example.
5///
6#[derive(Debug)]
7pub struct Mailbox<SenderMessage: Send + Sync, ReceiverMessage: Send + Sync> {
8    sender: Sender<SenderMessage>,
9    receiver: Receiver<ReceiverMessage>,
10}
11
12impl<MessageA: Send + Sync + 'static, MessageB: Send + Sync + 'static> Mailbox<MessageA, MessageB> {
13    ///
14    /// Creates a new pair of `Mailbox`s in the form of `(Mailbox<MessageA, MessageB>, Mailbox<MessageB, MessageA>)`
15    ///
16    /// # Example
17    /// ```rust
18    /// let (renderer_mailbox, game_mailbox) = Mailbox::new_entangled_pair();
19    ///
20    /// renderer_mailbox.send(RenderLoopMessage::SyncWithGame);
21    /// if let Ok(RenderLoopMessage::SyncWithGame) = game_mailbox.poll() {
22    ///     // ...
23    /// }
24    /// 
25    /// game_mailbox.send_and_wait(GameLoopMessage::SyncWithRender)?;
26    /// ```
27    ///
28    pub fn new_entangled_pair() -> (Mailbox<MessageA, MessageB>, Mailbox<MessageB, MessageA>) {
29        let (sender_a, receiver_a) = std::sync::mpsc::channel();
30        let (sender_b, receiver_b) = std::sync::mpsc::channel();
31
32        let mailbox_a = Mailbox::new(sender_a, receiver_b);
33        let mailbox_b = Mailbox::new(sender_b, receiver_a);
34
35        (mailbox_a, mailbox_b)
36    }
37}
38
39impl<SenderMessage: Send + Sync, ReceiverMessage: Send + Sync>
40    Mailbox<SenderMessage, ReceiverMessage>
41{
42    ///
43    /// Creates a new `Mailbox`. Since `new_entangled_pair()` exists, this is only exposed in case that doesn't cover your use case. Otherwise you should just use that method instead.
44    ///
45    /// # Example
46    /// ```rust
47    /// let (sender_a, receiver_a) = std::sync::mpsc::channel();
48    /// let (sender_b, receiver_b) = std::sync::mpsc::channel();
49    ///
50    /// let renderer_mailbox = Mailbox::new(sender_a, receiver_b);
51    /// let game_mailbox = Mailbox::new(sender_b, receiver_a);
52    ///
53    /// renderer_mailbox.send(RenderLoopMessage::SyncWithGame);
54    /// if let Ok(RenderLoopMessage::SyncWithGame) = game_mailbox.poll() {
55    ///     // ...
56    /// }
57    /// 
58    /// game_mailbox.send_and_wait(GameLoopMessage::SyncWithRender)?;
59    /// ```
60    ///
61    pub fn new(sender: Sender<SenderMessage>, receiver: Receiver<ReceiverMessage>) -> Self {
62        Self { sender, receiver }
63    }
64
65    ///
66    /// Sends a message through the held sender. Wrapper around `sender.send()`
67    /// 
68    pub fn send(&self, message: SenderMessage) -> Result<(), MessagingError<SenderMessage>> {
69        self.sender.send(message).map_err(MessagingError::from)
70    }
71
72    ///
73    /// Waits for a message from the held receiver. Wrapper around `receiver.recv()`
74    /// 
75    pub fn wait(&mut self) -> Result<ReceiverMessage, MessagingError<SenderMessage>> {
76        self.receiver.recv().map_err(MessagingError::from)
77    }
78
79    ///
80    /// Polls for a message from the held receiver, otherwise immediately returning. Wrapper around `receiver.try_recv()`
81    /// 
82    pub fn poll(&mut self) -> Result<ReceiverMessage, MessagingError<SenderMessage>> {
83        self.receiver.try_recv().map_err(MessagingError::from)
84    }
85
86    ///
87    /// Does a `send` and a `wait`. Good for syncing between two threads.
88    /// 
89    pub fn send_and_wait(&mut self, message: SenderMessage) -> Result<ReceiverMessage, MessagingError<SenderMessage>> {
90        self.send(message)?;
91        self.wait()
92    }
93}
94
95use thiserror::Error;
96
97#[derive(Error, Debug)]
98pub enum MessagingError<SenderMessage> {
99    #[error("{error}")]
100    SendError { #[from] error: SendError<SenderMessage> },
101    #[error("{error}")]
102    PollError { #[from] error: TryRecvError },
103    #[error("{error}")]
104    WaitError { #[from] error: RecvError },
105}
messaging/lib.rs

messaging/
lib.rs
