[−][src]Trait libp2p::core::muxing::StreamMuxer

pub trait StreamMuxer {
    type Substream;
    type OutboundSubstream;
    type Error: Into<Error>;
    fn poll_inbound(
        &self, 
        cx: &mut Context
    ) -> Poll<Result<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 read_substream(
        &self, 
        cx: &mut Context, 
        s: &mut Self::Substream, 
        buf: &mut [u8]
    ) -> Poll<Result<usize, Self::Error>>;

    fn write_substream(
        &self, 
        cx: &mut Context, 
        s: &mut Self::Substream, 
        buf: &[u8]
    ) -> Poll<Result<usize, Self::Error>>;

    fn flush_substream(
        &self, 
        cx: &mut Context, 
        s: &mut Self::Substream
    ) -> Poll<Result<(), Self::Error>>;

    fn shutdown_substream(
        &self, 
        cx: &mut Context, 
        s: &mut Self::Substream
    ) -> Poll<Result<(), Self::Error>>;

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

    fn is_remote_acknowledged(&self) -> bool;

    fn close(&self, cx: &mut Context) -> Poll<Result<(), Self::Error>>;

    fn flush_all(&self, cx: &mut Context) -> Poll<Result<(), Self::Error>>;
}

Implemented on objects that can open and manage substreams.

The state of a muxer, as exposed by this API, is the following:

  • A connection to the remote. The is_remote_acknowledged, flush_all and close methods operate on this.
  • A list of substreams that are open. The poll_inbound, poll_outbound, read_substream, write_substream, flush_substream, shutdown_substream and destroy_substream methods allow controlling these entries.
  • A list of outbound substreams being opened. The open_outbound, poll_outbound and destroy_outbound methods allow controlling these entries.

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.

type Error: Into<Error>

Error type of the muxer

Loading content...

Required methods

fn poll_inbound(
    &self,
    cx: &mut Context
) -> Poll<Result<Self::Substream, Self::Error>>

Polls for an inbound substream.

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.

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

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

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.

fn poll_outbound(
    &self,
    cx: &mut Context,
    s: &mut Self::OutboundSubstream
) -> Poll<Result<Self::Substream, Self::Error>>

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.

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

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

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

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

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

If Async::Ready(0) is returned, the substream has been closed by the remote and should no longer be read afterwards.

An error can be generated if the connection has been closed, or if a protocol misbehaviour happened.

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

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

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

Calling write_substream does not guarantee that data will arrive to the remote. To ensure that, you should call flush_substream.

It is incorrect to call this method on a substream if you called shutdown_substream on this substream earlier.

fn flush_substream(
    &self,
    cx: &mut Context,
    s: &mut Self::Substream
) -> Poll<Result<(), Self::Error>>

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

After this method has been called, data written earlier on the substream is guaranteed to be received by the remote.

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

Note: This method may be implemented as a call to flush_all.

fn shutdown_substream(
    &self,
    cx: &mut Context,
    s: &mut Self::Substream
) -> Poll<Result<(), Self::Error>>

Attempts to shut down the writing side of a substream. The behaviour is similar to AsyncWrite::poll_close.

Contrary to AsyncWrite::poll_close, 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_all.

After this method has been called, you should no longer attempt to write to this substream.

An error can be generated if the connection has been closed, or if a protocol misbehaviour happened.

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

Destroys a substream.

fn is_remote_acknowledged(&self) -> bool

Returns true if the remote has shown any sign of activity after the muxer has been open.

For optimisation purposes, the connection handshake of libp2p can be very optimistic and is allowed to assume that the handshake has succeeded when it didn't in fact succeed. This method can be called in order to determine whether the remote has accepted our handshake or has potentially not received it yet.

fn close(&self, cx: &mut Context) -> Poll<Result<(), Self::Error>>

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.

Calling this method implies flush_all.

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.

fn flush_all(&self, cx: &mut Context) -> Poll<Result<(), Self::Error>>

Flush this StreamMuxer.

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

Loading content...

Implementors

impl StreamMuxer for StreamMuxerBox[src]

type Substream = usize

type OutboundSubstream = usize

type Error = Error

impl<A, B> StreamMuxer for EitherOutput<A, B> where
    A: StreamMuxer,
    B: StreamMuxer, [src]

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

type OutboundSubstream = EitherOutbound<A, B>

type Error = Error

impl<C> StreamMuxer for Multiplex<C> where
    C: AsyncRead + AsyncWrite + Unpin, [src]

type Substream = Substream

type OutboundSubstream = OutboundSubstream

type Error = Error

impl<S> StreamMuxer for Yamux<S> where
    S: Stream<Item = Result<Stream, YamuxError>> + Unpin, [src]

type Substream = Stream

type OutboundSubstream = OpenSubstreamToken

type Error = YamuxError

impl<TSocket> StreamMuxer for SingletonMuxer<TSocket> where
    TSocket: AsyncRead + AsyncWrite + Unpin, [src]

type Substream = Substream

type OutboundSubstream = OutboundSubstream

type Error = Error

Loading content...