Trait futures_util::sink::Sink
source · [−]pub trait Sink<Item> {
type Error;
fn poll_ready(
self: Pin<&mut Self>,
cx: &mut Context<'_>
) -> Poll<Result<(), Self::Error>>;
fn start_send(self: Pin<&mut Self>, item: Item) -> Result<(), Self::Error>;
fn poll_flush(
self: Pin<&mut Self>,
cx: &mut Context<'_>
) -> Poll<Result<(), Self::Error>>;
fn poll_close(
self: Pin<&mut Self>,
cx: &mut Context<'_>
) -> Poll<Result<(), Self::Error>>;
}
sink
only.Expand description
A Sink
is a value into which other values can be sent, asynchronously.
Basic examples of sinks include the sending side of:
- Channels
- Sockets
- Pipes
In addition to such “primitive” sinks, it’s typical to layer additional functionality, such as buffering, on top of an existing sink.
Sending to a sink is “asynchronous” in the sense that the value may not be sent in its entirety immediately. Instead, values are sent in a two-phase way: first by initiating a send, and then by polling for completion. This two-phase setup is analogous to buffered writing in synchronous code, where writes often succeed immediately, but internally are buffered and are actually written only upon flushing.
In addition, the Sink
may be full, in which case it is not even possible
to start the sending process.
As with Future
and Stream
, the Sink
trait is built from a few core
required methods, and a host of default methods for working in a
higher-level way. The Sink::send_all
combinator is of particular
importance: you can use it to send an entire stream to a sink, which is
the simplest way to ultimately consume a stream.
Associated Types
Required methods
Attempts to prepare the Sink
to receive a value.
This method must be called and return Poll::Ready(Ok(()))
prior to
each call to start_send
.
This method returns Poll::Ready
once the underlying sink is ready to
receive data. If this method returns Poll::Pending
, the current task
is registered to be notified (via cx.waker().wake_by_ref()
) when poll_ready
should be called again.
In most cases, if the sink encounters an error, the sink will permanently be unable to receive items.
Begin the process of sending a value to the sink.
Each call to this function must be preceded by a successful call to
poll_ready
which returned Poll::Ready(Ok(()))
.
As the name suggests, this method only begins the process of sending
the item. If the sink employs buffering, the item isn’t fully processed
until the buffer is fully flushed. Since sinks are designed to work with
asynchronous I/O, the process of actually writing out the data to an
underlying object takes place asynchronously. You must use
poll_flush
or poll_close
in order to guarantee completion of a
send.
Implementations of poll_ready
and start_send
will usually involve
flushing behind the scenes in order to make room for new messages.
It is only necessary to call poll_flush
if you need to guarantee that
all of the items placed into the Sink
have been sent.
In most cases, if the sink encounters an error, the sink will permanently be unable to receive items.
Flush any remaining output from this sink.
Returns Poll::Ready(Ok(()))
when no buffered items remain. If this
value is returned then it is guaranteed that all previous values sent
via start_send
have been flushed.
Returns Poll::Pending
if there is more work left to do, in which
case the current task is scheduled (via cx.waker().wake_by_ref()
) to wake up when
poll_flush
should be called again.
In most cases, if the sink encounters an error, the sink will permanently be unable to receive items.
Flush any remaining output and close this sink, if necessary.
Returns Poll::Ready(Ok(()))
when no buffered items remain and the sink
has been successfully closed.
Returns Poll::Pending
if there is more work left to do, in which
case the current task is scheduled (via cx.waker().wake_by_ref()
) to wake up when
poll_close
should be called again.
If this function encounters an error, the sink should be considered to
have failed permanently, and no more Sink
methods should be called.
Implementations on Foreign Types
sourceimpl<P, Item> Sink<Item> for Pin<P> where
P: DerefMut + Unpin,
<P as Deref>::Target: Sink<Item>,
impl<P, Item> Sink<Item> for Pin<P> where
P: DerefMut + Unpin,
<P as Deref>::Target: Sink<Item>,
type Error = <<P as Deref>::Target as Sink<Item>>::Error
pub fn poll_ready(
self: Pin<&mut Pin<P>>,
cx: &mut Context<'_>
) -> Poll<Result<(), <Pin<P> as Sink<Item>>::Error>>
pub fn start_send(
self: Pin<&mut Pin<P>>,
item: Item
) -> Result<(), <Pin<P> as Sink<Item>>::Error>
pub fn poll_flush(
self: Pin<&mut Pin<P>>,
cx: &mut Context<'_>
) -> Poll<Result<(), <Pin<P> as Sink<Item>>::Error>>
pub fn poll_close(
self: Pin<&mut Pin<P>>,
cx: &mut Context<'_>
) -> Poll<Result<(), <Pin<P> as Sink<Item>>::Error>>
sourceimpl<'_, S, Item> Sink<Item> for &'_ mut S where
S: Sink<Item> + Unpin + ?Sized,
impl<'_, S, Item> Sink<Item> for &'_ mut S where
S: Sink<Item> + Unpin + ?Sized,
type Error = <S as Sink<Item>>::Error
pub fn poll_ready(
self: Pin<&mut &'_ mut S>,
cx: &mut Context<'_>
) -> Poll<Result<(), <&'_ mut S as Sink<Item>>::Error>>
pub fn start_send(
self: Pin<&mut &'_ mut S>,
item: Item
) -> Result<(), <&'_ mut S as Sink<Item>>::Error>
pub fn poll_flush(
self: Pin<&mut &'_ mut S>,
cx: &mut Context<'_>
) -> Poll<Result<(), <&'_ mut S as Sink<Item>>::Error>>
pub fn poll_close(
self: Pin<&mut &'_ mut S>,
cx: &mut Context<'_>
) -> Poll<Result<(), <&'_ mut S as Sink<Item>>::Error>>
Implementors
sourceimpl<A, B, Item> Sink<Item> for Either<A, B> where
A: Sink<Item>,
B: Sink<Item, Error = A::Error>,
impl<A, B, Item> Sink<Item> for Either<A, B> where
A: Sink<Item>,
B: Sink<Item, Error = A::Error>,
sourceimpl<S, Fut, F, Item> Sink<Item> for Filter<S, Fut, F> where
S: Stream + Sink<Item>,
F: FnMut(&S::Item) -> Fut,
Fut: Future<Output = bool>,
impl<S, Fut, F, Item> Sink<Item> for Filter<S, Fut, F> where
S: Stream + Sink<Item>,
F: FnMut(&S::Item) -> Fut,
Fut: Future<Output = bool>,
sourceimpl<S, Fut, F, Item> Sink<Item> for FilterMap<S, Fut, F> where
S: Stream + Sink<Item>,
F: FnMut1<S::Item, Output = Fut>,
Fut: Future,
impl<S, Fut, F, Item> Sink<Item> for FilterMap<S, Fut, F> where
S: Stream + Sink<Item>,
F: FnMut1<S::Item, Output = Fut>,
Fut: Future,
sourceimpl<S, Fut, F, Item> Sink<Item> for SkipWhile<S, Fut, F> where
S: Stream + Sink<Item>,
F: FnMut(&S::Item) -> Fut,
Fut: Future<Output = bool>,
impl<S, Fut, F, Item> Sink<Item> for SkipWhile<S, Fut, F> where
S: Stream + Sink<Item>,
F: FnMut(&S::Item) -> Fut,
Fut: Future<Output = bool>,
sourceimpl<S, Fut, F, Item> Sink<Item> for TryFilterMap<S, Fut, F> where
S: Sink<Item>,
impl<S, Fut, F, Item> Sink<Item> for TryFilterMap<S, Fut, F> where
S: Sink<Item>,
sourceimpl<S, Fut, F, Item, E> Sink<Item> for TryFilter<S, Fut, F> where
S: TryStream + Sink<Item, Error = E>,
impl<S, Fut, F, Item, E> Sink<Item> for TryFilter<S, Fut, F> where
S: TryStream + Sink<Item, Error = E>,
type Error = E
sourceimpl<S, Fut, F, Item, E> Sink<Item> for TrySkipWhile<S, Fut, F> where
S: TryStream + Sink<Item, Error = E>,
impl<S, Fut, F, Item, E> Sink<Item> for TrySkipWhile<S, Fut, F> where
S: TryStream + Sink<Item, Error = E>,
type Error = E
sourceimpl<S, Fut, F, Item, E> Sink<Item> for TryTakeWhile<S, Fut, F> where
S: TryStream + Sink<Item, Error = E>,
impl<S, Fut, F, Item, E> Sink<Item> for TryTakeWhile<S, Fut, F> where
S: TryStream + Sink<Item, Error = E>,
type Error = E
sourceimpl<S, Fut, Item> Sink<Item> for TakeUntil<S, Fut> where
S: Stream + Sink<Item>,
Fut: Future,
impl<S, Fut, Item> Sink<Item> for TakeUntil<S, Fut> where
S: Stream + Sink<Item>,
Fut: Future,
sourceimpl<S, Item> Sink<Item> for BufferUnordered<S> where
S: Stream + Sink<Item>,
S::Item: Future,
impl<S, Item> Sink<Item> for BufferUnordered<S> where
S: Stream + Sink<Item>,
S::Item: Future,
sourceimpl<S, Item> Sink<Item> for ReadyChunks<S> where
S: Stream + Sink<Item>,
impl<S, Item> Sink<Item> for ReadyChunks<S> where
S: Stream + Sink<Item>,
sourceimpl<S, Item> Sink<Item> for TryFlatten<S> where
S: TryStream + Sink<Item>,
impl<S, Item> Sink<Item> for TryFlatten<S> where
S: TryStream + Sink<Item>,
sourceimpl<S, Item, E> Sink<Item> for TryBufferUnordered<S> where
S: TryStream + Sink<Item, Error = E>,
S::Ok: TryFuture<Error = E>,
impl<S, Item, E> Sink<Item> for TryBufferUnordered<S> where
S: TryStream + Sink<Item, Error = E>,
S::Ok: TryFuture<Error = E>,
type Error = E
sourceimpl<S, Item, E> Sink<Item> for TryBuffered<S> where
S: TryStream + Sink<Item, Error = E>,
S::Ok: TryFuture<Error = E>,
impl<S, Item, E> Sink<Item> for TryBuffered<S> where
S: TryStream + Sink<Item, Error = E>,
S::Ok: TryFuture<Error = E>,
type Error = E
sourceimpl<S, SinkItem> Sink<SinkItem> for Compat01As03Sink<S, SinkItem> where
S: Sink01<SinkItem = SinkItem>,
This is supported on crate feature compat
only.
impl<S, SinkItem> Sink<SinkItem> for Compat01As03Sink<S, SinkItem> where
S: Sink01<SinkItem = SinkItem>,
compat
only.sourceimpl<Si1, Si2, Item> Sink<Item> for Fanout<Si1, Si2> where
Si1: Sink<Item>,
Item: Clone,
Si2: Sink<Item, Error = Si1::Error>,
impl<Si1, Si2, Item> Sink<Item> for Fanout<Si1, Si2> where
Si1: Sink<Item>,
Item: Clone,
Si2: Sink<Item, Error = Si1::Error>,
sourceimpl<Si, F, E, Item> Sink<Item> for SinkMapErr<Si, F> where
Si: Sink<Item>,
F: FnOnce(Si::Error) -> E,
impl<Si, F, E, Item> Sink<Item> for SinkMapErr<Si, F> where
Si: Sink<Item>,
F: FnOnce(Si::Error) -> E,
type Error = E
sourceimpl<Si, Item, E> Sink<Item> for SinkErrInto<Si, Item, E> where
Si: Sink<Item>,
Si::Error: Into<E>,
impl<Si, Item, E> Sink<Item> for SinkErrInto<Si, Item, E> where
Si: Sink<Item>,
Si::Error: Into<E>,
type Error = E
sourceimpl<Si, Item, U, Fut, F, E> Sink<U> for With<Si, Item, U, Fut, F> where
Si: Sink<Item>,
F: FnMut(U) -> Fut,
Fut: Future<Output = Result<Item, E>>,
E: From<Si::Error>,
impl<Si, Item, U, Fut, F, E> Sink<U> for With<Si, Item, U, Fut, F> where
Si: Sink<Item>,
F: FnMut(U) -> Fut,
Fut: Future<Output = Result<Item, E>>,
E: From<Si::Error>,
type Error = E
sourceimpl<Si, Item, U, St, F> Sink<U> for WithFlatMap<Si, Item, U, St, F> where
Si: Sink<Item>,
F: FnMut(U) -> St,
St: Stream<Item = Result<Item, Si::Error>>,
impl<Si, Item, U, St, F> Sink<U> for WithFlatMap<Si, Item, U, St, F> where
Si: Sink<Item>,
F: FnMut(U) -> St,
St: Stream<Item = Result<Item, Si::Error>>,
sourceimpl<St, F, Item> Sink<Item> for Map<St, F> where
St: Stream + Sink<Item>,
F: FnMut1<St::Item>,
impl<St, F, Item> Sink<Item> for Map<St, F> where
St: Stream + Sink<Item>,
F: FnMut1<St::Item>,
sourceimpl<T, F, R, Item, E> Sink<Item> for Unfold<T, F, R> where
F: FnMut(T, Item) -> R,
R: Future<Output = Result<T, E>>,
impl<T, F, R, Item, E> Sink<Item> for Unfold<T, F, R> where
F: FnMut(T, Item) -> R,
R: Future<Output = Result<T, E>>,
type Error = E
sourceimpl<W: AsyncWrite, Item: AsRef<[u8]>> Sink<Item> for IntoSink<W, Item>
This is supported on crate feature io
only.
impl<W: AsyncWrite, Item: AsRef<[u8]>> Sink<Item> for IntoSink<W, Item>
io
only.