Struct SendStream

pub struct SendStream { /* private fields */ }

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 bytes to the stream

Yields the number of bytes written on success. Congestion and flow control may cause this to be shorter than buf.len(), indicating that only a prefix of buf was written.

This operation is cancel-safe.

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

Convenience method to write an entire buffer to the stream

This operation is not cancel-safe.

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

Write chunks to the stream

Yields the number of bytes and chunks written on success. Congestion and flow control may cause this to be shorter than buf.len(), indicating that only a prefix of bufs was written

This operation is cancel-safe.

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

Convenience method to write a single chunk in its entirety to the stream

This operation is not cancel-safe.

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

Convenience method to write an entire list of chunks to the stream

This operation is not cancel-safe.

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 async fn stopped(&mut self) -> Result<Option<VarInt>, StoppedError>

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.