Struct SendStream 

pub struct SendStream { /* private fields */ }

Available on crate features quic and std only.

A stream that can only be used to send data

If dropped, streams that haven’t been explicitly reset() will be implicitly finish()ed, continuing to (re)transmit previously written data until it has been fully acknowledged or the connection is closed.

Cancellation

A write method is said to be cancel-safe when dropping its future before the future becomes ready will always result in no data being written to the stream. 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 writes internally before succeeding. Each write method documents whether it is cancel-safe.

Implementations

impl SendStream

pub async fn write(&mut self, buf: &[u8]) -> Result<usize, WriteError>

Write a buffer into this stream, returning how many bytes were written

Unless this method errors, it waits until some amount of buf can be written into this stream, and then writes as much as it can without waiting again. Due to congestion and flow control, this may be shorter than buf.len(). On success this yields the length of the prefix that was written.

Cancel safety

This method is cancellation safe. If this does not resolve, no bytes were written.

pub async fn write_all(&mut self, buf: &[u8]) -> Result<(), WriteError>

Write a buffer into this stream in its entirety

This method repeatedly calls write until all bytes are written, or an error occurs.

Cancel safety

This method is not cancellation safe. Even if this does not resolve, some prefix of buf may have been written when previously polled.

pub async fn write_chunks( &mut self, bufs: &mut [Bytes], ) -> Result<Written, WriteError>

Write a slice of Bytes into this stream, returning how much was written

Bytes to try to write are provided to this method as an array of cheaply cloneable chunks. Unless this method errors, it waits until some amount of those bytes can be written into this stream, and then writes as much as it can without waiting again. Due to congestion and flow control, this may be less than the total number of bytes.

On success, this method both mutates bufs and yields an informative Written struct indicating how much was written:

• Bytes chunks that were fully written are mutated to be empty.
• If a Bytes chunk was partially written, it is split to contain only the suffix of bytes that were not written.
• The yielded Written struct indicates how many chunks were fully written as well as how many bytes were written.

Cancel safety

This method is cancellation safe. If this does not resolve, no bytes were written.

pub async fn write_chunk(&mut self, buf: Bytes) -> Result<(), WriteError>

Write a single Bytes into this stream in its entirety

Bytes to write are provided to this method as an single cheaply cloneable chunk. This method repeatedly calls write_chunks until all bytes are written, or an error occurs.

Cancel safety

This method is not cancellation safe. Even if this does not resolve, some bytes may have been written when previously polled.

pub async fn write_all_chunks( &mut self, bufs: &mut [Bytes], ) -> Result<(), WriteError>

Write a slice of Bytes into this stream in its entirety

Bytes to write are provided to this method as an array of cheaply cloneable chunks. This method repeatedly calls write_chunks until all bytes are written, or an error occurs. This method mutates bufs by mutating all chunks to be empty.

Cancel safety

This method is not cancellation safe. Even if this does not resolve, some bytes may have been written when previously polled.

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

Notify the peer that no more data will ever be written to this stream

It is an error to write to a SendStream after finish()ing it. reset() may still be called after finish to abandon transmission of any stream data that might still be buffered.

To wait for the peer to receive all buffered stream data, see stopped().

May fail if finish() or reset() was previously called. This error is harmless and serves only to indicate that the caller may have incorrect assumptions about the stream’s state.

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

Close the send stream immediately.

No new data can be written after calling this method. Locally buffered data is dropped, and previously transmitted data will no longer be retransmitted if lost. If an attempt has already been made to finish the stream, the peer may still receive all written data.

May fail if finish() or reset() was previously called. This error is harmless and serves only to indicate that the caller may have incorrect assumptions about the stream’s state.

pub fn set_priority(&self, priority: i32) -> Result<(), ClosedStream>

Set the priority of the send stream

Every send stream has an initial priority of 0. Locally buffered data from streams with higher priority will be transmitted before data from streams with lower priority. Changing the priority of a stream with pending data may only take effect after that data has been transmitted. Using many different priority levels per connection may have a negative impact on performance.

pub fn priority(&self) -> Result<i32, ClosedStream>

Get the priority of the send stream

pub fn stopped( &self, ) -> impl Future<Output = Result<Option<VarInt>, StoppedError>> + Send + Sync + 'static

Completes when the peer stops the stream or reads the stream to completion

Yields Some with the stop error code if the peer stops the stream. Yields None if the local side finish()es the stream and then the peer acknowledges receipt of all stream data (although not necessarily the processing of it), after which the peer closing the stream is no longer meaningful.

For a variety of reasons, the peer may not send acknowledgements immediately upon receiving data. As such, relying on stopped to know when the peer has read a stream to completion may introduce more latency than using an application-level response of some sort.

pub fn id(&self) -> StreamId

Get the identity of this stream

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

Attempt to write bytes from buf into the stream.

On success, returns Poll::Ready(Ok(num_bytes_written)).

If the stream is not ready for writing, the method returns Poll::Pending and arranges for the current task (via cx.waker().wake_by_ref()) to receive a notification when the stream becomes writable or is closed.

Trait Implementations

impl AsyncWrite for SendStream

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

Attempt to write bytes from buf into the object.

fn poll_flush( self: Pin<&mut SendStream>, _cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>

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

fn poll_shutdown( self: Pin<&mut SendStream>, _cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>

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

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

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.

impl Debug for SendStream

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

Formats the value using the given formatter.

impl Drop for SendStream

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.