fluencelabs/rust-libp2p
1
0
Fork 0
mirror of https://github.com/fluencelabs/rust-libp2p synced 2025-05-10 09:57:14 +00:00
Code Issues Projects Releases Wiki Activity

Add some comments about the notification behaviour of muxers (#453)

Browse Source
This commit is contained in:
Pierre Krieger 2018-09-11 11:17:44 +02:00 committed by GitHub
parent cfdfca1a06
commit fd4b7488be
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 29 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
core/src/muxing.rs
View File

@ -34,6 +34,10 @@ pub trait StreamMuxer {
/// Polls for an inbound substream. /// Polls for an inbound substream.
/// ///
/// This function behaves the same as a `Stream`. /// 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.
fn poll_inbound(&self) -> Poll<Option<Self::Substream>, IoError>; fn poll_inbound(&self) -> Poll<Option<Self::Substream>, IoError>;
/// Opens a new outgoing substream, and produces a future that will be resolved when it becomes /// Opens a new outgoing substream, and produces a future that will be resolved when it becomes
@ -43,6 +47,11 @@ pub trait StreamMuxer {
/// Polls the outbound substream. /// Polls the outbound substream.
/// ///
/// May panic or produce an undefined result if an earlier polling returned `Ready` or `Err`. /// May panic or produce an undefined result if an earlier polling returned `Ready` or `Err`.
///
/// 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.
fn poll_outbound( fn poll_outbound(
&self, &self,
substream: &mut Self::OutboundSubstream, substream: &mut Self::OutboundSubstream,
@ -53,6 +62,11 @@ pub trait StreamMuxer {
fn destroy_outbound(&self, substream: Self::OutboundSubstream); fn destroy_outbound(&self, substream: Self::OutboundSubstream);
/// Reads data from a substream. The behaviour is the same as `std::io::Read::read`. /// Reads data from a substream. The behaviour is the same as `std::io::Read::read`.
///
/// If `WouldBlock` is returned, then the current task will be notified once the substream
/// is ready to be read, similar to the API of `AsyncRead`.
/// However, for each individual substream, only the latest task that was used to call this
/// method may be notified.
fn read_substream( fn read_substream(
&self, &self,
substream: &mut Self::Substream, substream: &mut Self::Substream,
@ -60,6 +74,11 @@ pub trait StreamMuxer {
) -> Result<usize, IoError>; ) -> Result<usize, IoError>;
/// Write data to a substream. The behaviour is the same as `std::io::Write::write`. /// Write data to a substream. The behaviour is the same as `std::io::Write::write`.
///
/// If `WouldBlock` is returned, then the current task will be notified once the substream
/// is ready to be written, similar to the API of `AsyncWrite`.
/// However, for each individual substream, only the latest task that was used to call this
/// method may be notified.
fn write_substream( fn write_substream(
&self, &self,
substream: &mut Self::Substream, substream: &mut Self::Substream,
@ -67,10 +86,20 @@ pub trait StreamMuxer {
) -> Result<usize, IoError>; ) -> Result<usize, IoError>;
/// Flushes a substream. The behaviour is the same as `std::io::Write::flush`. /// Flushes a substream. The behaviour is the same as `std::io::Write::flush`.
///
/// If `WouldBlock` is returned, then the current task will be notified once the substream
/// is ready to be flushed, similar to the API of `AsyncWrite`.
/// However, for each individual substream, only the latest task that was used to call this
/// method may be notified.
fn flush_substream(&self, substream: &mut Self::Substream) -> Result<(), IoError>; fn flush_substream(&self, substream: &mut Self::Substream) -> Result<(), IoError>;
/// Attempts to shut down a substream. The behaviour is the same as /// Attempts to shut down a substream. The behaviour is the same as
/// `tokio_io::AsyncWrite::shutdown`. /// `tokio_io::AsyncWrite::shutdown`.
///
/// If `NotReady` is returned, then the current task will be notified once the substream
/// is ready to be shut down, similar to the API of `AsyncWrite::shutdown()`.
/// However, for each individual substream, only the latest task that was used to call this
/// method may be notified.
fn shutdown_substream(&self, substream: &mut Self::Substream) -> Poll<(), IoError>; fn shutdown_substream(&self, substream: &mut Self::Substream) -> Poll<(), IoError>;
/// Destroys a substream. /// Destroys a substream.