Trait Sink 

pub trait Sink<Item> {
    type Error;

    // Required methods
    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>>;
}

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.

Required Associated Types

type Error

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

Required Methods

fn poll_ready( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<(), Self::Error>>

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.

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

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.

fn poll_flush( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<(), Self::Error>>

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.

fn poll_close( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<(), Self::Error>>

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

impl<'a, T> Sink<T> for SendSink<'a, T>

type Error = SendError<T>

fn poll_ready( self: Pin<&mut SendSink<'a, T>>, cx: &mut Context<'_>, ) -> Poll<Result<(), <SendSink<'a, T> as Sink<T>>::Error>>

fn start_send( self: Pin<&mut SendSink<'a, T>>, item: T, ) -> Result<(), <SendSink<'a, T> as Sink<T>>::Error>

fn poll_flush( self: Pin<&mut SendSink<'a, T>>, cx: &mut Context<'_>, ) -> Poll<Result<(), <SendSink<'a, T> as Sink<T>>::Error>>

fn poll_close( self: Pin<&mut SendSink<'a, T>>, cx: &mut Context<'_>, ) -> Poll<Result<(), <SendSink<'a, T> as Sink<T>>::Error>>

impl<L, R, Item, Error> Sink<Item> for Either<L, R>

where L: Sink<Item, Error = Error>, R: Sink<Item, Error = Error>,

type Error = Error

fn poll_ready( self: Pin<&mut Either<L, R>>, cx: &mut Context<'_>, ) -> Poll<Result<(), <Either<L, R> as Sink<Item>>::Error>>

fn start_send( self: Pin<&mut Either<L, R>>, item: Item, ) -> Result<(), <Either<L, R> as Sink<Item>>::Error>

fn poll_flush( self: Pin<&mut Either<L, R>>, cx: &mut Context<'_>, ) -> Poll<Result<(), <Either<L, R> as Sink<Item>>::Error>>

fn poll_close( self: Pin<&mut Either<L, R>>, cx: &mut Context<'_>, ) -> Poll<Result<(), <Either<L, R> as Sink<Item>>::Error>>

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

fn poll_ready( self: Pin<&mut Pin<P>>, cx: &mut Context<'_>, ) -> Poll<Result<(), <Pin<P> as Sink<Item>>::Error>>

fn start_send( self: Pin<&mut Pin<P>>, item: Item, ) -> Result<(), <Pin<P> as Sink<Item>>::Error>

fn poll_flush( self: Pin<&mut Pin<P>>, cx: &mut Context<'_>, ) -> Poll<Result<(), <Pin<P> as Sink<Item>>::Error>>

fn poll_close( self: Pin<&mut Pin<P>>, cx: &mut Context<'_>, ) -> Poll<Result<(), <Pin<P> as Sink<Item>>::Error>>

impl<S, Item> Sink<Item> for &mut S

where S: Sink<Item> + Unpin + ?Sized,

type Error = <S as Sink<Item>>::Error

fn poll_ready( self: Pin<&mut &mut S>, cx: &mut Context<'_>, ) -> Poll<Result<(), <&mut S as Sink<Item>>::Error>>

fn start_send( self: Pin<&mut &mut S>, item: Item, ) -> Result<(), <&mut S as Sink<Item>>::Error>

fn poll_flush( self: Pin<&mut &mut S>, cx: &mut Context<'_>, ) -> Poll<Result<(), <&mut S as Sink<Item>>::Error>>

fn poll_close( self: Pin<&mut &mut S>, cx: &mut Context<'_>, ) -> Poll<Result<(), <&mut S as Sink<Item>>::Error>>

impl<T> Sink<T> for PollSender<T>

where T: Send,

type Error = PollSendError<T>

fn poll_ready( self: Pin<&mut PollSender<T>>, cx: &mut Context<'_>, ) -> Poll<Result<(), <PollSender<T> as Sink<T>>::Error>>

fn poll_flush( self: Pin<&mut PollSender<T>>, _cx: &mut Context<'_>, ) -> Poll<Result<(), <PollSender<T> as Sink<T>>::Error>>

fn start_send( self: Pin<&mut PollSender<T>>, item: T, ) -> Result<(), <PollSender<T> as Sink<T>>::Error>

fn poll_close( self: Pin<&mut PollSender<T>>, _cx: &mut Context<'_>, ) -> Poll<Result<(), <PollSender<T> as Sink<T>>::Error>>

Implementors

impl<'a, S> Sink<&'a [u8]> for CopyToBytes<S>

where S: Sink<Bytes>,

type Error = <S as Sink<Bytes>>::Error

impl<A, B, Item> Sink<Item> for rama::futures::prelude::future::Either<A, B>

where A: Sink<Item>, B: Sink<Item, Error = <A as Sink<Item>>::Error>,

Available on crate feature sink only.

type Error = <A as Sink<Item>>::Error

impl<I, C, S> Sink<(I, SocketAddr)> for UdpFramedRelay<C, S>

where C: Encoder<I>, <C as Encoder<I>>::Error: Into<Box<dyn Error + Send + Sync>>, S: Stream + Unpin,

type Error = Box<dyn Error + Send + Sync>

impl<I, C, T> Sink<(I, SocketAddr)> for UdpFramed<C, T>

where T: Borrow<UdpSocket>, C: Encoder<I>,

type Error = <C as Encoder<I>>::Error

impl<I, C, T> Sink<(I, UnixSocketAddress)> for UnixDatagramFramed<C, T>

where T: Borrow<UnixDatagram>, C: Encoder<I>,

type Error = <C as Encoder<I>>::Error

impl<I, T> Sink<I> for WithContext<T>

where T: Sink<I>,

type Error = <T as Sink<I>>::Error

impl<S, B, E, T> Sink<T> for StreamReader<S, B>

where S: Sink<T, Error = E>,

type Error = E

impl<S, Fut, F, Item> Sink<Item> for AndThen<S, Fut, F>

where S: Sink<Item>,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Fut, F, Item> Sink<Item> for Filter<S, Fut, F>

where S: Stream + Sink<Item>, F: FnMut(&<S as Stream>::Item) -> Fut, Fut: Future<Output = bool>,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Fut, F, Item> Sink<Item> for FilterMap<S, Fut, F>

where S: Stream + Sink<Item>, F: FnMut1<<S as Stream>::Item, Output = Fut>, Fut: Future,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Fut, F, Item> Sink<Item> for OrElse<S, Fut, F>

where S: Sink<Item>,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Fut, F, Item> Sink<Item> for SkipWhile<S, Fut, F>

where S: Stream + Sink<Item>, F: FnMut(&<S as Stream>::Item) -> Fut, Fut: Future<Output = bool>,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Fut, F, Item> Sink<Item> for TakeWhile<S, Fut, F>

where S: Stream + Sink<Item>,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Fut, F, Item> Sink<Item> for Then<S, Fut, F>

where S: Sink<Item>,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Fut, F, Item> Sink<Item> for TryFilterMap<S, Fut, F>

where S: Sink<Item>,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Fut, F, Item, E> Sink<Item> for TryFilter<S, Fut, F>

where S: TryStream + Sink<Item, Error = E>,

Available on crate feature sink only.

type Error = E

impl<S, Fut, F, Item, E> Sink<Item> for TrySkipWhile<S, Fut, F>

where S: TryStream + Sink<Item, Error = E>,

Available on crate feature sink only.

type Error = E

impl<S, Fut, F, Item, E> Sink<Item> for TryTakeWhile<S, Fut, F>

where S: TryStream + Sink<Item, Error = E>,

Available on crate feature sink only.

type Error = E

impl<S, Fut, Item> Sink<Item> for TakeUntil<S, Fut>

where S: Stream + Sink<Item>, Fut: Future,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Item> Sink<Item> for Box<S>

where S: Sink<Item> + Unpin + ?Sized,

type Error = <S as Sink<Item>>::Error

impl<S, Item> Sink<Item> for BufferUnordered<S>

where S: Stream + Sink<Item>, <S as Stream>::Item: Future,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Item> Sink<Item> for Buffered<S>

where S: Stream + Sink<Item>, <S as Stream>::Item: Future,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Item> Sink<Item> for Chunks<S>

where S: Stream + Sink<Item>,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Item> Sink<Item> for Enumerate<S>

where S: Stream + Sink<Item>,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Item> Sink<Item> for Fuse<S>

where S: Stream + Sink<Item>,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Item> Sink<Item> for IntoStream<S>

where S: Sink<Item>,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Item> Sink<Item> for Peekable<S>

where S: Sink<Item> + Stream,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Item> Sink<Item> for ReadyChunks<S>

where S: Stream + Sink<Item>,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Item> Sink<Item> for Skip<S>

where S: Stream + Sink<Item>,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Item> Sink<Item> for SplitSink<S, Item>

where S: Sink<Item>,

type Error = <S as Sink<Item>>::Error

impl<S, Item> Sink<Item> for Take<S>

where S: Stream + Sink<Item>,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Item> Sink<Item> for TryChunks<S>

where S: TryStream + Sink<Item>,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Item> Sink<Item> for TryFlatten<S>

where S: TryStream + Sink<Item>,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Item> Sink<Item> for TryReadyChunks<S>

where S: TryStream + Sink<Item>,

Available on crate feature sink only.

type Error = <S as Sink<Item>>::Error

impl<S, Item, E> Sink<Item> for TryBufferUnordered<S>

where S: TryStream + Sink<Item, Error = E>, <S as TryStream>::Ok: TryFuture<Error = E>,

Available on crate feature sink only.

type Error = E

impl<S, Item, E> Sink<Item> for TryBuffered<S>

where S: TryStream + Sink<Item, Error = E>, <S as TryStream>::Ok: TryFuture<Error = E>,

Available on crate feature sink only.

type Error = E

impl<Si1, Si2, Item> Sink<Item> for Fanout<Si1, Si2>

where Si1: Sink<Item>, Item: Clone, Si2: Sink<Item, Error = <Si1 as Sink<Item>>::Error>,

type Error = <Si1 as Sink<Item>>::Error

impl<Si, F, E, Item> Sink<Item> for SinkMapErr<Si, F>

where Si: Sink<Item>, F: FnOnce(<Si as Sink<Item>>::Error) -> E,

type Error = E

impl<Si, Item> Sink<Item> for Buffer<Si, Item>

where Si: Sink<Item>,

type Error = <Si as Sink<Item>>::Error

impl<Si, Item, E> Sink<Item> for SinkErrInto<Si, Item, E>

where Si: Sink<Item>, <Si as Sink<Item>>::Error: Into<E>,

type Error = E

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 as Sink<Item>>::Error>,

type Error = E

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 as Sink<Item>>::Error>>,

type Error = <Si as Sink<Item>>::Error

impl<St, F, Item> Sink<Item> for Map<St, F>

where St: Stream + Sink<Item>, F: FnMut1<<St as Stream>::Item>,

Available on crate feature sink only.

type Error = <St as Sink<Item>>::Error

impl<St, S, Fut, F, Item> Sink<Item> for Scan<St, S, Fut, F>

where St: Stream + Sink<Item>,

Available on crate feature sink only.

type Error = <St as Sink<Item>>::Error

impl<T> Sink<Message> for AsyncWebSocket<T>

where T: Stream + Unpin,

type Error = ProtocolError

impl<T> Sink<T> for &UnboundedSender<T>

type Error = SendError

impl<T> Sink<T> for VecDeque<T>

type Error = Infallible

impl<T> Sink<T> for Vec<T>

type Error = Infallible

impl<T> Sink<T> for Sender<T>

type Error = SendError

impl<T> Sink<T> for UnboundedSender<T>

type Error = SendError

impl<T> Sink<T> for Drain<T>

type Error = Infallible

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

impl<T, I, D> Sink<I> for FramedRead<T, D>

where T: Sink<I>,

type Error = <T as Sink<I>>::Error

impl<T, I, E> Sink<I> for FramedWrite<T, E>

where T: AsyncWrite, E: Encoder<I>, <E as Encoder<I>>::Error: From<Error>,

type Error = <E as Encoder<I>>::Error

impl<T, I, U> Sink<I> for Framed<T, U>

where T: AsyncWrite, U: Encoder<I>, <U as Encoder<I>>::Error: From<Error>,

type Error = <U as Encoder<I>>::Error

impl<W, Item> Sink<Item> for IntoSink<W, Item>

where W: AsyncWrite, Item: AsRef<[u8]>,

type Error = Error

impl<_Item, F> Sink<_Item> for FlattenStream<F>

where Flatten<F, <F as Future>::Output>: Sink<_Item>, F: Future,

Available on crate feature sink only.

type Error = <Flatten<F, <F as Future>::Output> as Sink<_Item>>::Error

impl<_Item, Fut> Sink<_Item> for TryFlattenStream<Fut>

where TryFlatten<Fut, <Fut as TryFuture>::Ok>: Sink<_Item>, Fut: TryFuture,

Available on crate feature sink only.

type Error = <TryFlatten<Fut, <Fut as TryFuture>::Ok> as Sink<_Item>>::Error

impl<_Item, Fut, Si> Sink<_Item> for FlattenSink<Fut, Si>

where TryFlatten<Fut, Si>: Sink<_Item>,

Available on crate feature sink only.

type Error = <TryFlatten<Fut, Si> as Sink<_Item>>::Error

impl<_Item, St> Sink<_Item> for Flatten<St>

where Flatten<St, <St as Stream>::Item>: Sink<_Item>, St: Stream,

Available on crate feature sink only.

type Error = <Flatten<St, <St as Stream>::Item> as Sink<_Item>>::Error

impl<_Item, St> Sink<_Item> for TryFlattenUnordered<St>

where FlattenUnorderedWithFlowController<NestedTryStreamIntoEitherTryStream<St>, PropagateBaseStreamError<St>>: Sink<_Item>, St: TryStream, <St as TryStream>::Ok: TryStream + Unpin, <<St as TryStream>::Ok as TryStream>::Error: From<<St as TryStream>::Error>,

Available on crate feature sink only.

type Error = <FlattenUnorderedWithFlowController<NestedTryStreamIntoEitherTryStream<St>, PropagateBaseStreamError<St>> as Sink<_Item>>::Error

impl<_Item, St, E> Sink<_Item> for ErrInto<St, E>

where MapErr<St, IntoFn<E>>: Sink<_Item>,

Available on crate feature sink only.

type Error = <MapErr<St, IntoFn<E>> as Sink<_Item>>::Error

impl<_Item, St, F> Sink<_Item> for Inspect<St, F>

where Map<St, InspectFn<F>>: Sink<_Item>,

Available on crate feature sink only.

type Error = <Map<St, InspectFn<F>> as Sink<_Item>>::Error

impl<_Item, St, F> Sink<_Item> for InspectErr<St, F>

where Inspect<IntoStream<St>, InspectErrFn<F>>: Sink<_Item>,

Available on crate feature sink only.

type Error = <Inspect<IntoStream<St>, InspectErrFn<F>> as Sink<_Item>>::Error

impl<_Item, St, F> Sink<_Item> for InspectOk<St, F>

where Inspect<IntoStream<St>, InspectOkFn<F>>: Sink<_Item>,

Available on crate feature sink only.

type Error = <Inspect<IntoStream<St>, InspectOkFn<F>> as Sink<_Item>>::Error

impl<_Item, St, F> Sink<_Item> for MapErr<St, F>

where Map<IntoStream<St>, MapErrFn<F>>: Sink<_Item>,

Available on crate feature sink only.

type Error = <Map<IntoStream<St>, MapErrFn<F>> as Sink<_Item>>::Error

impl<_Item, St, F> Sink<_Item> for MapOk<St, F>

where Map<IntoStream<St>, MapOkFn<F>>: Sink<_Item>,

Available on crate feature sink only.

type Error = <Map<IntoStream<St>, MapOkFn<F>> as Sink<_Item>>::Error

impl<_Item, St, U, F> Sink<_Item> for FlatMap<St, U, F>

where Flatten<Map<St, F>, U>: Sink<_Item>,

Available on crate feature sink only.

type Error = <Flatten<Map<St, F>, U> as Sink<_Item>>::Error

impl<_Item, St, U, F> Sink<_Item> for FlatMapUnordered<St, U, F>

where FlattenUnorderedWithFlowController<Map<St, F>, ()>: Sink<_Item>, St: Stream, U: Stream + Unpin, F: FnMut(<St as Stream>::Item) -> U,

Available on crate feature sink only.

type Error = <FlattenUnorderedWithFlowController<Map<St, F>, ()> as Sink<_Item>>::Error