Struct Executor

pub struct Executor<'a> { /* private fields */ }

Interface for running concurrent tasks

You call the spawn_pinned or spawn method to add a task to the executor. Just adding a task to the executor does not run it. You need to call the step or run_until_stalled method to run the tasks.

Executor implements Clone but all clones share the same set of tasks. Separately created Executor instances do not share tasks.

Implementations

impl<'a> Executor<'a>

pub fn new() -> Self

Creates a new Executor with an empty task queue.

pub fn wake_count(&self) -> usize

Returns the number of tasks that have been woken up but not yet polled.

pub unsafe fn spawn_pinned( &self, future: Pin<Box<dyn Future<Output = ()> + 'a>>, )

Adds a task to the task queue.

The added task is not polled immediately. It will be polled when the executor runs tasks.

Safety

It may be surprising that this method is unsafe. The reason is that the Waker available in the Context passed to the future’s poll method is thread-unsafe despite Waker being Send and Sync. The Waker is not protected by a lock or atomic operation, and it is your sole responsibility to ensure that the Waker is not passed to or accessed from other threads.

pub unsafe fn spawn<F, T>(&self, future: F) -> Receiver<T>

where F: IntoFuture<Output = T> + 'a, T: 'a,

Adds a task to the task queue.

This method is an extended version of spawn_pinned that can take a non-pinned future and may return a non-unit output. The result of the future will be sent to the returned receiver.

The added task is not polled immediately. It will be polled when the executor runs tasks.

Safety

See spawn_pinned for safety considerations.

pub fn spawner(&self) -> Spawner<'a>

Returns a Spawner that can spawn tasks.

pub fn step(&self) -> Option<bool>

Runs a task that has been woken up.

This method removes a single task from the task queue and polls it. Returns:

• Some(true) if the task is complete
• Some(false) if the task is not complete
• None if there are no tasks to run

This method panics if the task is polled recursively.

pub fn run_until_stalled(&self) -> usize

Runs tasks until there are no more tasks to run.

This method repeatedly calls step until it returns None, that is, there are no more tasks that have been woken up. Returns the number of completed tasks.

This method panics if a task is polled recursively.

Trait Implementations

impl<'a> Clone for Executor<'a>

fn clone(&self) -> Executor<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Executor<'a>

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

Formats the value using the given formatter.

impl<'a> Default for Executor<'a>

fn default() -> Executor<'a>

Returns the “default value” for a type.