Struct Spawner

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

Interface for spawning tasks

Spawner provides a subset of the functionality of Executor to allow spawning tasks without access to the full executor.

Spawner instances can be cloned and share the same executor state. Spawners maintain a weak reference to the executor state, so they do not prevent the executor from being dropped. If the executor is dropped, the Spawner will not be able to spawn any more tasks.

To obtain a Spawner from an Executor, use the Executor::spawner method. The dead and default functions return a Spawner that can never spawn tasks.

let executor = Executor::new();
let spawner = executor.spawner();
let final_receiver = unsafe {
    executor.spawn(async move {
        let receiver_1 = spawner.spawn(async { 1 }).unwrap();
        let receiver_2 = spawner.spawn(async { 2 }).unwrap();
        receiver_2.await + receiver_1.await
    })
};
executor.run_until_stalled();
assert_eq!(final_receiver.try_receive(), Ok(3));

Implementations

impl<'a> Spawner<'a>

pub fn dead() -> Self

Creates a dummy Spawner that is not associated with any executor and thus cannot spawn tasks.

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

Adds the given future to the executor’s task queue so that it will be polled when the executor is run.

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

If the executor has been dropped, this method will return the future wrapped in a SpawnError. The caller can then reuse the future with another executor or handle the error in some other way.

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, ) -> Result<Receiver<T>, SpawnError<F>>

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

Adds the given future to the executor’s task queue so that it will be polled when the executor is run.

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.

If the executor has been dropped, this method will return the future wrapped in a SpawnError. The caller can then reuse the future with another executor or handle the error in some other way.

Safety

See spawn_pinned for safety considerations.

Trait Implementations

impl<'a> Clone for Spawner<'a>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Spawner<'a>

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

Formats the value using the given formatter.

impl<'a> Default for Spawner<'a>

fn default() -> Spawner<'a>

Returns the “default value” for a type.