[−][src]Trait futures::sink::Sink

pub trait Sink {
    type SinkItem;
    type SinkError;
    fn poll_ready(
        self: Pin<&mut Self>, 
        lw: &LocalWaker
    ) -> Poll<Result<(), Self::SinkError>>;

    fn start_send(
        self: Pin<&mut Self>, 
        item: Self::SinkItem
    ) -> Result<(), Self::SinkError>;

    fn poll_flush(
        self: Pin<&mut Self>, 
        lw: &LocalWaker
    ) -> Poll<Result<(), Self::SinkError>>;

    fn poll_close(
        self: Pin<&mut Self>, 
        lw: &LocalWaker
    ) -> Poll<Result<(), Self::SinkError>>;
}

A Sink is a value into which other values can be sent, asynchronously.

Basic examples of sinks include the sending side of:

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

type SinkItem

The type of value that the sink accepts.

type SinkError

The type of value produced by the sink when an error occurs.

Loading content...

Required methods

fn poll_ready(
    self: Pin<&mut Self>,
    lw: &LocalWaker
) -> Poll<Result<(), Self::SinkError>>

Attempts to prepare the Sink to receive a value.

This method must be called and return Ok(Poll::Ready(())) 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 Async::Pending, the current task is registered to be notified (via lw.waker()) 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.

fn start_send(
    self: Pin<&mut Self>,
    item: Self::SinkItem
) -> Result<(), Self::SinkError>

Begin the process of sending a value to the sink. Each call to this function must be proceeded by a successful call to poll_ready which returned Ok(Poll::Ready(())).

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.

fn poll_flush(
    self: Pin<&mut Self>,
    lw: &LocalWaker
) -> Poll<Result<(), Self::SinkError>>

Flush any remaining output from this sink.

Returns Ok(Poll::Ready(())) 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 Ok(Async::Pending) if there is more work left to do, in which case the current task is scheduled (via lw.waker()) 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.

fn poll_close(
    self: Pin<&mut Self>,
    lw: &LocalWaker
) -> Poll<Result<(), Self::SinkError>>

Flush any remaining output and close this sink, if necessary.

Returns Ok(Poll::Ready(())) when no buffered items remain and the sink has been successfully closed.

Returns Ok(Async::Pending) if there is more work left to do, in which case the current task is scheduled (via lw.waker()) 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.

Loading content...

Implementations on Foreign Types

impl<Si, U, St, F> Sink for WithFlatMap<Si, U, St, F> where
    F: FnMut(U) -> St,
    Si: Sink,
    St: Stream<Item = Result<<Si as Sink>::SinkItem, <Si as Sink>::SinkError>>, [src]

type SinkItem = U

type SinkError = <Si as Sink>::SinkError

impl<S> Sink for Box<S> where
    S: Sink + Unpin + ?Sized, [src]

type SinkItem = <S as Sink>::SinkItem

type SinkError = <S as Sink>::SinkError

impl<A, B> Sink for Either<A, B> where
    A: Sink,
    B: Sink<SinkItem = <A as Sink>::SinkItem, SinkError = <A as Sink>::SinkError>, [src]

type SinkItem = <A as Sink>::SinkItem

type SinkError = <A as Sink>::SinkError

impl<'a, S> Sink for Pin<&'a mut S> where
    S: Sink + ?Sized, [src]

type SinkItem = <S as Sink>::SinkItem

type SinkError = <S as Sink>::SinkError

impl<T> Sink for VecDeque<T>[src]

type SinkItem = T

type SinkError = VecSinkError

impl<T> Sink for Vec<T>[src]

type SinkItem = T

type SinkError = VecSinkError

impl<'a, S> Sink for &'a mut S where
    S: Sink + Unpin + ?Sized, [src]

type SinkItem = <S as Sink>::SinkItem

type SinkError = <S as Sink>::SinkError

Loading content...

Implementors

impl<'a, T> Sink for &'a UnboundedSender<T>[src]

type SinkItem = T

type SinkError = SendError

impl<Fut, Si> Sink for FlattenSink<Fut, Si> where
    Fut: TryFuture<Ok = Si>,
    Si: Sink<SinkError = <Fut as TryFuture>::Error>, [src]

type SinkItem = <Si as Sink>::SinkItem

type SinkError = <Si as Sink>::SinkError

impl<S> Sink for BufferUnordered<S> where
    S: Stream + Sink,
    <S as Stream>::Item: Future, [src]

type SinkItem = <S as Sink>::SinkItem

type SinkError = <S as Sink>::SinkError

impl<S> Sink for Buffered<S> where
    S: Stream + Sink,
    <S as Stream>::Item: Future, [src]

type SinkItem = <S as Sink>::SinkItem

type SinkError = <S as Sink>::SinkError

impl<S> Sink for Fuse<S> where
    S: Stream + Sink, [src]

type SinkItem = <S as Sink>::SinkItem

type SinkError = <S as Sink>::SinkError

impl<S> Sink for SplitSink<S> where
    S: Sink, [src]

type SinkItem = <S as Sink>::SinkItem

type SinkError = <S as Sink>::SinkError

impl<Si> Sink for Buffer<Si> where
    Si: Sink, [src]

type SinkItem = <Si as Sink>::SinkItem

type SinkError = <Si as Sink>::SinkError

impl<Si, E> Sink for SinkErrInto<Si, E> where
    Si: Sink,
    <Si as Sink>::SinkError: Into<E>, [src]

type SinkItem = <Si as Sink>::SinkItem

type SinkError = E

impl<Si, F, E> Sink for SinkMapErr<Si, F> where
    F: FnOnce(<Si as Sink>::SinkError) -> E,
    Si: Sink, [src]

type SinkItem = <Si as Sink>::SinkItem

type SinkError = E

impl<Si, U, Fut, F, E> Sink for With<Si, U, Fut, F> where
    E: From<<Si as Sink>::SinkError>,
    F: FnMut(U) -> Fut,
    Fut: Future<Output = Result<<Si as Sink>::SinkItem, E>>,
    Si: Sink, [src]

type SinkItem = U

type SinkError = E

impl<Si1, Si2> Sink for Fanout<Si1, Si2> where
    Si1: Sink,
    Si2: Sink<SinkItem = <Si1 as Sink>::SinkItem, SinkError = <Si1 as Sink>::SinkError>,
    <Si1 as Sink>::SinkItem: Clone, [src]

type SinkItem = <Si1 as Sink>::SinkItem

type SinkError = <Si1 as Sink>::SinkError

impl<T> Sink for Sender<T>[src]

type SinkItem = T

type SinkError = SendError

impl<T> Sink for UnboundedSender<T>[src]

type SinkItem = T

type SinkError = SendError

impl<T> Sink for Drain<T>[src]

type SinkItem = T

type SinkError = DrainError

Loading content...