Module prelude

Re-exports of types – out of the internal directory and module structure – useful for users of this crate

Macros

_define_processor_uni_and_sender_channel_types

For internal use: defines ProcessorUniType & SenderChannel based on the given [Channels] parameter (for use when spawning processors with [MessagingService::spawn_unresponsive_processor()] & [MessagingService::spawn_responsive_processor()].)

multis_close_async

Macro to close, atomically-ish, all Multis passed in as parameters

new_composite_socket_client

Instantiates & allocates resources for a stateful CompositeSocketClient (suitable for the “Composite Protocol Stacking” pattern), ready to have processors added by spawn_client_processor!().

new_composite_socket_server

Instantiates & allocates resources for a stateful CompositeSocketServer (suitable for the “Composite Protocol Stacking” pattern), ready to have processors added by [spawn_unresponsive_server_processor!()] or [spawn_responsive_server_processor!()] and to be later started by CompositeSocketServer::start_multi_protocol() – using the default “Atomic” channels (see [new_composite_fullsync_server!()] & [new_composite_crossbeam_server!()] for alternatives).
Params:

new_socket_client

Instantiates & allocates resources for a stateless CompositeSocketClient (suitable for single protocol communications), ready to be later started by start_client_processor!().

new_socket_server

Instantiates & allocates resources for a stateless CompositeSocketServer (suitable for single protocol communications), ready to be later started by [start_unresponsive_server_processor!()] or [start_responsive_server_processor!()].

spawn_client_processor

Spawns a processor for a client (previously instantiated by new_composite_socket_client!()) that may communicate with the server using multiple protocols / multiple calls to this macro with different parameters – and finally calling CompositeSocketClient::start_multi_protocol() when the “Composite Protocol Stacking” is complete.

spawn_server_processor

See CompositeSocketServer::spawn_processor().

start_client_processor

Starts a client (previously instantiated by new_socket_client!()) that will communicate with the server using a single protocol – as defined by the given dialog_processor_builder_fn, a builder of Streams as specified in CompositeSocketClient::spawn_processor().

start_server_processor

Starts a server (previously instantiated by new_socket_server!()) that will communicate with clients using a single protocol – as defined by the given dialog_processor_builder_fn, a builder of “unresponsive” Streams as specified in CompositeSocketServer::spawn_processor().
If you want to follow the “Composite Protocol Stacking” pattern, see the [spawn_composite_server_processor!()] macro instead.

unis_close_async

Macro to close, atomically-ish, all Unis passed as parameters

Structs

ClientConnectionManager

Abstracts out the TCP/IP intricacies for establishing (and retrying) connections, while still enabling the “Protocol Stack Composition” pattern by accepting existing connections to be provided (instead of opening new ones).

CompositeSocketClient

Real definition & implementation for our Socket Client, full of generic parameters.
Probably you want to instantiate this structure through the sugared macros new_socket_client!() or new_composite_socket_client!() instead. Generic Parameters:

CompositeSocketServer

Real definition & implementation for our Socket Server, full of generic parameters.
Probably you want to instantiate this structure through the sugared macros new_socket_server!() or new_composite_socket_server!() instead. Generic Parameters:

ConnectionChannel

The abstraction for handling server connections – here, the connections are provided through a Stream instead of through the TCP/IP API directly. This enables the “Protocol Stack Composition” pattern, as already existing connections may be also added to the Stream (in addition to fresh incoming ones).
When the end-of-stream is reached (possibly due to a “server shutdown” request), the Stream will return None.

ConstConfig

Implements something that could be called the “Zero-Cost Const Configuration Pattern”, that produces a usize whose goal is to be the only const parameter of a generic struct (avoiding the alternative of bloating it with several const params).
When using the const “query functions” defined here in ifs, the compiler will have the opportunity to cancel out any unreachable code (zero-cost abstraction).
Some commonly used combinations may be pre-defined in some enum variants, but you may always build unmapped possibilities through [Self::custom()].
Usage examples:

Multi

Multi is an event handler capable of having several “listeners” – all of which receives all events.
With this struct, it is possible to:

MutinyStream

Special Stream implementation to avoid using dynamic dispatching, so to allow the compiler to fully optimize the whole event consumption chain.
The following paths are covered:

OgreArc

Wrapper type for data providing an atomic reference counter for dropping control, similar to Arc, but allowing a custom allocator to be used – BoundedOgreAllocator. providing reference counting similar to Arc

OgreUnique

Wrapper type for data that requires a custom Drop to be called (through an BoundedOgreAllocator). Similar to C++’s unique_ptr

Peer

Represents a reactive channel connected to a remote peer, through which we’re able to send out “local messages” of type RetryableSenderImpl::LocalMessages.
the Self::send() method honors whatever retrying config is specified in [RetryableSenderImpl::CONST_CONFIG]. IMPLEMENTATION NOTE: GAT traits (to reduce the number of generic parameters) couldn’t be used here – even after applying this compiler bug workaround https://github.com/rust-lang/rust/issues/102211#issuecomment-1513931928 – the “error: implementation of std::marker::Send is not general enough” bug kept on popping up in user provided closures that called other async functions.

ReceiverDroppedErr

Indicates the receiver end of a channel was dropped, therefore the element of type T couldn’t be sent and is being returned back along with the error indication.
Important: This is an unrecoverable situation, so trying again is futile.

ServerConnectionHandler

Abstracts out, from servers, the connection handling so to enable the “Protocol Stack Composition” pattern:
Binds to a network listening interface and port and starts a network event loop for accepting connections, supplying them to an internal ConnectionChannel (while also allowing manually fed connections).

SocketConnection

A wrapper for a TcpStream – attaching a custom “state” and unique id to it.
This abstraction plays a role in enabling the “Composite Protocol Stacking” design pattern.
IMPLEMENTATION NOTE: The crate::prelude::Peer object still holds a copy of the state – synced elsewhere with us here – in the future, this should be reworked.

SocketOptions

Socket options for the local peer to be set when the connection is established

Uni

Contains the producer-side Uni handle used to interact with the uni event – for closing the stream, requiring stats, …

Enums

ConnectionEvent

Event issued by Composite Protocol Clients & Servers when connections are made or dropped

Instruments

Honors the Zero-Cost Instrumentation Pattern for the [stream_executors]:
Designed to be used as a const generic parameter for Structs, causes the conditional instrumentation code in client structs to be selectively compiled – see the implemented const methods for documentation of each available instrument.

ProtocolEvent

Event issued by Composite Protocol Clients & Servers to their Reactive Processors.
The user code may use those events to maintain a list of connected parties, be notified of stop/close/quit requests, init/de-init sessions, etc. Note that the Peer objects received in those events may be used, at any time, to send messages to the remote party – like “Shutting down. Goodbye”. IMPLEMENTATION NOTE: GAT traits (to reduce the number of generic parameters) couldn’t be used here – even after applying this compiler bug workaround https://github.com/rust-lang/rust/issues/102211#issuecomment-1513931928 – the “error: implementation of std::marker::Send is not general enough” bug kept on popping up in user provided closures that called other async functions.

RetryingStrategies

Specifies how to behave when communication failures happen

Traits

BoundedOgreAllocator

Dictates how data slots – in a bounded allocator – should be acquired and returned for future reuse.
A bounded allocator differs from a tradicional allocator (like Box) in these fundamental aspects:

ChannelCommon

Defines common abstractions on how [Uni]s receives produced events and delivers them to Streams.
Implementors should also implement one of ChannelProducer or [UniZeroCopyChannel]. NOTE: all async functions are out of the hot path, so the async_trait won’t impose performance penalties

ChannelConsumer

Source of events for MutinyStream.

ChannelMulti

Defines abstractions specific to [Uni] channels

ChannelProducer

Defines how to send events (to a [Uni] or [Multi]).

ChannelUni

Defines abstractions specific to [Uni] channels

FullDuplexMultiChannel

A fully fledged Multi channel, that has both the producer and consumer parts Also, laverages generic programming by allowing simpler generic parameters:

FullDuplexUniChannel

Defines a fully fledged Uni channel, that has both the producer and consumer parts Also, laverages generic programming by allowing simpler generic parameters:

GenericMulti

This trait exists to allow simplifying generic declarations of concrete Multi types. See also [GenericUni].
Usage:

GenericUni

This trait exists to allow simplifying generic declarations of concrete Uni types. See also [GenericMulti].
Usage:

MessagingService

Base trait for server and client services functionalities

ReactiveMessagingDeserializer

Trait that should be implemented by enums that model the “remote messages” to be consumed by a “Responsive Processor” – “remote messages” may either be messages produced by the remote server or by the remote client (when we are implementing the opposite peer).
This trait, therefore, specifies how to deserialize() enum variants received by the remote peer (like RON, for textual protocols)

ReactiveMessagingSerializer

Trait that should be implemented by enums that model the “local messages” to be sent to the remote peer – “local messages” may either be messages generated by the server or by the client, depending on if you’re building a server or client.
This trait, therefore, specifies how to:

ResponsiveStream

The implementor of this trait adds a new functionality to Streams, allowing the yielded items to be sent out to the peer

Functions

ron_deserializer

RON deserializer

ron_serializer

RON serializer

Type Aliases

AllocatorAtomicArray

AllocatorFullSyncArray

ChannelMultiArcAtomic

ChannelMultiArcCrossbeam

ChannelMultiArcFullSync

ChannelMultiMmapLog

ChannelMultiOgreArcAtomic

ChannelMultiOgreArcFullSync

ChannelUniMoveAtomic

ChannelUniMoveCrossbeam

ChannelUniMoveFullSync

ChannelUniZeroCopyAtomic

ChannelUniZeroCopyFullSync

ConnectionId

MessagingMutinyStream

Concrete type of the Streams this crate produces.
Type for the Stream we create when reading from the remote peer.
This type is intended to be used only for the first level of dialog_processor_builder()s you pass to the [SocketClient] or [SocketServer], as Rust Generics isn’t able to infer a generic Stream type in this situation (in which the Stream is created inside the generic function itself).
If your logic uses functions that receive Streams, you’ll want flexibility to do whatever you want with the Stream (which would no longer be a MutinyStream), so declare such functions as:

MultiArc

Default Multi for those who wants to use Arc as the wrapping type for payloads

MultiAtomicArc

MultiAtomicOgreArc

MultiCrossbeamArc

MultiFullSyncArc

MultiFullSyncOgreArc

MultiMmapLog

MultiOgreArc

Default Multi for those who want the more performant OgreArc as the wrapping type for their payloads

UniMove

Default UniBuilder for “moving” data around – good for small payloads (< 1k) whose types don’t require a custom Drop function

UniMoveAtomic

UniMoveCrossbeam

UniMoveFullSync

UniZeroCopy

Default ‘UniBuilder’ for “zero-copying” data that will either be shared around or has a reasonably “big” payload (> 1k)

UniZeroCopyAtomic

UniZeroCopyFullSync