Struct Selector 

pub struct Selector<T, S> { /* private fields */ }

Selector over a dynamic set of Tasks (generalized Futures/Streams).

Inspired by FuturesUnordered, designed for flexibility and optimal performance when polling a large number of tasks.

Unless you want to exercise the full flexibility of this type, you can stick to the specializations exposed in the root of this crate (e.g. FutureSelector and StreamSelector).

Removal

The selector creates a heap allocation for each stored task. Removing a task from the selector does not instantly free that memory. The memory can only be freed when:

1. all Id instances for this task are dropped, AND
2. Removed instance is dropped, AND
3. the Waker (and all its clones) passed when polling the task is dropped, AND
4. the selector observes the task removal (which happens when the selector is polled).

Wakeups

The selector uses a smart strategy for polling the tasks. A task is only polled in the following cases:

1. after it is pushed into the selector
2. after it yields a non-terminal value
3. after the waker passed to Task::poll_progress receives a wakeup

To avoid nasty surprises, keep this in mind when:

1. Modifying a task borrowed from the selector
2. Changing the strategy used by the selector (see example)

The wakeups are stored in a FIFO queue. This implies that the selector processes ready tasks in a round-robin fashion.

Panic

If the Task implementation panics, the task is removed from the selector and dropped, and the panic propagates. The selector remains valid.

Implementations

impl<T, S> Selector<T, S>

pub fn new(strategy: S) -> Self

Creates an empty selector with the given strategy.

pub fn push(&mut self, task: T) -> BorrowedMut<'_, T>

Pushes the given task into the selector, returning a mutable reference to the task.

The reference can be used to obtain the task’s Id.

This method is O(1).

pub fn len(&self) -> usize

Returns the number of tasks stored in the selector.

This method is O(1).

pub fn is_empty(&self) -> bool

Returns whether the selector is empty.

This method is O(1).

pub fn contains(&self, id: &Id<T>) -> bool

Returns whether the selector contains a task with the given Id.

This method is O(1).

pub fn get<'a>(&'a self, id: &Id<T>) -> Option<Borrowed<'a, T>>

If the selector contains a task with the given Id, returns a reference to it.

This method is O(1).

pub fn get_mut<'a>(&'a mut self, id: &Id<T>) -> Option<BorrowedMut<'a, T>>

If the selector contains a task with the given Id, returns a mutable reference to it.

This method is O(1).

pub fn remove(&mut self, id: &Id<T>) -> Option<Removed<T>>

If the selector contains a task with the given Id, removes it.

This method is O(1).

pub fn strategy(&self) -> &S

Returns a reference to the strategy used by this selector.

pub fn strategy_mut(&mut self) -> &mut S

Returns a mutable reference to the strategy used by this selector.

pub fn with_strategy<S1>(self, strategy: S1) -> Selector<T, S1>

Returns a new selector with the same state, but different strategy.

pub fn iter(&self) -> Iter<'_, T>

Returns an iterator over all tasks in the selector.

The tasks are visited in the insertion order.

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

Returns an iterator that allows for modifying each task in the selector.

The tasks are visited in the insertion order.

pub fn extract_if<F>(&mut self, pred: F) -> ExtractIf<'_, T, F>

where F: for<'b> FnMut(BorrowedMut<'b, T>) -> bool,

Creates an iterator which uses a closure to determine if a task should be removed.

If the closure returns true, the task is removed from the selector and yielded. The tasks are visited in the insertion order.

If the returned ExtractIf is not exhausted, e.g. because it is dropped without iterating or the iteration short-circuits, then the remaining tasks will be retained.

pub fn retain<F>(&mut self, pred: F)

where F: for<'b> FnMut(BorrowedMut<'b, T>) -> bool,

Retains only the tasks specified by the predicate.

In other words, remove all tasks for which the predicate returns false. The tasks are visited in the insertion order.

pub fn wake_all(&self)

Manually wakes all tasks in the selector.

Trait Implementations

impl<T, S> Debug for Selector<T, S>

where S: Debug,

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

Formats the value using the given formatter.

impl<T, S> Default for Selector<T, S>

where S: Default,

fn default() -> Self

Returns the “default value” for a type.

impl<T, S> Extend<T> for Selector<T, S>

fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T, S> FromIterator<T> for Selector<T, S>

where S: Default,

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Creates a value from an iterator.

impl<T, S> Index<&Id<T>> for Selector<T, S>

type Output = T

The returned type after indexing.

fn index(&self, id: &Id<T>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T, S> Index<Id<T>> for Selector<T, S>

type Output = T

The returned type after indexing.

fn index(&self, id: Id<T>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T, S> IndexMut<&Id<T>> for Selector<T, S>

where T: Unpin,

fn index_mut(&mut self, id: &Id<T>) -> &mut Self::Output

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

impl<T, S> IndexMut<Id<T>> for Selector<T, S>

where T: Unpin,

fn index_mut(&mut self, id: Id<T>) -> &mut Self::Output

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

impl<T, S> IntoIterator for Selector<T, S>

type IntoIter = IntoIter<T>

Which kind of iterator are we turning this into?

type Item = Removed<T>

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T, S> IntoIterator for &'a Selector<T, S>

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?

type Item = Borrowed<'a, T>

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T, S> IntoIterator for &'a mut Selector<T, S>

type IntoIter = IterMut<'a, T>

Which kind of iterator are we turning this into?

type Item = BorrowedMut<'a, T>

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T, S> Send for Selector<T, S>

where T: Send, S: Send,

impl<T, S> Stream for Selector<T, S>

where T: Task<S>, S: Unpin,

type Item = <T as Task<S>>::Output

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<T, S> Sync for Selector<T, S>

where T: Sync, S: Sync,