Struct SometimesUnboundedSink 

pub(crate) struct SometimesUnboundedSink<T, S> {
    buf: VecDeque<T>,
    inner: S,
}

Wraps a Sink, providing an only-sometimes-used unbounded buffer

For example, consider SometimesUnboundedSink<T, mpsc::Receiver>. The Receiver is not always ready for writing: if the capacity is exceeded, send will block.

SometimesUnboundedSink’s Sink implementation works the same way. But there are also two methods pollish_send_unbounded and send_unbounded which will always succeed immediately. Items which the underlying sink S is not ready to accept are queued, and will be delivered to S when possible.

You must poll this type

For queued items to be delivered, SometimesUnboundedSink must be polled, even if you don’t have an item to send.

You can use Sink::poll_ready for this. Any Context-taking methods is suitable.

(This is a difference between SometimesUnboundedSink and mpsc::UnboundedSender: UnboundedSender::unbounded_send does not require a flush operation. In this way, SometimesUnboundedSink::send_unbounded behaves more like Sink::start_send, which does require a subsequent flush.)

Error handling

Errors from the underlying sink may not be reported immediately, due to the buffering in SometimesUnboundedSink.

However, if the sink reports errors from poll_ready these will surface in a timely fashion.

After an error has been reported, there may still be buffered data, which will only be delivered if SometimesUnboundedSink is polled again (and the error in the underlying sink was transient).

Fields

buf: VecDeque<T>

Things we couldn’t send_unbounded right away

Invariants:

• Everything here must be fed to inner before any further user data (unbounded user data may be appended).

• If this is nonempty, the executor knows to wake this task. This is achieved as follows: If this is nonempty, inner.poll_ready() has been called.

inner: S

The actual sink

This also has the relevant Waker.

Waker invariant

Whenever either

• The last call to any of our public methods returned Pending, or
• buf is nonempty,

the last method call inner also returned Pending. (Or, we have reported an error.)

So, in those situations, this task has been recorded for wakeup by inner (specifically, its other end, if it’s a channel) when inner becomes readable.

Therefore this task will be woken up, and, if the caller actually polls us again (as is usual and is required by our docs), we’ll drain any queued data.

Implementations

impl<T, S> SometimesUnboundedSink<T, S>

pub(crate) fn project<'pin>( self: Pin<&'pin mut Self>, ) -> __SometimesUnboundedSinkProjection<'pin, T, S>

pub(crate) fn project_ref<'pin>( self: Pin<&'pin Self>, ) -> __SometimesUnboundedSinkProjectionRef<'pin, T, S>

impl<T, S: Sink<T>> SometimesUnboundedSink<T, S>

pub(crate) fn new(inner: S) -> Self

Wrap an inner Sink with a SometimesUnboundedSink

pub(crate) fn n_queued(&self) -> usize

Return the number of T queued in this sink.

pub(crate) fn iter_queue(&self) -> impl Iterator<Item = &T> + '_

Return an iterator over the items queued in this sink.

(Used by circuit padding to see whether we have a cell queued for a given hop.)

pub(crate) fn pollish_send_unbounded( self: Pin<&mut Self>, cx: &mut Context<'_>, item: T, ) -> Result<(), S::Error>

Hand item to the inner Sink if possible, or queue it otherwise

Like a poll_... method in that it takes a Context. That’s needed to make sure we get polled again when the underlying sink can accept items.

But unlike a poll_... method in that it doesn’t return Poll, since completion is always immediate.

pub(crate) async fn send_unbounded( self: Pin<&mut Self>, item: T, ) -> Result<(), S::Error>

Hand item to the inner Sink if possible, or queue it otherwise (async fn)

You must .await this, but it will never block. (Its future is always Ready.)

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

Flush the buffer. On a Ready(()) return, it’s empty.

This satisfies the Waker invariant as if it were a public method.

pub(crate) fn as_inner(&self) -> &S

Obtain a reference to the inner Sink, S

This method should be used with a little care, since it bypasses the wrapper. For example, if S has interior mutability, and this method is used to modify it, the SometimesUnboundedSink may malfunction.

pub(crate) fn as_inner_mut(&mut self) -> &mut S

Obtain a mutable reference to the inner Sink, S

This method should be used with extra care, since it bypasses the wrapper. Before you call this method, make sure you understand the internal invariants for SometimesUnboundedSink, and make sure that you are not violating them. In particular, do not queue anything onto the resulting Sink directly.

Trait Implementations

impl<T, S: Sink<T>> Sink<T> for SometimesUnboundedSink<T, S>

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

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

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

Attempts to prepare the Sink to receive a value.

fn start_send(self: Pin<&mut Self>, item: T) -> Result<(), S::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(())).

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

Flush any remaining output from this sink.

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

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

impl<'pin, T, S> Unpin for SometimesUnboundedSink<T, S>

where PinnedFieldsOf<__SometimesUnboundedSink<'pin, T, S>>: Unpin,