Trait Spawner

pub trait Spawner:
    Clone
    + Send
    + Sync
    + 'static {
    // Required methods
    fn spawn<F, Fut, T>(self, f: F) -> Handle<T> 
       where F: FnOnce(Self) -> Fut + Send + 'static,
             Fut: Future<Output = T> + Send + 'static,
             T: Send + 'static;
    fn spawn_ref<F, T>(&mut self) -> impl FnOnce(F) -> Handle<T> + 'static
       where F: Future<Output = T> + Send + 'static,
             T: Send + 'static;
    fn spawn_blocking<F, T>(self, dedicated: bool, f: F) -> Handle<T> 
       where F: FnOnce(Self) -> T + Send + 'static,
             T: Send + 'static;
    fn spawn_blocking_ref<F, T>(
        &mut self,
        dedicated: bool,
    ) -> impl FnOnce(F) -> Handle<T> + 'static
       where F: FnOnce() -> T + Send + 'static,
             T: Send + 'static;
    fn stop(&self, value: i32);
    fn stopped(&self) -> Signal;
}

Interface that any task scheduler must implement to spawn tasks.

Required Methods

fn spawn<F, Fut, T>(self, f: F) -> Handle<T>

where F: FnOnce(Self) -> Fut + Send + 'static, Fut: Future<Output = T> + Send + 'static, T: Send + 'static,

Enqueue a task to be executed.

Unlike a future, a spawned task will start executing immediately (even if the caller does not await the handle).

Spawned tasks consume the context used to create them. This ensures that context cannot be shared between tasks and that a task’s context always comes from somewhere.

fn spawn_ref<F, T>(&mut self) -> impl FnOnce(F) -> Handle<T> + 'static

where F: Future<Output = T> + Send + 'static, T: Send + 'static,

Enqueue a task to be executed (without consuming the context).

The semantics are the same as Spawner::spawn.

Warning

If this function is used to spawn multiple tasks from the same context, the runtime will panic to prevent accidental misuse.

fn spawn_blocking<F, T>(self, dedicated: bool, f: F) -> Handle<T>

where F: FnOnce(Self) -> T + Send + 'static, T: Send + 'static,

Enqueue a blocking task to be executed.

This method is designed for synchronous, potentially long-running operations. Tasks can either be executed in a shared thread (tasks that are expected to finish on their own) or a dedicated thread (tasks that are expected to run indefinitely).

The task starts executing immediately, and the returned handle can be awaited to retrieve the result.

Motivation

Most runtimes allocate a limited number of threads for executing async tasks, running whatever isn’t waiting. If blocking tasks are spawned this way, they can dramatically reduce the efficiency of said runtimes.

Warning

Blocking tasks cannot be aborted.

fn spawn_blocking_ref<F, T>( &mut self, dedicated: bool, ) -> impl FnOnce(F) -> Handle<T> + 'static

where F: FnOnce() -> T + Send + 'static, T: Send + 'static,

Enqueue a blocking task to be executed (without consuming the context).

The semantics are the same as Spawner::spawn_blocking.

Warning

If this function is used to spawn multiple tasks from the same context, the runtime will panic to prevent accidental misuse.

fn stop(&self, value: i32)

Signals the runtime to stop execution and that all outstanding tasks should perform any required cleanup and exit. This method is idempotent and can be called multiple times.

This method does not actually kill any tasks but rather signals to them, using the Signal returned by stopped, that they should exit.

fn stopped(&self) -> Signal

Returns an instance of a Signal that resolves when stop is called by any task.

If stop has already been called, the returned Signal will resolve immediately.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl Spawner for commonware_runtime::deterministic::Context

impl Spawner for commonware_runtime::tokio::Context