Module muxing

Muxing is the process of splitting a connection into multiple substreams.

The main item of this module is the StreamMuxer trait. An implementation of StreamMuxer has ownership of a connection, lets you open and close substreams, and read/write data on open substreams.

Note: You normally don’t need to use the methods of the StreamMuxer directly, as this is managed by the library’s internals.

Each substream of a connection is an isolated stream of data. All the substreams are muxed together so that the data read from or written to each substream doesn’t influence the other substreams.

In the context of libp2p, each substream can use a different protocol. Contrary to opening a connection, opening a substream is almost free in terms of resources. This means that you shouldn’t hesitate to rapidly open and close substreams, and to design protocols that don’t require maintaining long-lived channels of communication.

Example: The Kademlia protocol opens a new substream for each request it wants to perform. Multiple requests can be performed simultaneously by opening multiple substreams, without having to worry about associating responses with the right request.

Implementing a muxing protocol

In order to implement a muxing protocol, create an object that implements the UpgradeInfo, InboundUpgrade and OutboundUpgrade traits. See the upgrade module for more information. The Output associated type of the InboundUpgrade and OutboundUpgrade traits should be identical, and should be an object that implements the StreamMuxer trait.

The upgrade process will take ownership of the connection, which makes it possible for the implementation of StreamMuxer to control everything that happens on the wire.

Structs

OutboundSubstreamRefFuture

Future returned by outbound_from_ref.

OutboundSubstreamRefWrapFuture

Future returned by outbound_from_ref_and_wrap.

SingletonMuxer

Implementation of StreamMuxer that allows only one substream on top of a connection, yielding the connection itself.

StreamMuxerBox

Abstract StreamMuxer.

SubstreamRef

Stream returned by substream_from_ref.

Enums

StreamMuxerEvent

Event about a connection, reported by an implementation of StreamMuxer.

Traits

StreamMuxer

Implemented on objects that can open and manage substreams.

Functions

event_from_ref_and_wrap

Polls for an event from the muxer and, if an inbound substream, wraps this substream in an object that implements Read/Write/AsyncRead/AsyncWrite.

outbound_from_ref

Builds a new future for an outbound substream, where the muxer is a reference.

outbound_from_ref_and_wrap

Same as outbound_from_ref, but wraps the output in an object that implements Read/Write/AsyncRead/AsyncWrite.

substream_from_ref

Builds an implementation of Read/Write/AsyncRead/AsyncWrite from an Arc to the muxer and a substream.