Struct StreamUnobtrusivePeeker

pub struct StreamUnobtrusivePeeker<S: Stream> {
    buffered: Option<S::Item>,
    poll_waker: Option<Waker>,
    inner: Option<S>,
}

Wraps [Stream] and provides \[poll_]peek and unobtrusive_peek

unobtrusive_peek is callable in sync contexts, outside the reading task.

Like [futures::stream::Peekable], this has an async peek method, and poll_peek, for use from the task that is also reading (via the [Stream] impl). But, that type doesn’t have unobtrusive_peek.

One way to conceptualise this is that StreamUnobtrusivePeeker is dual-ported: the two sets of APIs, while provided on the same type, are typically called from different contexts.

Fields

buffered: Option<S::Item>

An item that we have peeked.

(If we peeked EOF, that’s represented by None in inner.)

poll_waker: Option<Waker>

The Waker from the last time we were polled and returned Pending

“polled” includes any of our poll_ methods but not unobtrusive_peek.

None if we haven’t been polled, or the last poll returned Ready.

inner: Option<S>

The inner stream

None if it has yielded None` meaning EOF. We don’t require S: FusedStream.

Implementations

impl<S: Stream> StreamUnobtrusivePeeker<S>

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

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

impl<S: Stream> StreamUnobtrusivePeeker<S>

pub fn new(inner: S) -> Self

Create a new StreamUnobtrusivePeeker from a Stream

impl<S: Stream> StreamUnobtrusivePeeker<S>

fn impl_poll_next_or_peek<'s, R: 's>( self: Pin<&'s mut Self>, cx: &mut Context<'_>, return_value_obtainer: impl FnOnce(&'s mut Option<S::Item>) -> Option<R>, ) -> Poll<Option<R>>

Implementation of poll_{peek,next}

This takes care of

• examining the state of our buffer, and polling inner if needed
• ensuring that we store a waker, if needed
• dealing with some borrowck awkwardness

The Ready value is always calculated from buffer. return_value_obtainer is called only if we are going to return Ready. It’s given buffer and should either:

• take the contained value (for poll_next)
• return a reference using Option::as_ref (for poll_peek)

fn next_or_peek_inner( self_: &mut PeekerProj<'_, S>, cx: &mut Context<'_>, ) -> Poll<()>

Try to populate buffer, and calculate if we’re Ready

Returns Ready iff poll_next or poll_peek should return Ready. The actual Ready value (an Option) will be calculated later.

pub fn peek(self: Pin<&mut Self>) -> PeekFuture<'_, Self>

Wait for an item to be ready, and then inspect it

Equivalent to [futures::stream::Peekable::peek].

Tasks, waking, and calling context

This should be called by the task that is reading from the stream. If it is called by another task, the reading task would miss notifications.

fn return_from_poll<R>( poll_waker: &mut Option<Waker>, cx: &mut Context<'_>, r: Poll<R>, ) -> Poll<R>

Return from a poll_* function, setting the stored waker appropriately

Our poll functions always use this. The rule is that if a future returns Pending, it has stored the waker.

pub fn as_raw_inner_pin_mut<'s>( self: Pin<&'s mut Self>, ) -> Option<Pin<&'s mut S>>

Obtain a raw reference to the inner stream

Correctness!

This method must be used with care! Whatever you do mustn’t interfere with polling and peeking. Careless use can result in wrong behaviour including deadlocks.

Trait Implementations

impl<S: Debug + Stream> Debug for StreamUnobtrusivePeeker<S>

where S::Item: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<S: Stream> FusedStream for StreamUnobtrusivePeeker<S>

fn is_terminated(&self) -> bool

Returns true if the stream should no longer be polled.

impl<S: Stream> PeekableStream for StreamUnobtrusivePeeker<S>

fn poll_peek<'s>( self: Pin<&'s mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<&'s S::Item>>

Poll for an item to be ready, and then inspect it.

fn poll_peek_mut<'s>( self: Pin<&'s mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<&'s mut S::Item>>

Poll for an item to be ready, and then inspect it.

impl<S: Stream> Stream for StreamUnobtrusivePeeker<S>

type Item = <S as Stream>::Item

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.

impl<S: Stream> UnobtrusivePeekableStream for StreamUnobtrusivePeeker<S>

fn unobtrusive_peek_mut<'s>(self: Pin<&'s mut Self>) -> Option<&'s mut S::Item>

Peek at the next available value, while not losing a previously registered waker.

fn unobtrusive_peek(self: Pin<&mut Self>) -> Option<&<Self as Stream>::Item>

Peek at the next available value, while not losing a previously registered waker.

impl<'pin, S: Stream> Unpin for StreamUnobtrusivePeeker<S>

where PinnedFieldsOf<__StreamUnobtrusivePeeker<'pin, S>>: Unpin,