Trait libp2p::core::muxing::StreamMuxer

pub trait StreamMuxer {
    type Substream;
    type OutboundSubstream;
    type Error: Into<Error>;
    pub fn poll_event(
        &self, 
        cx: &mut Context<'_>
    ) -> Poll<Result<StreamMuxerEvent<Self::Substream>, Self::Error>>;
    pub fn open_outbound(&self) -> Self::OutboundSubstream;
    pub fn poll_outbound(
        &self, 
        cx: &mut Context<'_>, 
        s: &mut Self::OutboundSubstream
    ) -> Poll<Result<Self::Substream, Self::Error>>;
    pub fn destroy_outbound(&self, s: Self::OutboundSubstream);
    pub fn read_substream(
        &self, 
        cx: &mut Context<'_>, 
        s: &mut Self::Substream, 
        buf: &mut [u8]
    ) -> Poll<Result<usize, Self::Error>>;
    pub fn write_substream(
        &self, 
        cx: &mut Context<'_>, 
        s: &mut Self::Substream, 
        buf: &[u8]
    ) -> Poll<Result<usize, Self::Error>>;
    pub fn flush_substream(
        &self, 
        cx: &mut Context<'_>, 
        s: &mut Self::Substream
    ) -> Poll<Result<(), Self::Error>>;
    pub fn shutdown_substream(
        &self, 
        cx: &mut Context<'_>, 
        s: &mut Self::Substream
    ) -> Poll<Result<(), Self::Error>>;
    pub fn destroy_substream(&self, s: Self::Substream);
    pub fn close(&self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;
    pub fn flush_all(
        &self, 
        cx: &mut Context<'_>
    ) -> Poll<Result<(), Self::Error>>;

    pub fn is_remote_acknowledged(&self) -> bool { ... }
}

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 poll_event, flush_all and close methods operate on this.
• A list of substreams that are open. The 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

pub fn poll_event(
    &self,
    cx: &mut Context<'_>
) -> Poll<Result<StreamMuxerEvent<Self::Substream>, Self::Error>>

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.

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

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

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

Destroys a substream.

pub 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.

pub 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...

Provided methods

pub fn is_remote_acknowledged(&self) -> bool

👎 Deprecated:

This method is unused and will be removed in the future

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.

Loading content...

Implementors

impl StreamMuxer for StreamMuxerBox

type Substream = usize

type OutboundSubstream = usize

type Error = Error

pub fn poll_event(
    &self,
    cx: &mut Context<'_>
) -> Poll<Result<StreamMuxerEvent<<StreamMuxerBox as StreamMuxer>::Substream>, <StreamMuxerBox as StreamMuxer>::Error>>

pub fn open_outbound(
    &self
) -> <StreamMuxerBox as StreamMuxer>::OutboundSubstream

pub fn poll_outbound(
    &self,
    cx: &mut Context<'_>,
    s: &mut <StreamMuxerBox as StreamMuxer>::OutboundSubstream
) -> Poll<Result<<StreamMuxerBox as StreamMuxer>::Substream, <StreamMuxerBox as StreamMuxer>::Error>>

pub fn destroy_outbound(
    &self,
    substream: <StreamMuxerBox as StreamMuxer>::OutboundSubstream
)

pub fn read_substream(
    &self,
    cx: &mut Context<'_>,
    s: &mut <StreamMuxerBox as StreamMuxer>::Substream,
    buf: &mut [u8]
) -> Poll<Result<usize, <StreamMuxerBox as StreamMuxer>::Error>>

pub fn write_substream(
    &self,
    cx: &mut Context<'_>,
    s: &mut <StreamMuxerBox as StreamMuxer>::Substream,
    buf: &[u8]
) -> Poll<Result<usize, <StreamMuxerBox as StreamMuxer>::Error>>

pub fn flush_substream(
    &self,
    cx: &mut Context<'_>,
    s: &mut <StreamMuxerBox as StreamMuxer>::Substream
) -> Poll<Result<(), <StreamMuxerBox as StreamMuxer>::Error>>

pub fn shutdown_substream(
    &self,
    cx: &mut Context<'_>,
    s: &mut <StreamMuxerBox as StreamMuxer>::Substream
) -> Poll<Result<(), <StreamMuxerBox as StreamMuxer>::Error>>

pub fn destroy_substream(&self, s: <StreamMuxerBox as StreamMuxer>::Substream)

pub fn close(
    &self,
    cx: &mut Context<'_>
) -> Poll<Result<(), <StreamMuxerBox as StreamMuxer>::Error>>

pub fn flush_all(
    &self,
    cx: &mut Context<'_>
) -> Poll<Result<(), <StreamMuxerBox as StreamMuxer>::Error>>

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>

type Error = Error

pub fn poll_event(
    &self,
    cx: &mut Context<'_>
) -> Poll<Result<StreamMuxerEvent<<EitherOutput<A, B> as StreamMuxer>::Substream>, <EitherOutput<A, B> as StreamMuxer>::Error>>

pub fn open_outbound(
    &self
) -> <EitherOutput<A, B> as StreamMuxer>::OutboundSubstream

pub fn poll_outbound(
    &self,
    cx: &mut Context<'_>,
    substream: &mut <EitherOutput<A, B> as StreamMuxer>::OutboundSubstream
) -> Poll<Result<<EitherOutput<A, B> as StreamMuxer>::Substream, <EitherOutput<A, B> as StreamMuxer>::Error>>

pub fn destroy_outbound(
    &self,
    substream: <EitherOutput<A, B> as StreamMuxer>::OutboundSubstream
)

pub fn read_substream(
    &self,
    cx: &mut Context<'_>,
    sub: &mut <EitherOutput<A, B> as StreamMuxer>::Substream,
    buf: &mut [u8]
) -> Poll<Result<usize, <EitherOutput<A, B> as StreamMuxer>::Error>>

pub fn write_substream(
    &self,
    cx: &mut Context<'_>,
    sub: &mut <EitherOutput<A, B> as StreamMuxer>::Substream,
    buf: &[u8]
) -> Poll<Result<usize, <EitherOutput<A, B> as StreamMuxer>::Error>>

pub fn flush_substream(
    &self,
    cx: &mut Context<'_>,
    sub: &mut <EitherOutput<A, B> as StreamMuxer>::Substream
) -> Poll<Result<(), <EitherOutput<A, B> as StreamMuxer>::Error>>

pub fn shutdown_substream(
    &self,
    cx: &mut Context<'_>,
    sub: &mut <EitherOutput<A, B> as StreamMuxer>::Substream
) -> Poll<Result<(), <EitherOutput<A, B> as StreamMuxer>::Error>>

pub fn destroy_substream(
    &self,
    substream: <EitherOutput<A, B> as StreamMuxer>::Substream
)

pub fn close(
    &self,
    cx: &mut Context<'_>
) -> Poll<Result<(), <EitherOutput<A, B> as StreamMuxer>::Error>>

pub fn flush_all(
    &self,
    cx: &mut Context<'_>
) -> Poll<Result<(), <EitherOutput<A, B> as StreamMuxer>::Error>>

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

type Substream = Substream

type OutboundSubstream = OutboundSubstream

type Error = Error

pub fn poll_event(
    &self,
    cx: &mut Context<'_>
) -> Poll<Result<StreamMuxerEvent<<Multiplex<C> as StreamMuxer>::Substream>, Error>>

pub fn open_outbound(&self) -> <Multiplex<C> as StreamMuxer>::OutboundSubstream

pub fn poll_outbound(
    &self,
    cx: &mut Context<'_>,
    substream: &mut <Multiplex<C> as StreamMuxer>::OutboundSubstream
) -> Poll<Result<<Multiplex<C> as StreamMuxer>::Substream, Error>>

pub fn destroy_outbound(
    &self,
    _substream: <Multiplex<C> as StreamMuxer>::OutboundSubstream
)

pub fn read_substream(
    &self,
    cx: &mut Context<'_>,
    substream: &mut <Multiplex<C> as StreamMuxer>::Substream,
    buf: &mut [u8]
) -> Poll<Result<usize, Error>>

pub fn write_substream(
    &self,
    cx: &mut Context<'_>,
    substream: &mut <Multiplex<C> as StreamMuxer>::Substream,
    buf: &[u8]
) -> Poll<Result<usize, Error>>

pub fn flush_substream(
    &self,
    cx: &mut Context<'_>,
    _substream: &mut <Multiplex<C> as StreamMuxer>::Substream
) -> Poll<Result<(), Error>>

pub fn shutdown_substream(
    &self,
    cx: &mut Context<'_>,
    sub: &mut <Multiplex<C> as StreamMuxer>::Substream
) -> Poll<Result<(), Error>>

pub fn destroy_substream(&self, sub: <Multiplex<C> as StreamMuxer>::Substream)

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

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

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

type Substream = Stream

type OutboundSubstream = OpenSubstreamToken

type Error = YamuxError

pub fn poll_event(
    &self,
    c: &mut Context<'_>
) -> Poll<Result<StreamMuxerEvent<<Yamux<S> as StreamMuxer>::Substream>, YamuxError>>

pub fn open_outbound(&self) -> <Yamux<S> as StreamMuxer>::OutboundSubstream

pub fn poll_outbound(
    &self,
    c: &mut Context<'_>,
    &mut OpenSubstreamToken
) -> Poll<Result<<Yamux<S> as StreamMuxer>::Substream, YamuxError>>

pub fn destroy_outbound(&self, <Yamux<S> as StreamMuxer>::OutboundSubstream)

pub fn read_substream(
    &self,
    c: &mut Context<'_>,
    s: &mut <Yamux<S> as StreamMuxer>::Substream,
    b: &mut [u8]
) -> Poll<Result<usize, YamuxError>>

pub fn write_substream(
    &self,
    c: &mut Context<'_>,
    s: &mut <Yamux<S> as StreamMuxer>::Substream,
    b: &[u8]
) -> Poll<Result<usize, YamuxError>>

pub fn flush_substream(
    &self,
    c: &mut Context<'_>,
    s: &mut <Yamux<S> as StreamMuxer>::Substream
) -> Poll<Result<(), YamuxError>>

pub fn shutdown_substream(
    &self,
    c: &mut Context<'_>,
    s: &mut <Yamux<S> as StreamMuxer>::Substream
) -> Poll<Result<(), YamuxError>>

pub fn destroy_substream(&self, <Yamux<S> as StreamMuxer>::Substream)

pub fn close(&self, c: &mut Context<'_>) -> Poll<Result<(), YamuxError>>

pub fn flush_all(&self, &mut Context<'_>) -> Poll<Result<(), YamuxError>>

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

type Substream = Substream

type OutboundSubstream = OutboundSubstream

type Error = Error

pub fn poll_event(
    &self,
    &mut Context<'_>
) -> Poll<Result<StreamMuxerEvent<<SingletonMuxer<TSocket> as StreamMuxer>::Substream>, Error>>

pub fn open_outbound(
    &self
) -> <SingletonMuxer<TSocket> as StreamMuxer>::OutboundSubstream

pub fn poll_outbound(
    &self,
    &mut Context<'_>,
    &mut <SingletonMuxer<TSocket> as StreamMuxer>::OutboundSubstream
) -> Poll<Result<<SingletonMuxer<TSocket> as StreamMuxer>::Substream, Error>>

pub fn destroy_outbound(
    &self,
    <SingletonMuxer<TSocket> as StreamMuxer>::OutboundSubstream
)

pub fn read_substream(
    &self,
    cx: &mut Context<'_>,
    &mut <SingletonMuxer<TSocket> as StreamMuxer>::Substream,
    buf: &mut [u8]
) -> Poll<Result<usize, Error>>

pub fn write_substream(
    &self,
    cx: &mut Context<'_>,
    &mut <SingletonMuxer<TSocket> as StreamMuxer>::Substream,
    buf: &[u8]
) -> Poll<Result<usize, Error>>

pub fn flush_substream(
    &self,
    cx: &mut Context<'_>,
    &mut <SingletonMuxer<TSocket> as StreamMuxer>::Substream
) -> Poll<Result<(), Error>>

pub fn shutdown_substream(
    &self,
    cx: &mut Context<'_>,
    &mut <SingletonMuxer<TSocket> as StreamMuxer>::Substream
) -> Poll<Result<(), Error>>

pub fn destroy_substream(
    &self,
    <SingletonMuxer<TSocket> as StreamMuxer>::Substream
)

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

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

Loading content...