pub struct Mailbox<M, S = Bincode, L = ()>where
S: CanSerialize<M>,{ /* private fields */ }
Expand description
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
[MailboxError::LinkDied
] in its mailbox containing the Tag
used when
the process was spawned (spawn_link_tag
).
Implementations§
source§impl<M, S> Mailbox<M, S, ()>where
S: CanSerialize<M>,
impl<M, S> Mailbox<M, S, ()>where S: CanSerialize<M>,
sourcepub fn receive(&self) -> 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
.
sourcepub fn tag_receive(&self, tags: &[Tag]) -> M
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
.
sourcepub fn try_receive(&self) -> Result<M, MailboxError>
pub fn try_receive(&self) -> Result<M, MailboxError>
Same as receive
, but doesn’t panic in case the deserialization fails.
Instead, it will return MailboxError::DeserializationFailed
.
sourcepub fn receive_timeout(&self, timeout: Duration) -> Result<M, MailboxError>
pub fn receive_timeout(&self, timeout: Duration) -> Result<M, MailboxError>
Same as receive
, but only waits for the duration of timeout for the
message. If the timeout expires it will return
MailboxError::TimedOut
.
sourcepub fn tag_receive_timeout(
&self,
tags: &[Tag],
timeout: Duration
) -> Result<M, MailboxError>
pub fn tag_receive_timeout( &self, tags: &[Tag], timeout: Duration ) -> Result<M, MailboxError>
Same as tag_receive
, but only waits for the duration of timeout for
the message. If the timeout expires it will return
MailboxError::TimedOut
.
sourcepub fn catch_link_failure(self) -> Mailbox<M, S, LinkDiedSignal>
pub fn catch_link_failure(self) -> Mailbox<M, S, LinkDiedSignal>
Allow this mailbox to catch link failures.
This function returns a Mailbox
that will get a
LinkDiedSignal
message every time a linked process dies.
sourcepub fn monitorable(self) -> Mailbox<M, S, ProcessDiedSignal>
pub fn monitorable(self) -> Mailbox<M, S, ProcessDiedSignal>
Allows this mailbox to monitor other processes.
This function returns a Mailbox
that will get a ProcessDiedSignal
message
whenever a monitored process dies.
source§impl<M, S> Mailbox<M, S, LinkDiedSignal>where
S: CanSerialize<M>,
impl<M, S> Mailbox<M, S, LinkDiedSignal>where S: CanSerialize<M>,
sourcepub fn receive(&self) -> MessageSignal<M, LinkDiedSignal>
pub fn receive(&self) -> MessageSignal<M, LinkDiedSignal>
Gets next message or signal 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
.
sourcepub fn try_receive(&self) -> MailboxResult<M, LinkDiedSignal>
pub fn try_receive(&self) -> MailboxResult<M, LinkDiedSignal>
Same as receive
, but doesn’t panic in case the deserialization fails.
Instead, it will return MailboxError::DeserializationFailed
.
sourcepub fn tag_receive(&self, tags: &[Tag]) -> MessageSignal<M, LinkDiedSignal>
pub fn tag_receive(&self, tags: &[Tag]) -> MessageSignal<M, LinkDiedSignal>
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.
sourcepub fn try_tag_receive(&self, tags: &[Tag]) -> MailboxResult<M, LinkDiedSignal>
pub fn try_tag_receive(&self, tags: &[Tag]) -> MailboxResult<M, LinkDiedSignal>
Same as tag_receive
, but doesn’t panic in case the deserialization fails.
Instead, it will return MailboxError::DeserializationFailed
.
sourcepub fn receive_timeout(
&self,
timeout: Duration
) -> MailboxResult<M, LinkDiedSignal>
pub fn receive_timeout( &self, timeout: Duration ) -> MailboxResult<M, LinkDiedSignal>
Same as receive
, but only waits for the duration of timeout for the
message. If the timeout expires it will return
MailboxError::TimedOut
.
sourcepub fn tag_receive_timeout(
&self,
tags: &[Tag],
timeout: Duration
) -> MailboxResult<M, LinkDiedSignal>
pub fn tag_receive_timeout( &self, tags: &[Tag], timeout: Duration ) -> MailboxResult<M, LinkDiedSignal>
Same as tag_receive
, but only waits for the duration of timeout for
the message. If the timeout expires it will return
MailboxError::TimedOut
.
source§impl<M, S> Mailbox<M, S, ProcessDiedSignal>where
S: CanSerialize<M>,
impl<M, S> Mailbox<M, S, ProcessDiedSignal>where S: CanSerialize<M>,
sourcepub fn receive(&self) -> MessageSignal<M, ProcessDiedSignal>
pub fn receive(&self) -> MessageSignal<M, ProcessDiedSignal>
Gets next message or signal 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
.
sourcepub fn try_receive(&self) -> MailboxResult<M, ProcessDiedSignal>
pub fn try_receive(&self) -> MailboxResult<M, ProcessDiedSignal>
Same as receive
, but doesn’t panic in case the deserialization fails.
Instead, it will return MailboxError::DeserializationFailed
.
sourcepub fn tag_receive(&self, tags: &[Tag]) -> MessageSignal<M, ProcessDiedSignal>
pub fn tag_receive(&self, tags: &[Tag]) -> MessageSignal<M, ProcessDiedSignal>
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.
sourcepub fn try_tag_receive(
&self,
tags: &[Tag]
) -> MailboxResult<M, ProcessDiedSignal>
pub fn try_tag_receive( &self, tags: &[Tag] ) -> MailboxResult<M, ProcessDiedSignal>
Same as tag_receive
, but doesn’t panic in case the deserialization fails.
Instead, it will return MailboxError::DeserializationFailed
.
sourcepub fn receive_timeout(
&self,
timeout: Duration
) -> MailboxResult<M, ProcessDiedSignal>
pub fn receive_timeout( &self, timeout: Duration ) -> MailboxResult<M, ProcessDiedSignal>
Same as receive
, but only waits for the duration of timeout for the
message. If the timeout expires it will return
MailboxError::TimedOut
.
sourcepub fn tag_receive_timeout(
&self,
tags: &[Tag],
timeout: Duration
) -> MailboxResult<M, ProcessDiedSignal>
pub fn tag_receive_timeout( &self, tags: &[Tag], timeout: Duration ) -> MailboxResult<M, ProcessDiedSignal>
Same as tag_receive
, but only waits for the duration of timeout for
the message. If the timeout expires it will return
MailboxError::TimedOut
.
source§impl<M, S> Mailbox<M, S, Signal>where
S: CanSerialize<M>,
impl<M, S> Mailbox<M, S, Signal>where S: CanSerialize<M>,
sourcepub fn receive(&self) -> MessageSignal<M, Signal>
pub fn receive(&self) -> MessageSignal<M, Signal>
Gets next message or signal 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
.
sourcepub fn try_receive(&self) -> MailboxResult<M, Signal>
pub fn try_receive(&self) -> MailboxResult<M, Signal>
Same as receive
, but doesn’t panic in case the deserialization fails.
Instead, it will return MailboxError::DeserializationFailed
.
sourcepub fn tag_receive(&self, tags: &[Tag]) -> MessageSignal<M, Signal>
pub fn tag_receive(&self, tags: &[Tag]) -> MessageSignal<M, Signal>
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.
sourcepub fn try_tag_receive(&self, tags: &[Tag]) -> MailboxResult<M, Signal>
pub fn try_tag_receive(&self, tags: &[Tag]) -> MailboxResult<M, Signal>
Same as tag_receive
, but doesn’t panic in case the deserialization fails.
Instead, it will return MailboxError::DeserializationFailed
.
sourcepub fn receive_timeout(&self, timeout: Duration) -> MailboxResult<M, Signal>
pub fn receive_timeout(&self, timeout: Duration) -> MailboxResult<M, Signal>
Same as receive
, but only waits for the duration of timeout for the
message. If the timeout expires it will return
MailboxError::TimedOut
.
sourcepub fn tag_receive_timeout(
&self,
tags: &[Tag],
timeout: Duration
) -> MailboxResult<M, Signal>
pub fn tag_receive_timeout( &self, tags: &[Tag], timeout: Duration ) -> MailboxResult<M, Signal>
Same as tag_receive
, but only waits for the duration of timeout for
the message. If the timeout expires it will return
MailboxError::TimedOut
.
source§impl<M, S> Mailbox<M, S, LinkDiedSignal>where
S: CanSerialize<M>,
impl<M, S> Mailbox<M, S, LinkDiedSignal>where S: CanSerialize<M>,
A mailbox that is catching dead links.
sourcepub fn monitorable(self) -> Mailbox<M, S, Signal>
pub fn monitorable(self) -> Mailbox<M, S, Signal>
Allows this mailbox to monitor other processes.
This function returns a Mailbox
that will get a Signal::ProcessDied
message
whenever a monitored process dies.
source§impl<M, S> Mailbox<M, S, ProcessDiedSignal>where
S: CanSerialize<M>,
impl<M, S> Mailbox<M, S, ProcessDiedSignal>where S: CanSerialize<M>,
A mailbox that is monitoring other processes.
sourcepub fn catch_link_failure(self) -> Mailbox<M, S, Signal>
pub fn catch_link_failure(self) -> Mailbox<M, S, Signal>
Allow this mailbox to catch link failures.
This function returns a Mailbox
that will get a
Signal::LinkDied
message every time a linked process dies.
sourcepub fn stop_monitoring<T, U>(&self, process: Process<T, U>)
pub fn stop_monitoring<T, U>(&self, process: Process<T, U>)
Stop monitoring a process.
source§impl<M, S, L> Mailbox<M, S, L>where
S: CanSerialize<M>,
impl<M, S, L> Mailbox<M, S, L>where S: CanSerialize<M>,
sourcepub unsafe fn new() -> Self
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.