Trait ordered_stream::OrderedStream

source · 
pub trait OrderedStream {
    type Ordering: Ord;
    type Data;

    fn poll_next_before(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
        before: Option<&Self::Ordering>
    ) -> Poll<PollResult<Self::Ordering, Self::Data>>;

    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§

The type ordered by this stream.

Each stream must produce values that are in ascending order according to this function, although there is no requirement that the values be strictly ascending.

The unordered data carried by this stream

This is split from the Ordering type to allow specifying a smaller or cheaper-to-generate type as the ordering key. This is especially useful if you generate values to pass in to before.

Required Methods§

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 before was None, Poll::Pending means 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 before was Some, Poll::Pending means 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 subsequent poll_next_before calls. 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 to before.

  • Poll::Ready(PollResult::Terminated) means that the stream has terminated, and poll_next_before should not be invoked again.

  • Poll::Ready(PollResult::NoneBefore) means that the stream will not produce any further ordering tokens less than the given token. Subsequent poll_next_before calls 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 if before was None.

Provided Methods§

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.

Returns the bounds on the remaining length of the stream.

Implementations on Foreign Types§

Implementors§