Overview
The futures-sink class library is relatively simple, it only contains one Sinktrait, and the sender included is
- Channels
- Sockets
- Pipes
In addition to such "original" sinks, it is usually possible to layer on top of existing sinks to add features, such as buffering.
In a sense, the value may not be sent in full immediately, so sending to the sink is "asynchronous." Instead, the value is sent in a two-stage manner: first initialize send, and then wait for completion through polling. This two-stage setting is similar to buffered writing in synchronous code, where writing is usually completed successfully immediately, but it is buffered internally, and actually only written when refreshed. In addition, the "sink" may be "full", in which case the sending process cannot even be started.
Like Futureand Stream, Sinktraits are built from some core required methods, as well as many default methods for working in more advanced ways.
The Sink::send_all combinator is particularly important: you can use it to send the entire stream to a sink, which is the easiest way to finally consume the stream.
Sink
"Sink" is a value to which other values can be sent asynchronously.
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>>;
}