Struct s2n_quic::stream::SendStream

pub struct SendStream(/* private fields */);

A QUIC stream that is only allowed to send data.

Implementations

impl SendStream

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

let stream = connection.open_send_stream().await?;
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 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.

Trait Implementations

impl AsyncWrite for SendStream

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 SendStream

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 SendStream

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

Formats the value using the given formatter.

impl From<SendStream> for LocalStream

fn from(stream: SendStream) -> 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 SendStream

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 SendStream

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

Splits the stream into ReceiveStream and SendStream halves