Struct quinn::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

Closing a stream

When a stream is expected to be closed gracefully the sender should call SendStream::finish. However there is no guarantee the connected RecvStream will receive the “finished” notification in the same QUIC frame as the last frame which carried data.

Even if the application layer logic already knows it read all the data because it does its own framing, it should still read until it reaches the end of the RecvStream. Otherwise it risks inadvertently calling RecvStream::stop if it drops the stream. And calling RecvStream::stop could result in the connected SendStream::finish call failing with a WriteError::Stopped error.

For example if exactly 10 bytes are to be read, you still need to explicitly read the end of the stream:

// In the sending task
send_stream.write(&b"0123456789"[..]).await?;
send_stream.finish().await?;

// In the receiving task
let mut buf = [0u8; 10];
let data = recv_stream.read_exact(&mut buf).await?;
if recv_stream.read_to_end(0).await.is_err() {
    // Discard unexpected data and notify the peer to stop sending it
    let _ = recv_stream.stop(0u8.into());
}

An alternative approach, used in HTTP/3, is to specify a particular error code used with stop that indicates graceful receiver-initiated stream shutdown, rather than a true error condition.

RecvStream::read_chunk could be used instead which does not take ownership and allows using an explit call to RecvStream::stop with a custom error code.

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.

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.

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.

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.

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.

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

Stop accepting data

Discards unread data and notifies the peer to stop transmitting. Once stopped, further attempts to operate on a stream will yield UnknownStream 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

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.