Struct RecvStream 

pub struct RecvStream { /* private fields */ }

Available on crate feature quic only.

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 fn poll_read_uninit( &mut self, cx: &mut Context<'_>, buf: &mut [MaybeUninit<u8>], ) -> Poll<Result<usize, ReadError>>

Attempts to read from the stream into the provided buffer

On success, returns Poll::Ready(Ok(num_bytes_read)) and places data into buf. If the buffer passed in has non-zero length and a 0 is returned, that indicates that the remote side has finished the stream and the local side has already read all bytes.

If no data is available for reading, this returns Poll::Pending and arranges for the current task (via cx.waker()) to be notified 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<B>(&mut self, buf: B) -> BufResult<usize, B>

where B: IoBufMut,

Convenience method to read all remaining data into a buffer.

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

This operation is not cancel-safe.

pub fn into_compat(self) -> CompatRecvStream

Available on crate feature io-compat only.

Convert into an [futures_util] compatible stream.

Trait Implementations

impl AsyncRead for RecvStream

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

where B: IoBufMut,

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 Debug for RecvStream

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

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

type Buf = Bytes

The type of Buf for data received on this stream.

fn poll_data( &mut self, cx: &mut Context<'_>, ) -> Poll<Result<Option<<RecvStream as RecvStream>::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