Trait Spawner 

pub trait Spawner:
    Clone
    + Send
    + Sync
    + 'static {
    // Required methods
    fn shared(self, blocking: bool) -> Self;
    fn dedicated(self) -> Self;
    fn instrumented(self) -> Self;
    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 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 shared(self, blocking: bool) -> Self

Return a Spawner that schedules tasks onto the runtime’s shared executor.

Set blocking to true when the task may hold the thread for a short, blocking operation. Runtimes can use this hint to move the work to a blocking-friendly pool so asynchronous tasks on a work-stealing executor are not starved. For long-lived, blocking work, use Spawner::dedicated instead.

The shared executor with blocking == false is the default spawn mode.

fn dedicated(self) -> Self

Return a Spawner that runs tasks on a dedicated thread when the runtime supports it.

Reserve this for long-lived or prioritized tasks that should not compete for resources in the shared executor.

This is not the default behavior. See Spawner::shared for more information.

fn instrumented(self) -> Self

Return a Spawner that instruments the next spawned task with the label of the spawning context.

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,

Spawn a task with the current context.

Unlike directly awaiting a future, the task starts running immediately even if the caller never awaits the returned Handle.

Mandatory Supervision

All tasks are supervised. When a parent task finishes or is aborted, all its descendants are aborted.

Spawn consumes the current task and provides a new child context to the spawned task. Likewise, cloning a context (either via Clone::clone or Metrics::with_label) returns a child context.

ctx_a
  |
  +-- clone() ---> ctx_c
  |                  |
  |                  +-- spawn() ---> Task C (ctx_d)
  |
  +-- spawn() ---> Task A (ctx_b)
                             |
                             +-- spawn() ---> Task B (ctx_e)

Task A finishes or aborts --> Task B and Task C are aborted

Spawn Configuration

When a context is cloned (either via Clone::clone or Metrics::with_label) or provided via Spawner::spawn, any configuration made via Spawner::dedicated or Spawner::shared is reset.

Child tasks should assume they start from a clean configuration without needing to inspect how their parent was configured.

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

impl<C> Spawner for Cell<C>

where C: Spawner,