Struct turbulence::message_channels::MessageChannels

pub struct MessageChannels { /* private fields */ }

Manages a set of channels through a packet multiplexer, where each channel is associated with exactly one message type.

Acts as a bridge between the sync and async worlds. Provides sync methods to send and receive messages that do not block or error. Has simplified error handling, is if any of the backing tasks end in an error or if the backing packet channels are dropped, the MessageChannels will permanently go into a “disconnected” state.

Additionally still provides async versions of methods to send and receive messages that share the same simplified error handling, which may be useful during startup or shutdown.

Implementations

impl MessageChannels

pub fn is_connected(&self) -> bool

Returns whether this MessageChannels has become disconnected because the backing network task has errored.

Once it has become disconnected, a MessageChannels is permanently in this errored state. You can receive the error from the task by calling MessageChannels::recv_err.

pub async fn recv_err(self) -> ChannelTaskError

Consume this MessageChannels and receive the networking task shutdown error.

If this MessageChannels is disconnected, returns the error that caused it to become disconnected. If it is not disconnected, it will become disconnected by calling this and return that error.

pub fn send<M: ChannelMessage>(&mut self, message: M) -> Option<M>

Send the given message on the channel associated with its message type.

In order to ensure delivery, flush should be called for the same message type to immediately send any buffered messages.

If the mpsc channel for this message type is full, will return the message that was sent back to the caller. If the message was successfully put onto the outgoing mpsc channel, will return None.

Panics

Panics if this message type was not registered with the MessageChannelsBuilder used to build this MessageChannels instance.

pub fn try_send<M: ChannelMessage>(
    &mut self,
    message: M
) -> Result<Option<M>, MessageTypeUnregistered>

Like MessageChannels::send but errors instead of panicking when the message type is unregistered.

pub async fn async_send<M: ChannelMessage>(
    &mut self,
    message: M
) -> Result<(), MessageChannelsDisconnected>

Any async version of MessageChannels::send, sends the given message on the channel associated with its message type but waits if the channel is full. Like MessageChannels::send, MessageChannels::flush must still be called afterwards in order to ensure delivery.

This method is cancel safe, it will never partially send a message, though canceling it may or may not buffer a message to be sent.

Panics

Panics if this message type is not registered.

pub async fn try_async_send<M: ChannelMessage>(
    &mut self,
    message: M
) -> Result<(), TryAsyncMessageError>

Like MessageChannels::async_send but errors instead of panicking when the message type is unregistered.

pub fn flush<M: ChannelMessage>(&mut self)

Immediately send any buffered messages for this message type. Messages may not be delivered unless flush is called after any send calls.

Panics

Panics if this message type was not registered with the MessageChannelsBuilder used to build this MessageChannels instance.

pub fn try_flush<M: ChannelMessage>(
    &mut self
) -> Result<(), MessageTypeUnregistered>

Like MessageChannels::flush but errors instead of panicking when the message type is unregistered.

pub fn recv<M: ChannelMessage>(&mut self) -> Option<M>

Receive an incoming message on the channel associated with this mesage type, if one is available.

Panics

Panics if this message type was not registered with the MessageChannelsBuilder used to build this MessageChannels instance.

pub fn try_recv<M: ChannelMessage>(
    &mut self
) -> Result<Option<M>, MessageTypeUnregistered>

Like MessageChannels::recv but errors instead of panicking when the message type is unregistered.

pub async fn async_recv<M: ChannelMessage>(
    &mut self
) -> Result<M, MessageChannelsDisconnected>

Any async version of MessageChannels::receive, receives an incoming message on the channel associated with its message type but waits if there is no message available.

This method is cancel safe, it will never partially read a message or drop received messages.

Panics

Panics if this message type is not registered.

pub async fn try_async_recv<M: ChannelMessage>(
    &mut self
) -> Result<M, TryAsyncMessageError>

Like MessageChannels::async_recv but errors instead of panicking when the message type is unregistered.

pub fn statistics<M: ChannelMessage>(&self) -> &ChannelStatistics

pub fn try_statistics<M: ChannelMessage>(
    &self
) -> Result<&ChannelStatistics, MessageTypeUnregistered>

Trait Implementations

impl Debug for MessageChannels

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

Formats the value using the given formatter.