logo

Trait libp2p::core::muxing::StreamMuxer

source · [−]
pub trait StreamMuxer {
    type Substream;
    type OutboundSubstream;
    type Error: Into<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 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 close(&self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;

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

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

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

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.

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.

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.

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.

Destroys a substream.

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.

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.

Provided methods

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

Implementors

Note: This implementation never emits StreamMuxerEvent::AddressChange events.