Trait libp2p_core::muxing::StreamMuxer

source · 
pub trait StreamMuxer {
    type Substream: AsyncRead + AsyncWrite;
    type OutboundSubstream;
    type Error: Error;

    fn poll_event(
        &self,
        cx: &mut Context<'_>
    ) -> Poll<Result<StreamMuxerEvent<Self::Substream>, Self::Error>>;
    fn open_outbound(&self) -> Self::OutboundSubstream;
    fn poll_outbound(
        &self,
        cx: &mut Context<'_>,
        s: &mut Self::OutboundSubstream
    ) -> Poll<Result<Self::Substream, Self::Error>>;
    fn destroy_outbound(&self, s: Self::OutboundSubstream);
    fn poll_close(&self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;
}
Expand description

Provides multiplexing for a connection by allowing users to open substreams.

A substream created by a StreamMuxer is a type that implements AsyncRead and AsyncWrite.

Inbound substreams are reported via StreamMuxer::poll_event. Outbound substreams can be opened via StreamMuxer::open_outbound and subsequent polling via StreamMuxer::poll_outbound.

Required Associated Types§

Type of the object that represents the raw substream where data can be read and written.

Future that will be resolved when the outgoing substream is open.

Error type of the muxer

Required Methods§

Polls for a connection-wide event.

This function behaves the same as a Stream.

If Pending is returned, then the current task will be notified once the muxer is ready to be polled, similar to the API of Stream::poll(). Only the latest task that was used to call this method may be notified.

It is permissible and common to use this method to perform background work, such as processing incoming packets and polling timers.

An error can be generated if the connection has been closed.

Opens a new outgoing substream, and produces the equivalent to a future that will be resolved when it becomes available.

The API of OutboundSubstream is totally opaque, and the object can only be interfaced through the methods on the StreamMuxer trait.

Polls the outbound substream.

If Pending is returned, then the current task will be notified once the substream is ready to be polled, similar to the API of Future::poll(). However, for each individual outbound substream, only the latest task that was used to call this method may be notified.

May panic or produce an undefined result if an earlier polling of the same substream returned Ready or Err.

Destroys an outbound substream future. Use this after the outbound substream has finished, or if you want to interrupt it.

Closes this StreamMuxer.

After this has returned Poll::Ready(Ok(())), the muxer has become useless. All subsequent reads must return either EOF or an error. All subsequent writes, shutdowns, or polls must generate an error or be ignored.

Note: You are encouraged to call this method and wait for it to return Ready, so that the remote is properly informed of the shutdown. However, apart from properly informing the remote, there is no difference between this and immediately dropping the muxer.

Implementors§