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 fn id(&self) -> StreamId

Get the identity of this stream

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 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 async fn stopped(&mut self) -> Result<Option<VarInt>, StoppedError>

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.

pub async fn read( &mut self, buf: impl BufMut, ) -> 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: impl BufMut, ) -> Result<(), ReadExactError>

Read an exact number of bytes contiguously from the stream.

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

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, buf: impl BufMut, ) -> Result<usize, ReadError>

Convenience method to read all remaining data into a buffer.

Uses unordered reads to be more efficient than using AsyncRead. If unordered reads have already been made, the resulting buffer may have gaps containing zero.

Depending on BufMut implementation, this method may fail with ReadError::BufferTooShort if the buffer is not large enough to hold the entire stream. For example when using a &mut [u8] it will never receive bytes more than the length of the slice, but when using a &mut Vec<u8> it will allocate more memory as needed.

This operation is not cancel-safe.

Trait Implementations

impl AsyncRead for RecvStream

async fn read<B: IoBufMut>(&mut self, buf: B) -> BufResult<usize, B>

Read some bytes from this source into the IoBufMut buffer and return a BufResult, consisting of the buffer and a usize indicating how many bytes were read.

async fn read_vectored<V>(&mut self, buf: V) -> BufResult<usize, V>

where V: IoVectoredBufMut,

Like read, except that it reads into a type implements IoVectoredBufMut.

impl AsyncRead for RecvStream

Available on crate feature io-compat only.

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

impl RecvStream for RecvStream

Available on crate feature h3 only.

type Buf = Bytes

The type of Buf for data received on this stream.

fn poll_data( &mut self, cx: &mut Context<'_>, ) -> Poll<Result<Option<Self::Buf>, StreamErrorIncoming>>

Poll the stream for more data.

fn stop_sending(&mut self, error_code: u64)

Send a STOP_SENDING QUIC code.

fn recv_id(&self) -> StreamId

Get QUIC send stream id