Struct StreamUnordered

pub struct StreamUnordered<S> { /* private fields */ }

A set of streams which may yield items in any order.

This structure is optimized to manage a large number of streams. Streams managed by StreamUnordered will only be polled when they generate wake-up notifications. This reduces the required amount of work needed to poll large numbers of streams.

StreamUnordered can be filled by collecting an iterator of streams into a StreamUnordered, or by inserting streams onto an existing StreamUnordered. When new streams are added, poll_next must be called in order to begin receiving wake-ups for new streams.

Note that you can create a ready-made StreamUnordered via the collect method, or you can start with an empty set with the StreamUnordered::new constructor.

Implementations

impl<S: Stream> StreamUnordered<S>

pub fn new() -> StreamUnordered<S>

Constructs a new, empty StreamUnordered.

The returned StreamUnordered does not contain any streams. In this state, StreamUnordered::poll_next will return Poll::Ready(None).

impl<S> StreamUnordered<S>

pub fn len(&self) -> usize

Returns the number of streams contained in the set.

This represents the total number of in-flight streams.

pub fn is_empty(&self) -> bool

Returns true if the set contains no streams.

pub fn stream_entry(&mut self) -> StreamEntry<'_, S>

Returns a handle to a vacant stream entry allowing for further manipulation.

This function is useful when creating values that must contain their stream token. The returned StreamEntry reserves an entry for the stream and is able to query the associated token.

pub fn push(&mut self, stream: S) -> usize

👎Deprecated since 0.5.2: Prefer StreamUnordered::insert

Insert a stream into the set.

A deprecated synonym for [insert].

pub fn insert(&mut self, stream: S) -> usize

Insert a stream into the set.

This method adds the given stream to the set. This method will not call poll_next on the submitted stream. The caller must ensure that StreamUnordered::poll_next is called in order to receive wake-up notifications for the given stream.

The returned token is an identifier that uniquely identifies the given stream in the current set. To get a handle to the inserted stream, pass the token to StreamUnordered::get, StreamUnordered::get_mut, or StreamUnordered::get_pin_mut (or just index StreamUnordered directly). The same token will be yielded whenever an element is pulled from this stream.

Note that the streams are not ordered, and may not be yielded back in insertion or token order when you iterate over them.

pub fn remove(self: Pin<&mut Self>, token: usize) -> bool

Remove a stream from the set.

The stream will be dropped and will no longer yield stream events.

pub fn take(self: Pin<&mut Self>, token: usize) -> Option<S>

where S: Unpin,

Remove and return a stream from the set.

The stream will no longer be polled, and will no longer yield stream events.

Note that since this method moves S, which we may have given out a Pin to, it requires that S is Unpin.

pub fn is_finished(&self, token: usize) -> Option<bool>

Returns true if the stream with the given token has yielded None.

pub fn get(&self, token: usize) -> Option<&S>

Returns a reference to the stream with the given token

pub fn get_mut(&mut self, token: usize) -> Option<&mut S>

where S: Unpin,

Returns a reference that allows modifying the stream with the given token.

pub fn get_pin_mut(self: Pin<&mut Self>, token: usize) -> Option<Pin<&mut S>>

Returns a pinned reference that allows modifying the stream with the given token.

pub fn iter_mut(&mut self) -> IterMut<'_, S>

where S: Unpin,

Returns an iterator that allows modifying each stream in the set.

pub fn iter_mut_with_token(&mut self) -> IterMutWithToken<'_, S>

where S: Unpin,

Returns an iterator that allows modifying each stream in the set.

pub fn iter_pin_mut(self: Pin<&mut Self>) -> IterPinMut<'_, S>

Returns an iterator that allows modifying each stream in the set.

pub fn iter_pin_mut_with_token( self: Pin<&mut Self>, ) -> IterPinMutWithToken<'_, S>

Returns an iterator that allows modifying each stream in the set.

pub fn iter_with_token(&self) -> IterWithToken<'_, S>

Returns an immutable iterator that allows getting a reference to each stream in the set.

Trait Implementations

impl<S> Debug for StreamUnordered<S>

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

Formats the value using the given formatter.

impl<S: Stream> Default for StreamUnordered<S>

fn default() -> StreamUnordered<S>

Returns the “default value” for a type.

impl<S> Drop for StreamUnordered<S>

fn drop(&mut self)

Executes the destructor for this type.

impl<S: Stream> FromIterator<S> for StreamUnordered<S>

fn from_iter<I>(iter: I) -> Self

where I: IntoIterator<Item = S>,

Creates a value from an iterator.

impl<S: Stream + 'static> FusedStream for StreamUnordered<S>

fn is_terminated(&self) -> bool

Returns true if the stream should no longer be polled.

impl<S> Index<usize> for StreamUnordered<S>

type Output = S

The returned type after indexing.

fn index(&self, stream: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<S> IndexMut<usize> for StreamUnordered<S>

where S: Unpin,

fn index_mut(&mut self, stream: usize) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<S: Stream + 'static> Stream for StreamUnordered<S>

type Item = (StreamYield<S>, usize)

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: Send> Send for StreamUnordered<S>

impl<S: Sync> Sync for StreamUnordered<S>

impl<S> Unpin for StreamUnordered<S>