结构体 SendStream 

pub struct SendStream { /* private fields */ }

仅可用于发送数据的流

对于尚未显式调用 reset() 的流，在被释放时会被隐式地 finish()，继续（重新）传输此前已写入的数据，直到这些数据被完全确认，或连接被关闭。

取消

当某个 write 方法的 future 在尚未就绪时被丢弃时，如果可以保证没有任何数据被写入到流上，则称该方法是可安全取消的（cancel-safe）。只要有任意的进展就能立即成功的方法属于可安全取消的；而那些内部可能需要执行多次写才能成功的方法则不属于。每个 write 方法的文档都会注明它是否可安全取消。

实现

impl SendStream

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

将一个缓冲区写入该流，并返回实际写入的字节数

除非此方法出错，否则它会一直等到 buf 中的部分字节可以写入该流，然后尽可能多地写入而不再等待。受拥塞控制与流量控制影响，实际写入长度可能小于 buf.len()。成功时返回已写入前缀的长度。

取消安全性

该方法是取消安全的。如果它没有完成，不会写入任何字节。

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

将整个缓冲区完整写入该流

此方法会反复调用 write，直至所有字节写完或发生错误。

取消安全性

该方法不是取消安全的。即使未完成，此前轮询中也可能已经写入了 buf 的某个前缀。

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

将一段 Bytes 切片写入该流，并返回实际写入的数量

待写入的字节以一组廉价可克隆的数据块形式提供。除非此方法出错，否则它会等到部分字节可以写入，然后尽可能多地写入而不再等待。受拥塞控制与流量控制影响，实际写入可能少于总字节数。

成功时，此方法会修改 bufs 并返回一个描述写入情况的 Written 结构体：

• 完全写入的 Bytes 数据块会被修改为空。
• 若某 Bytes 数据块被部分写入，则会切分为只保留尚未写入的后缀字节。
• 返回的 Written 结构体会同时报告完整写入的数据块数和字节数。

取消安全性

该方法是取消安全的。如果未完成，不会写入任何字节。

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

将单个 Bytes 数据块完整写入该流

待写入的字节以单个廉价可克隆的数据块形式提供。此方法会反复调用 write_chunks，直至所有字节写完或发生错误。

取消安全性

该方法不是取消安全的。即使未完成，此前轮询中也可能已经写入了部分字节。

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

将一段 Bytes 切片完整写入该流

待写入的字节以一组廉价可克隆的数据块形式提供。此方法会反复调用 write_chunks，直至所有字节写完或发生错误。此方法会把 bufs 中的所有数据块都修改为空。

取消安全性

该方法不是取消安全的。即使未完成，此前轮询中也可能已经写入了部分字节。

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

通知对端，此后将不会再向该流写入任何数据

在 finish() 之后向 SendStream 写入数据是错误的。在 finish 之后仍可调用 reset() 来丢弃可能仍在缓冲区中的所有流数据。

若需等待对端接收完所有缓冲的流数据，请参阅 stopped()。

如果之前已调用过 finish() 或 reset()，本方法可能失败。该错误无害，仅用于提示调用者可能对流的状态存在错误假设。

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

立即关闭发送流。

调用此方法之后不可再写入任何新数据。本地缓冲的数据将被丢弃，此前已发送的数据若丢失也不会再重传。如果已经调用过 finish，对端仍可能收到全部已写入的数据。

如果之前已调用过 finish() 或 reset()，本方法可能失败。该错误无害，仅用于提示调用者可能对流的状态存在错误假设。

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

设置发送流的优先级

每个发送流的初始优先级为 0。本地缓冲的数据中，优先级较高的流会先于优先级较低的流被发送。修改尚有未发送数据的流的优先级，可能要等到这些数据被发送后才会生效。在每个连接上使用过多不同的优先级等级可能对性能产生负面影响。

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

获取发送流的优先级

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

当对端停止该流或将该流读取完毕时完成

若对端停止该流，则返回带有停止错误码的 Some。若本地端先 finish() 了流，随后对端确认收完所有流数据（虽然不一定已处理完），则返回 None，此后对端关闭流便不再有意义。

出于多种原因，对端在收到数据后未必立即发送确认。因此，依靠 stopped 来判断对端何时将流读至完成，可能比采用某种应用层响应方式引入更大的延迟。

pub fn id(&self) -> StreamId

获取该流的标识

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

尝试将 buf 中的字节写入流中。

成功时返回 Poll::Ready(Ok(num_bytes_written))。

若流暂时不可写，该方法返回 Poll::Pending，并安排当前任务（经由 cx.waker().wake_by_ref()）在流变为可写或被关闭时收到通知。

trait 实现

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_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. 更多信息

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

使用给定的格式化器格式化此值。 更多信息

impl Drop for SendStream

fn drop(&mut self)

执行此类型的析构函数。 更多信息