Struct Selector 

pub struct Selector<T, P = PollDirect> { /* private fields */ }

Selector over a dynamic set of pollable tasks, for example Futures and Streams.

Designed for optimal performance when polling a large number of tasks (see example).

Allows for:

1. Safely injecting shared state into the tasks (see Pollable).
2. Accessing and removing the tasks by unique ids.

Unless you want to exercise the full flexibility of this type, you can use the specialized 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 or consumed, AND
3. the Waker (and all its clones) passed when polling the task are dropped or consumed, AND
4. the selector observes the task removal.

The selector always eventually observes the removal when 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 PollProxy::poll_progress inside Context is woken

To avoid nasty surprises, keep this in mind when:

1. Modifying a task borrowed from the selector
2. Polling the selector with different extension types

See example.

Panic

If the task panics when polled, the task is removed from the selector and dropped. The selector remains valid.

Implementations

impl<T, P> Selector<T, P>

pub fn push(&mut self, task: T)

Pushes a new task into the selector.

This method is O(1).

pub fn push_with_id(&mut self, task: T) -> Id<T>

Pushes a new task into the selector and returns its unique id.

This method is O(1).

pub fn is_empty(&self) -> bool

Returns whether the selector is empty.

This method is O(1).

pub fn len(&self) -> usize

Returns the number of tasks in the selector.

This method is O(1).

pub fn wake_all(&self)

Manually wakes all tasks in the selector.

Depending on the PollProxy::poll_progress implementation, this might be required when polling with different extension types. See the wakeups section.

This method is O(n).

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

Returns an iterator over the 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 modifying each task in the selector.

The tasks are visited in the insertion order.

Important: before modifying tasks stored in the selector, see the wakeups section.

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

where F: FnMut(Pin<&mut 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.

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.

Important: before removing tasks from the selector, see the removal section.

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

Returns an immutable reference to the task with the given id.

Returns None if the task is not found in this selector, for example because it was removed or has already finished.

This method is O(1).

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

Returns a mutable reference to the target with the given id.

Returns None if the task is not found in this selector, for example because it was removed or has already finished.

This method is O(1).

Important: before modifying tasks stored in the selector, see the wakeups section.

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

Removes the task with the given id from the selector.

Returns None if the task is not found in the selector, for example because it was removed or has already finished.

This method is O(1).

Important: before removing tasks from the selector, see the removal section.

pub fn with_ext<'s, 'e, 'emut, E, EMut>( &'s mut self, ext: &'e E, ext_mut: &'emut mut EMut, ) -> WithExt<'s, 'e, 'emut, T, P, E, EMut>

where P: PollProxy<'e, T, E, EMut>, E: ?Sized, EMut: ?Sized,

Borrows a Stream that will pass the given extensions to the tasks when polling.

Important: before polling the tasks with different extension types, see the wakeups section.

pub fn with_id(&mut self) -> WithId<'_, T, P>

where P: PollProxy<'static, T, (), ()>,

Borrows a Stream that will return a task Id with every item.

pub fn with_ext_and_id<'s, 'e, 'emut, E, EMut>( &'s mut self, ext: &'e E, ext_mut: &'emut mut EMut, ) -> WithExtAndId<'s, 'e, 'emut, T, P, E, EMut>

where P: PollProxy<'e, T, E, EMut>, E: ?Sized, EMut: ?Sized,

Borrows a Stream that will pass the given extensions to the tasks when polling, and return a task Id with every item.

Important: before polling the tasks with different extension types, see the wakeups section.

Trait Implementations

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

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

Formats the value using the given formatter.

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

fn default() -> Self

Returns the “default value” for a type.

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

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, P> FromIterator<T> for Selector<T, P>

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

Creates a value from an iterator.

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

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, P, E, EMut> Pollable<'a, E, EMut> for Selector<T, P>

where P: PollProxy<'a, T, E, EMut>, E: ?Sized, EMut: ?Sized,

type Progress = <P as PollProxy<'a, T, E, EMut>>::Progress

Type of values returned when polling the task.

fn poll_progress( self: Pin<&mut Self>, ext: &'a E, ext_mut: &mut EMut, cx: &mut Context<'_>, ) -> Poll<ControlFlow<Option<Self::Progress>, Self::Progress>>

Polls the given task with references to strongly typed extensions.

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

where P: PollProxy<'static, T, (), ()>,

type Item = <P as PollProxy<'static, T, (), ()>>::Progress

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.