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,
        timeout: Option<Duration>,
    ) -> impl Future<Output = Result<(), Error>> + Send;
    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, timeout: Option<Duration>, ) -> impl Future<Output = Result<(), Error>> + Send

Signals the runtime to stop execution and waits for all outstanding tasks to perform any required cleanup and exit.

This method does not actually kill any tasks but rather signals to them, using the signal::Signal returned by Spawner::stopped, that they should exit. It then waits for all signal::Signal references to be dropped before returning.

Multiple Stop Calls

This method is idempotent and safe to call multiple times concurrently (on different instances of the same context since it consumes self). The first call initiates shutdown with the provided value, and all subsequent calls will wait for the same completion regardless of their value parameter, i.e. the original value from the first call is preserved.

Timeout

If a timeout is provided, the method will return an error if all signal::Signal references have not been dropped within the specified duration.

fn stopped(&self) -> Signal

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

If Spawner::stop has already been called, the signal::Signal returned will resolve immediately. The signal::Signal returned will always resolve to the value of the first Spawner::stop call.

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