Struct MessageMailbox

pub struct MessageMailbox { /* private fields */ }

The MessageMailbox is a data structure holding all messages of a process.

If a Signal of type Message is received it will be taken from the Signal queue and put into this structure. The order of messages is preserved. This struct also implements the Future trait and pop() operations can be awaited on if the queue is empty.

Safety

This should be cancellation safe and can be used inside tokio::select! statements: https://docs.rs/tokio/1.10.0/tokio/macro.select.html#cancellation-safety

Implementations

impl MessageMailbox

pub async fn pop(&self, tags: Option<&[i64]>) -> Message

Return message in FIFO order from mailbox.

If function is called with a tags value different from None, it will only return the first message matching any of the tags.

If no message exist, blocks until a message is received.

pub async fn pop_skip_search(&self, tags: Option<&[i64]>) -> Message

Similar to pop, but will assume right away that no message with this tags exists.

Sometimes we know that the message we are waiting on can’t have a particular tags already in the queue, so we can save ourself a search through the queue. This is often the case in a request/response architecture where we sent the tags to the remote server but couldn’t have gotten it back yet.

Safety

It may not be clear right away why it’s safe to skip looking through the queue. If we are waiting on a reply, didn’t we already send the message and couldn’t it already have been received and pushed into our queue?

The way processes work is that they run a bit of code, stop, look for new signals/messages before running more code. This stop can only happen if there is an .await point in the code. Sending signals/messages is not an async task and we don’t need to .await on it. When using this function we need to make sure that sending a specific tag and waiting on it doesn’t contain any .await calls in-between. This implementation detail can be hidden inside of atomic host function calls so that end users don’t need to worry about it.

pub fn push(&self, message: Message)

Pushes a message into the mailbox.

If the message is being .awaited on, this call will immediately notify the waker that it’s ready, otherwise it will push it at the end of the queue.

pub fn len(&self) -> usize

Returns the number of messages currently available

pub fn is_empty(&self) -> bool

Returns true if the mailbox has no available messages

Trait Implementations

impl Clone for MessageMailbox

fn clone(&self) -> MessageMailbox

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for MessageMailbox

fn default() -> MessageMailbox

Returns the “default value” for a type.

impl Future for &MessageMailbox

type Output = Message

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.