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 fn id(&self) -> StreamId

Get the identity of this stream

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

Every 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 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 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_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.

Trait Implementations

impl AsyncWrite for SendStream

async fn write<T: IoBuf>(&mut self, buf: T) -> BufResult<usize, T>

Write some bytes from the buffer into this source and return a BufResult, consisting of the buffer and a usize indicating how many bytes were written.

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

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

async fn shutdown(&mut self) -> Result<()>

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

async fn write_vectored<T>(&mut self, buf: T) -> BufResult<usize, T>

where T: IoVectoredBuf,

Like write, except that it write bytes from a buffer implements IoVectoredBuf into the source.

impl AsyncWrite for SendStream

Available on crate feature io-compat only.

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

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

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

impl Debug for SendStream

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

Formats the value using the given formatter.

impl Drop for SendStream

fn drop(&mut self)

Executes the destructor for this type.