Struct lunatic::Mailbox

pub struct Mailbox<M, S = Bincode, L = ()>where
    S: Serializer<M>,{ /* private fields */ }

The mailbox of a Process.

Each process in lunatic gets one dedicated mailbox. Messages sent to the process will end up in this mailbox. Each Process and Mailbox pair have matching message and serializer types, because of this de/serialization should never fail.

One case where deserialization might fail is when the Mailbox type is used on a function inside an external WebAssembly module that is loaded by WasmModule. In this case we don’t have any compile-time information about what messages are going to be received by this mailbox. For such cases the function try_receive can be used. It will not panic in case it can’t deserialize the message buffer.

Message ordering

Lunatic guarantees that messages sent between two processes will arrive in the same order they were sent. Ordering is not guaranteed if more than two processes are involved.

Link deaths

By default, if a linked process fails all the links will die too. This behavior can be changed by using the catch_link_failure function. The returned Mailbox<_, _, Catching> will receive a special MailboxResult::LinkDied in its mailbox containing the Tag used when the process was spawned (spawn_link_tag).

Implementations

impl<M, S> Mailbox<M, S, ()>where
    S: Serializer<M>,

pub fn receive(&self) -> M

Gets next message from process’ mailbox.

If the mailbox is empty, this function will block until a new message arrives.

Panics

This function will panic if the received message can’t be deserialized into M with serializer S.

pub fn tag_receive(&self, tags: &[Tag]) -> M

Gets next message from process’ mailbox that is tagged with one of the tags.

If no such message exists, this function will block until a new message arrives. If tags is an empty array, it will behave the same as receive.

Panics

This function will panic if the received message can’t be deserialized into M with serializer S.

pub fn catch_link_failure(self) -> Mailbox<M, S, Catching>

Allow this mailbox to catch link failures.

This function returns a Mailbox that will get MailboxResult::LinkDied messages every time a linked process dies.

impl<M, S> Mailbox<M, S, Catching>where
    S: Serializer<M>,

A mailbox that is catching dead links.

pub fn receive(&self) -> MailboxResult<M>

Gets next message from process’ mailbox.

If the mailbox is empty, this function will block until a new message arrives.

A message indicating that a linked process died is returned as MailboxResult::LinkDied with the Tag used to spawn the linked process.

pub fn tag_receive(&self, tags: &[Tag]) -> MailboxResult<M>

Gets next message from process’ mailbox that is tagged with one of the tags.

If no such message exists, this function will block until a new message arrives. If tags is an empty array, it will behave the same as receive.

This function can also be used to await the death of specific linked processes. In this case the tags array should contain tags corresponding to the processes we are awaiting to die.

impl<M, S, L> Mailbox<M, S, L>where
    S: Serializer<M>,

pub fn this(&self) -> Process<M, S>

Returns a reference to the currently running process

pub fn try_receive(&self, timeout: Duration) -> MailboxResult<M>

Same as receive, but doesn’t panic in case the deserialization fails. Instead, it will return MailboxResult::DeserializationFailed.

pub fn receive_timeout(&self, timeout: Duration) -> MailboxResult<M>

Same as receive, but only waits for the duration of timeout for the message. If the timeout expires it will return MailboxResult::TimedOut.

pub fn tag_receive_timeout(
    &self,
    tags: &[Tag],
    timeout: Duration
) -> MailboxResult<M>

Same as tag_receive, but only waits for the duration of timeout for the message. If the timeout expires it will return MailboxResult::TimedOut.

pub unsafe fn new() -> Self

Create a mailbox with a specific type.

Safety

It’s not safe to mix different types of mailboxes inside one process. This function should never be used directly. The only reason it’s public is that it’s used inside the main macro and needs to be available outside this crate.

Trait Implementations

impl<M, S, L> Clone for Mailbox<M, S, L>where
    S: Serializer<M>,

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<M, S, L> Debug for Mailbox<M, S, L>where
    S: Serializer<M>,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<M, S, L> Copy for Mailbox<M, S, L>where
    S: Serializer<M>,