Enum s2n_quic::stream::Stream

pub enum Stream {
    Bidirectional(BidirectionalStream),
    Receive(ReceiveStream),
    Send(SendStream),
}

An enum of all the possible types of QUIC streams.

Variants

Bidirectional(BidirectionalStream)

Receive(ReceiveStream)

Send(SendStream)

Implementations

impl Stream

pub fn id(&self) -> u64

Returns the stream’s identifier

This value is unique to a particular connection. The format follows the same as what is defined in the QUIC Transport RFC.

Examples

use s2n_quic::stream::Stream;

let stream = connection.open_bidirectional_stream().await?;
let stream: Stream = stream.into();
println!("New stream's id: {}", stream.id());

pub fn connection(&self) -> Handle

Returns the connection::Handle associated with the stream.

Examples

let connection = stream.connection();

println!("The stream's connection id is: {}", connection.id());

pub async fn receive(&mut self) -> Result<Option<Bytes>>

Receives a chunk of data from the stream.

Return value

The function returns:

• Ok(Some(chunk)) if the stream is open and data was available.
• Ok(None) if the stream was finished and all of the data was consumed.
• Err(e) if the stream encountered a stream::Error.

Examples

while let Some(chunk) = stream.receive().await? {
    println!("received: {:?}", chunk);
}

println!("finished");

pub fn poll_receive( &mut self, cx: &mut Context<'_> ) -> Poll<Result<Option<Bytes>>>

Poll for a chunk of data from the stream.

Return value

The function returns:

• Poll::Pending if the stream is waiting to receive data from the peer. In this case, the caller should retry receiving after the Waker on the provided Context is notified.
• Poll::Ready(Ok(Some(chunk))) if the stream is open and data was available.
• Poll::Ready(Ok(None)) if the stream was finished and all of the data was consumed.
• Poll::Ready(Err(e)) if the stream encountered a stream::Error.

pub async fn receive_vectored( &mut self, chunks: &mut [Bytes] ) -> Result<(usize, bool)>

Receives a slice of chunks of data from the stream.

This can be more efficient than calling receive for each chunk, especially when receiving large amounts of data.

Return value

The function returns:

• Ok((count, is_open)) if the stream received data into the slice, where count was the number of chunks received, and is_open indicating if the stream is still open. If is_open == true, count will be at least 1. If is_open == false, future calls to receive_vectored will always return Ok((0, false)).
• Err(e) if the stream encountered a stream::Error.

Examples

loop {
    let mut chunks = [Bytes::new(), Bytes::new(), Bytes::new()];
    let (count, is_open) = stream.receive_vectored(&mut chunks).await?;

    for chunk in &chunks[..count] {
        println!("received: {:?}", chunk);
    }

    if !is_open {
        break;
    }
}

println!("finished");

pub fn poll_receive_vectored( &mut self, chunks: &mut [Bytes], cx: &mut Context<'_> ) -> Poll<Result<(usize, bool)>>

Polls for receiving a slice of chunks of data from the stream.

Return value

The function returns:

• Poll::Pending if the stream is waiting to receive data from the peer. In this case, the caller should retry receiving after the Waker on the provided Context is notified.
• Poll::Ready(Ok((count, is_open))) if the stream received data into the slice, where count was the number of chunks received, and is_open indicating if the stream is still open. If is_open == true, count will be at least 1. If is_open == false, future calls to poll_receive_vectored will always return Poll::Ready(Ok((0, false))).
• Poll::Ready(Err(e)) if the stream encountered a stream::Error.

pub fn stop_sending(&mut self, error_code: Error) -> Result<()>

Notifies the peer to stop sending data on the stream.

This requests the peer to finish the stream as soon as possible by issuing a reset with the provided error_code.

Since this is merely a request for the peer to reset the stream, the stream will not immediately be in a reset state after issuing this call.

If the stream has already been reset by the peer or if all data has been received, the call will not trigger any action.

Return value

The function returns:

• Ok(()) if the stop sending message was enqueued for the peer.
• Err(e) if the stream encountered a stream::Error.

Examples

while let Some(stream) = connection.accept_receive_stream().await? {
    stream.stop_sending(123u8.into());
}

pub async fn send(&mut self, data: Bytes) -> Result<()>

Enqueues a chunk of data for sending it towards the peer.

Return value

The function returns:

• Ok(()) if the data was enqueued for sending.
• Err(e) if the stream encountered a stream::Error.

Examples

let data = bytes::Bytes::from_static(&[1, 2, 3, 4]);
stream.send(data).await?;

pub fn poll_send( &mut self, chunk: &mut Bytes, cx: &mut Context<'_> ) -> Poll<Result<()>>

Enqueues a chunk of data for sending it towards the peer.

Return value

The function returns:

• Poll::Pending if the stream’s send buffer capacity is currently exhausted. In this case, the caller should retry sending after the Waker on the provided Context is notified.
• Poll::Ready(Ok(())) if the data was enqueued for sending. The provided chunk will be replaced with an empty Bytes.
• Poll::Ready(Err(e)) if the stream encountered a stream::Error.

pub async fn send_vectored(&mut self, chunks: &mut [Bytes]) -> Result<()>

Enqueues a slice of chunks of data for sending it towards the peer.

Return value

The function returns:

• Ok(()) if all of the chunks of data were enqueued for sending. Each of the consumed Bytes will be replaced with an empty Bytes.
• Err(e) if the stream encountered a stream::Error.

Examples

let mut data1 = bytes::Bytes::from_static(&[1, 2, 3]);
let mut data2 = bytes::Bytes::from_static(&[4, 5, 6]);
let mut data3 = bytes::Bytes::from_static(&[7, 8, 9]);
let chunks = [data1, data2, data3];
stream.send_vectored(&mut chunks).await?;

pub fn poll_send_vectored( &mut self, chunks: &mut [Bytes], cx: &mut Context<'_> ) -> Poll<Result<usize>>

Polls enqueueing a slice of chunks of data for sending it towards the peer.

Return value

The function returns:

• Poll::Pending if the stream’s send buffer capacity is currently exhausted. In this case, the caller should retry sending after the Waker on the provided Context is notified.
• Poll::Ready(Ok(count)) if one or more chunks of data were enqueued for sending. Any of the consumed Bytes will be replaced with an empty Bytes. If count does not equal the total number of chunks, the stream will store the Waker and notify the task once more capacity is available.
• Poll::Ready(Err(e)) if the stream encountered a stream::Error.

pub fn poll_send_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<usize>>

Polls send readiness for the given stream.

This method must be called before calling send_data.

Return value

The function returns:

• Poll::Pending if the stream’s send buffer capacity is currently exhausted. In this case, the caller should retry sending after the Waker on the provided Context is notified.
• Poll::Ready(Ok(available_bytes)) if the stream is ready to send data, where available_bytes is how many bytes the stream can currently accept.
• Poll::Ready(Err(e)) if the stream encountered a stream::Error.

pub fn send_data(&mut self, chunk: Bytes) -> Result<()>

Sends data on the stream without blocking the task.

poll_send_ready must be called before calling this method.

Return value

The function returns:

• Ok(()) if the data was enqueued for sending.
• Err(SendingBlocked) if the stream did not have enough capacity to enqueue the chunk.
• Err(e) if the stream encountered a stream::Error.

pub async fn flush(&mut self) -> Result<()>

Flushes the stream and waits for the peer to receive all outstanding data.

Return value

The function returns:

• Ok(()) if the send buffer was completely flushed and acknowledged by the peer.
• Err(e) if the stream encountered a stream::Error.

Examples

let data = bytes::Bytes::from_static(&[1, 2, 3, 4]);
stream.send(data).await?;
stream.flush().await?;
// at this point, the peer has received all of the `data`

pub fn poll_flush(&mut self, cx: &mut Context<'_>) -> Poll<Result<()>>

Polls flushing the stream and waits for the peer to receive all outstanding data.

Return value

The function returns:

• Poll::Pending if the stream’s send buffer is still being sent. In this case, the caller should retry sending after the Waker on the provided Context is notified.
• Poll::Ready(Ok(())) if the send buffer was completely flushed and acknowledged by the peer.
• Poll::Ready(Err(e)) if the stream encountered a stream::Error.

pub fn finish(&mut self) -> Result<()>

Marks the stream as finished.

This method returns immediately without notifying the caller that all of the outstanding data has been received by the peer. An application wanting to both finish and flush the outstanding data can use close to accomplish this.

NOTE: This method will be called when the stream is dropped.

Return value

The function returns:

• Ok(()) if the stream was finished successfully.
• Err(e) if the stream encountered a stream::Error.

pub async fn close(&mut self) -> Result<()>

Marks the stream as finished and waits for all outstanding data to be acknowledged.

This method is equivalent to calling finish and flush.

Return value

The function returns:

• Ok(()) if the send buffer was completely flushed and acknowledged by the peer.
• Err(e) if the stream encountered a stream::Error.

Examples

let data = bytes::Bytes::from_static(&[1, 2, 3, 4]);
stream.send(data).await?;
stream.close().await?;
// at this point, the peer has received all of the `data` and has acknowledged the
// stream being finished.

pub fn poll_close(&mut self, cx: &mut Context<'_>) -> Poll<Result<()>>

Marks the stream as finished and polls for all outstanding data to be acknowledged.

This method is equivalent to calling finish and flush.

Return value

The function returns:

• Poll::Pending if the stream’s send buffer is still being sent. In this case, the caller should retry sending after the Waker on the provided Context is notified.
• Poll::Ready(Ok(())) if the send buffer was completely flushed and acknowledged by the peer.
• Poll::Ready(Err(e)) if the stream encountered a stream::Error.

pub fn reset(&mut self, error_code: Error) -> Result<()>

Closes the stream with an error code.

After calling this, the stream is closed and will not accept any additional data to be sent to the peer. The peer will also be notified of the error code.

Return value

The function returns:

• Ok(()) if the stream was reset successfully.
• Err(e) if the stream encountered a stream::Error. The stream may have been reset previously, or the connection itself was closed.

pub fn split(self) -> (Option<ReceiveStream>, Option<SendStream>)

Splits the stream into ReceiveStream and SendStream halves

Examples

let (recv, send) = stream.split();

if let Some(recv) = recv {
   // the stream has a receive half
}

if let Some(send) = send {
   // the stream has a send half
}

Trait Implementations

impl AsyncRead for Stream

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

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

impl AsyncRead for Stream

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

Attempts to read from the AsyncRead into buf.

impl AsyncWrite for Stream

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

Attempt to write bytes from buf into the object.

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

Attempt to write bytes from bufs into the object using vectored IO operations.

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

Attempt to flush the object, ensuring that any buffered data reach their destination.

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

Attempt to close the object.

impl AsyncWrite for Stream

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

Attempt to write bytes from buf into the object.

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

Like poll_write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

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

Attempts to flush the object, ensuring that any buffered data reach their destination.

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

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

impl Debug for Stream

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

Formats the value using the given formatter.

impl From<BidirectionalStream> for Stream

fn from(stream: BidirectionalStream) -> Self

Converts to this type from the input type.

impl From<ReceiveStream> for Stream

fn from(stream: ReceiveStream) -> Self

Converts to this type from the input type.

impl From<SendStream> for Stream

fn from(stream: SendStream) -> Self

Converts to this type from the input type.

impl Sink<Bytes> for Stream

type Error = StreamError

The type of value produced by the sink when an error occurs.

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

Attempts to prepare the Sink to receive a value.

fn start_send(self: Pin<&mut Self>, data: Bytes) -> Result<()>

Begin the process of sending a value to the sink. Each call to this function must be preceded by a successful call to poll_ready which returned Poll::Ready(Ok(())).

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

Flush any remaining output from this sink.

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

Flush any remaining output and close this sink, if necessary.

impl SplittableStream for Stream

fn split(self) -> (Option<ReceiveStream>, Option<SendStream>)

Splits the stream into ReceiveStream and SendStream halves

impl Stream for Stream

type Item = Result<Bytes, StreamError>

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.