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

文章目录

    • 概述
    • Sink

概述

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

  • Channels
  • Sockets
  • Pipes

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

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

FutureStream一样,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>>;
}

你可能感兴趣的:(rust)