Struct RecvStream

pub struct RecvStream { /* private fields */ }

A stream that can only be used to receive data

stop(0) is implicitly called on drop unless:

• A variant of ReadError has been yielded by a read call
• stop() was called explicitly

Cancellation

A read method is said to be cancel-safe when dropping its future before the future becomes ready cannot lead to loss of stream data. This is true of methods which succeed immediately when any progress is made, and is not true of methods which might need to perform multiple reads internally before succeeding. Each read method documents whether it is cancel-safe.

Common issues

Data never received on a locally-opened stream

Peers are not notified of streams until they or a later-numbered stream are used to send data. If a bidirectional stream is locally opened but never used to send, then the peer may never see it. Application protocols should always arrange for the endpoint which will first transmit on a stream to be the endpoint responsible for opening it.

Data never received on a remotely-opened stream

Verify that the stream you are receiving is the same one that the server is sending on, e.g. by logging the id of each. Streams are always accepted in the same order as they are created, i.e. ascending order by StreamId. For example, even if a sender first transmits on bidirectional stream 1, the first stream yielded by Connection::accept_bi on the receiver will be bidirectional stream 0.

Implementations

impl RecvStream

pub async fn read(&mut self, buf: &mut [u8]) -> Result<Option<usize>, ReadError>

Read data contiguously from the stream.

Yields the number of bytes read into buf on success, or None if the stream was finished.

This operation is cancel-safe.

pub async fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), ReadExactError>

Read an exact number of bytes contiguously from the stream.

See read() for details. This operation is not cancel-safe.

pub fn poll_read( &mut self, cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll<Result<usize, ReadError>>

Attempts to read from the stream into buf.

On success, returns Poll::Ready(Ok(num_bytes_read)) and places data in the buf. If no data was read, it implies that EOF has been reached.

If no data is available for reading, the method returns Poll::Pending and arranges for the current task (via cx.waker()) to receive a notification when the stream becomes readable or is closed.

pub async fn read_chunk( &mut self, max_length: usize, ordered: bool, ) -> Result<Option<Chunk>, ReadError>

Read the next segment of data

Yields None if the stream was finished. Otherwise, yields a segment of data and its offset in the stream. If ordered is true, the chunk’s offset will be immediately after the last data yielded by read() or read_chunk(). If ordered is false, segments may be received in any order, and the Chunk’s offset field can be used to determine ordering in the caller. Unordered reads are less prone to head-of-line blocking within a stream, but require the application to manage reassembling the original data.

Slightly more efficient than read due to not copying. Chunk boundaries do not correspond to peer writes, and hence cannot be used as framing.

This operation is cancel-safe.

pub async fn read_chunks( &mut self, bufs: &mut [Bytes], ) -> Result<Option<usize>, ReadError>

Read the next segments of data

Fills bufs with the segments of data beginning immediately after the last data yielded by read or read_chunk, or None if the stream was finished.

Slightly more efficient than read due to not copying. Chunk boundaries do not correspond to peer writes, and hence cannot be used as framing.

This operation is cancel-safe.

pub async fn read_to_end( &mut self, size_limit: usize, ) -> Result<Vec<u8>, ReadToEndError>

Convenience method to read all remaining data into a buffer

Fails with ReadToEndError::TooLong on reading more than size_limit bytes, discarding all data read. Uses unordered reads to be more efficient than using AsyncRead would allow. size_limit should be set to limit worst-case memory use.

If unordered reads have already been made, the resulting buffer may have gaps containing arbitrary data.

This operation is not cancel-safe.

pub fn stop(&mut self, error_code: VarInt) -> Result<(), ClosedStream>

Stop accepting data

Discards unread data and notifies the peer to stop transmitting. Once stopped, further attempts to operate on a stream will yield ClosedStream errors.

pub fn is_0rtt(&self) -> bool

Check if this stream has been opened during 0-RTT.

In which case any non-idempotent request should be considered dangerous at the application level. Because read data is subject to replay attacks.

pub fn id(&self) -> StreamId

Get the identity of this stream

pub async fn received_reset(&mut self) -> Result<Option<VarInt>, ResetError>

Completes when the stream has been reset by the peer or otherwise closed

Yields Some with the reset error code when the stream is reset by the peer. Yields None when the stream was previously stop()ed, or when the stream was finish()ed by the peer and all data has been received, after which it is no longer meaningful for the stream to be reset.

This operation is cancel-safe.

Trait Implementations

impl AsyncRead for RecvStream

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>], ) -> Poll<Result<usize, Error>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl AsyncRead for RecvStream

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<()>>

Attempts to read from the AsyncRead into buf.

impl Debug for RecvStream

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for RecvStream

fn drop(&mut self)

Executes the destructor for this type.