Struct SendStream 

pub struct SendStream { /* private fields */ }

noq types that are used in the public iroh API. 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>

Available on crate feature qlog only.

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>

Available on crate feature qlog only.

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_many_chunks( &mut self, bufs: &mut &mut [Bytes], ) -> Result<usize, WriteError>

Available on crate feature qlog only.

Writes [Bytes] from a slice of buffers into this stream.

Returns how many bytes were 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 returns the number of bytes written:

• bufs is advanced past chunks that were fully written.
• If a [Bytes] chunk was partially written, the chunk at the new front of bufs is split to contain only the suffix of bytes that were not 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>

Available on crate feature qlog only.

Writes a single [Bytes] into this stream in its entirety.

Bytes to write are provided to this method as a single cheaply cloneable chunk. This method repeatedly calls write_many_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>

Available on crate feature qlog only.

Writes 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_many_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 fn finish(&mut self) -> Result<(), ClosedStream>

Available on crate feature qlog only.

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>

Available on crate feature qlog only.

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>

Available on crate feature qlog only.

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>

Available on crate feature qlog only.

Get the priority of the send stream

pub fn stopped(&self) -> Stopped

Available on crate feature qlog only.

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.

Clients may wish to await this after finishing a unidirectional 0-RTT stream to reliably determine whether the stream was rejected.

pub fn id(&self) -> StreamId

Available on crate feature qlog only.

Get the identity of this stream

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

Available on crate feature qlog only.

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.