Trait libp2p_core::muxing::StreamMuxer

pub trait StreamMuxer {
    type Substream;
    type OutboundSubstream;

    fn poll_inbound(&self) -> Poll<Option<Self::Substream>, IoError>;
    fn open_outbound(&self) -> Self::OutboundSubstream;
    fn poll_outbound(
        &self,
        s: &mut Self::OutboundSubstream
    ) -> Poll<Option<Self::Substream>, IoError>;
    fn destroy_outbound(&self, s: Self::OutboundSubstream);
    fn read_substream(
        &self,
        s: &mut Self::Substream,
        buf: &mut [u8]
    ) -> Poll<usize, IoError>;
    fn write_substream(
        &self,
        s: &mut Self::Substream,
        buf: &[u8]
    ) -> Poll<usize, IoError>;
    fn flush_substream(&self, s: &mut Self::Substream) -> Poll<(), IoError>;
    fn shutdown_substream(
        &self,
        s: &mut Self::Substream,
        kind: Shutdown
    ) -> Poll<(), IoError>;
    fn destroy_substream(&self, s: Self::Substream);
    fn shutdown(&self, kind: Shutdown) -> Poll<(), IoError>;
    fn flush_all(&self) -> Poll<(), IoError>;
}

Implemented on objects that can open and manage substreams.

Required Associated Types

type Substream

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

type OutboundSubstream

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

Required Methods

fn poll_inbound(&self) -> Poll<Option<Self::Substream>, IoError>

Polls for an inbound substream.

This function behaves the same as a Stream.

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

fn open_outbound(&self) -> Self::OutboundSubstream

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

fn poll_outbound(
    &self,
    s: &mut Self::OutboundSubstream
) -> Poll<Option<Self::Substream>, IoError>

Polls the outbound substream.

If this returns Ok(Ready(None)), that means that the outbound channel is closed and that opening any further outbound substream will likely produce None as well. The existing outbound substream attempts may however still succeed.

If NotReady 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.

fn destroy_outbound(&self, s: Self::OutboundSubstream)

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

fn read_substream(
    &self,
    s: &mut Self::Substream,
    buf: &mut [u8]
) -> Poll<usize, IoError>

Reads data from a substream. The behaviour is the same as tokio_io::AsyncRead::poll_read.

If NotReady is returned, then the current task will be notified once the substream is ready to be read. However, for each individual substream, only the latest task that was used to call this method may be notified.

fn write_substream(
    &self,
    s: &mut Self::Substream,
    buf: &[u8]
) -> Poll<usize, IoError>

Write data to a substream. The behaviour is the same as tokio_io::AsyncWrite::poll_write.

If NotReady is returned, then the current task will be notified once the substream is ready to be read. However, for each individual substream, only the latest task that was used to call this method may be notified.

fn flush_substream(&self, s: &mut Self::Substream) -> Poll<(), IoError>

Flushes a substream. The behaviour is the same as tokio_io::AsyncWrite::poll_flush.

If NotReady is returned, then the current task will be notified once the substream is ready to be read. However, for each individual substream, only the latest task that was used to call this method may be notified.

fn shutdown_substream(
    &self,
    s: &mut Self::Substream,
    kind: Shutdown
) -> Poll<(), IoError>

Attempts to shut down a substream. The behaviour is similar to tokio_io::AsyncWrite::shutdown.

Shutting down a substream does not imply flush_substream. If you want to make sure that the remote is immediately informed about the shutdown, use flush_substream or flush.

fn destroy_substream(&self, s: Self::Substream)

Destroys a substream.

fn shutdown(&self, kind: Shutdown) -> Poll<(), IoError>

Shutdown this StreamMuxer.

If supported, sends a hint to the remote that we may no longer open any further outbound or inbound substream. Calling poll_outbound or poll_inbound afterwards may or may not produce None.

Shutting down the muxer does not imply flush_all. If you want to make sure that the remote is immediately informed about the shutdown, use flush_all.

fn flush_all(&self) -> Poll<(), IoError>

Flush this StreamMuxer.

This drains any write buffers of substreams and otherwise and delivers any pending shutdown notifications due to shutdown_substream or shutdown. One may thus shutdown groups of substreams followed by a final flush_all instead of having to do flush_substream for each.

Implementors

impl StreamMuxer for StreamMuxerBox

type Substream = usize

type OutboundSubstream = usize

impl<A, B> StreamMuxer for EitherOutput<A, B>where
    A: StreamMuxer,
    B: StreamMuxer,

type Substream = EitherOutput<<A as StreamMuxer>::Substream, <B as StreamMuxer>::Substream>

type OutboundSubstream = EitherOutbound<A, B>