Module reactive_messaging::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_unresponsive_client_processor!() or spawn_responsive_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_unresponsive_client_processor!() or start_responsive_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_responsive_client_processor
  See CompositeSocketClient::spawn_responsive_processor().
• spawn_responsive_server_processor
  See CompositeSocketServer::spawn_responsive_processor().
• spawn_unresponsive_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 (or to its “responsive” variant) – finally calling CompositeSocketClient::start_multi_protocol() when the “Composite Protocol Stacking” is complete.
• spawn_unresponsive_server_processor
  See CompositeSocketServer::spawn_unresponsive_processor().
• start_responsive_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 “responsive” Streams as specified in [GenericCompositeSocketClient::spawn_responsive_processor()].
  If you want to follow the “Composite Protocol Stacking” pattern, see the [spawn_responsive_composite_client_processor!()] macro instead.
• start_responsive_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 “responsive” Streams as specified in CompositeSocketServer::spawn_responsive_processor().
  If you want to follow the “Composite Protocol Stacking” pattern, see the [spawn_responsive_composite_server_processor!()] macro instead.
• start_unresponsive_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 “unresponsive” Streams as specified in CompositeSocketClient::spawn_unresponsive_processor().
• start_unresponsive_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_unresponsive_processor().
  If you want to follow the “Composite Protocol Stacking” pattern, see the [spawn_unresponsive_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 – OgreAllocator. providing reference counting similar to Arc
• OgreUnique
  Wrapper type for data that requires a custom Drop to be called (through an OgreAllocator). 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

• 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
• OgreAllocator
  Dictates how data slots should be acquired and returned for future reuse.
  Two APIs are available:
• 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:
• ResponsiveMessages
  Adherents will, typically, also implement [ReactiveMessagingUnresponsiveSerializer].
  By upgrading your type with this trait, it is possible to build a “Responsive Processor”, where the returned Stream contains the messages to be sent as an answer to the remote peer.
  This trait, therefore, specifies (to the internal sender) how to handle special response cases, like “no answer” and “disconnection” messages.

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