Trait libp2p_core::muxing::StreamMuxer
source · 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>;
}
Expand description
Implemented on objects that can open and manage substreams.
Required Associated Types
sourcetype Substream
type Substream
Type of the object that represents the raw substream where data can be read and written.
sourcetype OutboundSubstream
type OutboundSubstream
Future that will be resolved when the outgoing substream is open.
Required Methods
sourcefn poll_inbound(&self) -> Poll<Option<Self::Substream>, IoError>
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.
sourcefn open_outbound(&self) -> Self::OutboundSubstream
fn open_outbound(&self) -> Self::OutboundSubstream
Opens a new outgoing substream, and produces a future that will be resolved when it becomes available.
sourcefn poll_outbound(
&self,
s: &mut Self::OutboundSubstream
) -> Poll<Option<Self::Substream>, IoError>
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
.
sourcefn destroy_outbound(&self, s: Self::OutboundSubstream)
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.
sourcefn read_substream(
&self,
s: &mut Self::Substream,
buf: &mut [u8]
) -> Poll<usize, IoError>
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.
sourcefn write_substream(
&self,
s: &mut Self::Substream,
buf: &[u8]
) -> Poll<usize, IoError>
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.
sourcefn flush_substream(&self, s: &mut Self::Substream) -> Poll<(), IoError>
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.
sourcefn shutdown_substream(
&self,
s: &mut Self::Substream,
kind: Shutdown
) -> Poll<(), IoError>
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
.
sourcefn destroy_substream(&self, s: Self::Substream)
fn destroy_substream(&self, s: Self::Substream)
Destroys a substream.
sourcefn shutdown(&self, kind: Shutdown) -> Poll<(), IoError>
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
.
sourcefn flush_all(&self) -> Poll<(), IoError>
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.