Skip to main content

TaskSpawner

moirai_core::executor::spawner

Trait TaskSpawner 

Source 
pub trait TaskSpawner:
    Send
    + Sync
    + 'static {
    // Required methods
    fn spawn<T>(&self, task: T) -> ExecutorResult<TaskHandle<T::Output>>
       where T: Task + Send + 'static;
    fn spawn_async<F>(&self, future: F) -> ExecutorResult<TaskHandle<F::Output>>
       where F: Future + Send + 'static,
             F::Output: Send + 'static;
    fn spawn_blocking<F, R>(&self, func: F) -> ExecutorResult<TaskHandle<R>>
       where F: FnOnce() -> R + Send + 'static,
             R: Send + 'static;
    fn spawn_with_priority<T>(
        &self,
        task: T,
        priority: Priority,
        locality_hint: Option<usize>,
    ) -> ExecutorResult<TaskHandle<T::Output>>
       where T: Task + Send + 'static;

    // Provided methods
    fn spawn_detached<F>(&self, func: F) -> ExecutorResult<()>
       where F: FnOnce() + Send + 'static { ... }
    fn spawn_local<T>(&self, task: T) -> ExecutorResult<TaskHandle<T::Output>>
       where T: Task + 'static { ... }
}
Expand description

Core task spawning capabilities.

This trait provides the fundamental ability to spawn tasks for execution. It follows the Single Responsibility Principle by focusing only on task spawning.

§Behavior Guarantees

  • Task spawning is non-blocking and returns immediately
  • Tasks are scheduled for execution but may not start immediately
  • Task handles can be used to wait for completion or cancel tasks
  • Memory ordering follows acquire-release semantics for task state

§Performance Characteristics

  • Task spawn: O(1) amortized, < 100ns typical latency
  • Memory overhead: < 64 bytes per task
  • Thread-safe: All operations are safe for concurrent access

Required Methods§

Source

fn spawn<T>(&self, task: T) -> ExecutorResult<TaskHandle<T::Output>>
where T: Task + Send + 'static,

Spawns a new task for execution.

§Arguments
  • task - The task to be executed
§Returns

A handle to the spawned task that allows monitoring and control

§Errors

Returns TaskError::SpawnFailed if the task cannot be spawned due to:

  • Resource exhaustion (queue full, memory limit reached)
  • Task validation failures (invalid priority, security constraints)
  • System shutdown in progress
Source

fn spawn_async<F>(&self, future: F) -> ExecutorResult<TaskHandle<F::Output>>
where F: Future + Send + 'static, F::Output: Send + 'static,

Spawns an asynchronous task (Future) for execution.

§Arguments
  • future - The future to be executed
§Returns

A handle to the spawned task

§Errors

Returns TaskError::SpawnFailed under the same conditions as spawn

Source

fn spawn_blocking<F, R>(&self, func: F) -> ExecutorResult<TaskHandle<R>>
where F: FnOnce() -> R + Send + 'static, R: Send + 'static,

Spawns a blocking task that may perform I/O or CPU-intensive work.

§Arguments
  • func - The blocking function to execute
§Returns

A handle to the spawned task

§Errors

Returns TaskError::SpawnFailed under the same conditions as spawn

Source

fn spawn_with_priority<T>( &self, task: T, priority: Priority, locality_hint: Option<usize>, ) -> ExecutorResult<TaskHandle<T::Output>>
where T: Task + Send + 'static,

Spawns a task with specific priority and scheduling hints.

§Arguments
  • task - The task to be executed
  • priority - The scheduling priority for this task
  • locality_hint - Optional hint about preferred execution location
§Returns

A handle to the spawned task

§Errors

Returns TaskError::SpawnFailed under the same conditions as spawn

Provided Methods§

Source

fn spawn_detached<F>(&self, func: F) -> ExecutorResult<()>
where F: FnOnce() + Send + 'static,

Spawns a fire-and-forget task whose result is discarded.

Unlike spawn_blocking, the caller receives no handle, so an implementation can avoid the per-task Arc<TaskResultSlot> heap allocation and its atomic reference counting that result-bearing spawns require. The task is still tracked for graceful-shutdown drain and metrics; it always runs to completion (there is no handle to drop, so dropping is not a cancellation path).

The provided default routes through spawn_blocking and discards the handle, so it still allocates a result slot; implementations should override it to skip that allocation.

§Errors

Returns TaskError::SpawnFailed under the same conditions as spawn.

Source

fn spawn_local<T>(&self, task: T) -> ExecutorResult<TaskHandle<T::Output>>
where T: Task + 'static,

Spawn a task on the current thread’s local queue for better locality (inspired by Tokio’s spawn_local)

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§