[−][src]Trait libp2p_core::muxing::StreamMuxer
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
andclose
methods operate on this. - A list of substreams that are open. The
poll_inbound
,poll_outbound
,read_substream
,write_substream
,flush_substream
,shutdown_substream
anddestroy_substream
methods allow controlling these entries. - A list of outbound substreams being opened. The
open_outbound
,poll_outbound
anddestroy_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
Required methods
fn poll_inbound(&self) -> Poll<Self::Substream, Self::Error>
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()
.
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,
s: &mut Self::OutboundSubstream
) -> Poll<Self::Substream, Self::Error>
&self,
s: &mut Self::OutboundSubstream
) -> Poll<Self::Substream, Self::Error>
Polls the outbound substream.
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 future. 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, Self::Error>
&self,
s: &mut Self::Substream,
buf: &mut [u8]
) -> Poll<usize, Self::Error>
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.
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,
s: &mut Self::Substream,
buf: &[u8]
) -> Poll<usize, Self::Error>
&self,
s: &mut Self::Substream,
buf: &[u8]
) -> Poll<usize, Self::Error>
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. 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, s: &mut Self::Substream) -> Poll<(), Self::Error>
Flushes a substream. The behaviour is the same as tokio_io::AsyncWrite::poll_flush
.
After this method has been called, data written earlier on the substream is guaranteed to be received by the remote.
If NotReady
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, s: &mut Self::Substream) -> Poll<(), Self::Error>
Attempts to shut down the writing side of a substream. The behaviour is similar to
tokio_io::AsyncWrite::shutdown
.
Contrary to 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_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) -> Poll<(), Self::Error>
Closes this StreamMuxer
.
After this has returned Ok(Async::Ready(()))
, 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) -> Poll<(), 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.
Provided methods
unsafe fn prepare_uninitialized_buffer(&self, buf: &mut [u8]) -> bool
Mimics the prepare_uninitialized_buffer
method of the AsyncRead
trait.
This function isn't actually unsafe to call but unsafe to implement. The implementer must
ensure that either the whole buf has been zeroed or that read_substream
overwrites the
buffer without reading it and returns correct value.
If this function returns true, then the memory has been zeroed out. This allows
implementations of AsyncRead
which are composed of multiple subimplementations to
efficiently implement prepare_uninitialized_buffer
.
Implementors
impl StreamMuxer for StreamMuxerBox
[src]
type Substream = usize
type OutboundSubstream = usize
type Error = Error
fn poll_inbound(&self) -> Poll<Self::Substream, Self::Error>
[src]
fn open_outbound(&self) -> Self::OutboundSubstream
[src]
fn poll_outbound(
&self,
s: &mut Self::OutboundSubstream
) -> Poll<Self::Substream, Self::Error>
[src]
&self,
s: &mut Self::OutboundSubstream
) -> Poll<Self::Substream, Self::Error>
fn destroy_outbound(&self, substream: Self::OutboundSubstream)
[src]
unsafe fn prepare_uninitialized_buffer(&self, buf: &mut [u8]) -> bool
[src]
fn read_substream(
&self,
s: &mut Self::Substream,
buf: &mut [u8]
) -> Poll<usize, Self::Error>
[src]
&self,
s: &mut Self::Substream,
buf: &mut [u8]
) -> Poll<usize, Self::Error>
fn write_substream(
&self,
s: &mut Self::Substream,
buf: &[u8]
) -> Poll<usize, Self::Error>
[src]
&self,
s: &mut Self::Substream,
buf: &[u8]
) -> Poll<usize, Self::Error>
fn flush_substream(&self, s: &mut Self::Substream) -> Poll<(), Self::Error>
[src]
fn shutdown_substream(&self, s: &mut Self::Substream) -> Poll<(), Self::Error>
[src]
fn destroy_substream(&self, s: Self::Substream)
[src]
fn close(&self) -> Poll<(), Self::Error>
[src]
fn is_remote_acknowledged(&self) -> bool
[src]
fn flush_all(&self) -> Poll<(), Self::Error>
[src]
impl<A, B> StreamMuxer for EitherOutput<A, B> where
A: StreamMuxer,
B: StreamMuxer,
[src]
A: StreamMuxer,
B: StreamMuxer,
type Substream = EitherOutput<A::Substream, B::Substream>
type OutboundSubstream = EitherOutbound<A, B>
type Error = IoError
fn poll_inbound(&self) -> Poll<Self::Substream, Self::Error>
[src]
fn open_outbound(&self) -> Self::OutboundSubstream
[src]
fn poll_outbound(
&self,
substream: &mut Self::OutboundSubstream
) -> Poll<Self::Substream, Self::Error>
[src]
&self,
substream: &mut Self::OutboundSubstream
) -> Poll<Self::Substream, Self::Error>
fn destroy_outbound(&self, substream: Self::OutboundSubstream)
[src]
unsafe fn prepare_uninitialized_buffer(&self, buf: &mut [u8]) -> bool
[src]
fn read_substream(
&self,
sub: &mut Self::Substream,
buf: &mut [u8]
) -> Poll<usize, Self::Error>
[src]
&self,
sub: &mut Self::Substream,
buf: &mut [u8]
) -> Poll<usize, Self::Error>
fn write_substream(
&self,
sub: &mut Self::Substream,
buf: &[u8]
) -> Poll<usize, Self::Error>
[src]
&self,
sub: &mut Self::Substream,
buf: &[u8]
) -> Poll<usize, Self::Error>
fn flush_substream(&self, sub: &mut Self::Substream) -> Poll<(), Self::Error>
[src]
fn shutdown_substream(&self, sub: &mut Self::Substream) -> Poll<(), Self::Error>
[src]
fn destroy_substream(&self, substream: Self::Substream)
[src]
fn is_remote_acknowledged(&self) -> bool
[src]
fn close(&self) -> Poll<(), Self::Error>
[src]
fn flush_all(&self) -> Poll<(), Self::Error>
[src]
impl<TSocket> StreamMuxer for SingletonMuxer<TSocket> where
TSocket: AsyncRead + AsyncWrite,
[src]
TSocket: AsyncRead + AsyncWrite,
type Substream = Substream
type OutboundSubstream = OutboundSubstream
type Error = Error
fn poll_inbound(&self) -> Poll<Self::Substream, Error>
[src]
fn open_outbound(&self) -> Self::OutboundSubstream
[src]
fn poll_outbound(
&self,
_: &mut Self::OutboundSubstream
) -> Poll<Self::Substream, Error>
[src]
&self,
_: &mut Self::OutboundSubstream
) -> Poll<Self::Substream, Error>
fn destroy_outbound(&self, _: Self::OutboundSubstream)
[src]
unsafe fn prepare_uninitialized_buffer(&self, buf: &mut [u8]) -> bool
[src]
fn read_substream(
&self,
_: &mut Self::Substream,
buf: &mut [u8]
) -> Poll<usize, Error>
[src]
&self,
_: &mut Self::Substream,
buf: &mut [u8]
) -> Poll<usize, Error>
fn write_substream(
&self,
_: &mut Self::Substream,
buf: &[u8]
) -> Poll<usize, Error>
[src]
&self,
_: &mut Self::Substream,
buf: &[u8]
) -> Poll<usize, Error>