rust异步编程:futures-rs之futures-sink

概述

futures-sink这个类库比较简单，只包含一个Sink trait,包含的发送方有

• Channels
• Sockets
• Pipes

除了此类“原始”sink之外，通常还可以在现有sink之上分层以添加功能，例如缓冲。

从某种意义上说，可能不会立即完整发送值，因此发送到sink是“异步的”。而是以两阶段的方式发送值：首先初始化send，然后通过轮询等待完成。此两阶段设置类似于同步代码中的buffered writing，其中写入通常会立即成功完成，但是内部会被缓冲，并且实际上仅在刷新时才被写入。另外“sink”可能是“已满”的，在这种情况下甚至无法启动发送过程。

与Future和Stream一样，Sink trait是由一些核心必需方法构建的，以及许多用于更高级方式工作的默认方法。

Sink::send_all组合器特别重要：您可以使用它将整个流发送到一个sink中，这是最终消费流的最简单方法。

Sink

“Sink”是一个值，可以将其他值异步发送到该值中。

pub trait Sink<Item> {
    /// The type of value produced by the sink when an error occurs.
    type Error;

    /// 尝试准备Sink以接收值
    /// 此方法必须返回 `Poll::Ready(Ok(()))`才能调用`start_send`
    /// 一旦底层sink准备好接收数据，此方法将返回`Poll :: Ready`
    /// 如果此方法返回`Poll :: Pending`，则当再次调用`poll_ready`时，当前任务将被通知（via `cx.waker().wake_by_ref()`）
    /// 在大多数情况下，如果sink遇到错误，sink将永久无法接收item
    fn poll_ready(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;

    /// 开始将值发送到sink的过程
    /// 每次对该函数的调用之前，都必须成功调用`poll_ready`并返回`Poll::Ready(Ok(()))`
    /// 顾名思义，此方法仅仅是开始发送item的过程。
    /// 如果sink采用了缓冲，则在缓冲区被完全清空之前，item不会得到完全处理。
    /// 由于sink旨在与异步I/O一起使用，因此实际将数据写到基础对象的过程是异步进行的。 
    /// 您*必须*使用`poll_flush`或`poll_close`，以确保发送完成。
    fn start_send(self: Pin<&mut Self>, item: Item) -> Result<(), Self::Error>;

    /// flush该sink的所有剩余的数据。
    /// 当没有缓冲的item时， 返回`Poll::Ready(Ok(()))` 
    /// 如果返回此值，则可以确保已flush所有通过`start_send`发送的值。
    /// 如果还有更多工作要做，则返回`Poll::Pending`，在这种情况下，当前任务被暂时挂起，等待被唤醒（via `cx.waker().wake_by_ref()`），唤醒后`poll_flush`将被再次调用。  
    /// 在大多数情况下，如果sink遇到错误，sink将永久无法接收item
    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;

    /// flush该sink的所有剩余的数据，并关闭sink.
    /// 当没有缓冲的item时并成功关闭时， 返回`Poll::Ready(Ok(()))` 
    /// 如果还有更多工作要做，则返回`Poll::Pending`，在这种情况下，当前任务被暂时挂起，等待被唤醒（via `cx.waker().wake_by_ref()`），唤醒后`poll_close`将被再次调用。 
    fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;
}