pub trait OrderedStream {
type Ordering: Ord;
type Data;
// Required method
fn poll_next_before(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
before: Option<&Self::Ordering>,
) -> Poll<PollResult<Self::Ordering, Self::Data>>;
// Provided methods
fn position_hint(&self) -> Option<MaybeBorrowed<'_, Self::Ordering>> { ... }
fn size_hint(&self) -> (usize, Option<usize>) { ... }
}Expand description
A stream that produces items that are ordered according to some token.
The main advantage of this trait over the standard Stream trait is the ability to implement a
join function that does not either block until both source streams produce an item
or contain a race condition when rejoining streams that originated from a common well-ordered
source.
Required Associated Types§
Required Methods§
sourcefn poll_next_before(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
before: Option<&Self::Ordering>,
) -> Poll<PollResult<Self::Ordering, Self::Data>>
fn poll_next_before( self: Pin<&mut Self>, cx: &mut Context<'_>, before: Option<&Self::Ordering>, ) -> Poll<PollResult<Self::Ordering, Self::Data>>
Attempt to pull out the next value of this stream, registering the current task for wakeup
if needed, and returning NoneBefore if it is known that the stream will not produce any
more values ordered before the given point.
§Return value
There are several possible return values, each indicating a distinct stream state depending
on the value passed in before:
-
If
beforewasNone,Poll::Pendingmeans that this stream’s next value is not ready yet. Implementations will ensure that the current task is notified when the next value may be ready. -
If
beforewasSome,Poll::Pendingmeans that this stream’s next value is not ready and that it is not yet known if the stream will produce a value ordered prior to the given ordering value. Implementations will ensure that the current task is notified when either the next value is ready or once it is known that no such value will be produced. -
Poll::Ready(PollResult::Item)means that the stream has successfully produced an item. The stream may produce further values on subsequentpoll_next_beforecalls. The returned ordering value must not be less than any prior ordering value returned by this stream. The returned ordering value may be greater than the value passed tobefore. -
Poll::Ready(PollResult::Terminated)means that the stream has terminated, andpoll_next_beforeshould not be invoked again. -
Poll::Ready(PollResult::NoneBefore)means that the stream will not produce any further ordering tokens less than the given token. Subsequentpoll_next_beforecalls may still produce additional items, but their tokens will be greater than or equal to the given token. It does not make sense to return this value ifbeforewasNone.
Provided Methods§
sourcefn position_hint(&self) -> Option<MaybeBorrowed<'_, Self::Ordering>>
fn position_hint(&self) -> Option<MaybeBorrowed<'_, Self::Ordering>>
The minimum value of the ordering for any future items.
If this does not return None, the returned ordering must be less than or equal to the
ordering of any future item returned from Self::poll_next_before. This value should
(but is not required to) be greater than or equal to the ordering of the most recent item
returned.