std/task

Types

Executor

@unsafeGuarantee(Send)
pub type Executor

Runs one task tree: on the thread driving it, and on its own workers when it has any. Safety: every operation on the scheduler state takes its lock, and a drop on any lane leaves a busy pool to be joined by the driver.

Executor.handoff

pub fn Executor.handoff[T](self, future: Future[T]) -> Task[T]

Starts the future as a child of the running task, but on this executor instead of the running task's own.

Executor.runToCompletion

pub fn Executor.runToCompletion[T](self, future: Future[T]) -> T

Drives the future, and everything it spawns, to a terminal state.

Task

pub type Task[T]

A running task; await it for its result.

Task.cancel

pub fn Task[T].cancel(self)

Asks the task to stop at its next suspension point.

BlockingPool

pub type BlockingPool

A bounded, root-owned boundary for running direct-blocking work from an async body instead of calling it bare.

BlockingPool.new

pub fn BlockingPool.new(capacity: usize) -> BlockingPool

Creates a pool that runs at most capacity closures at once.

BlockingPool.run

pub fn BlockingPool.run[T, F: FnOnce[fn() -> T]](self, work: F) -> Result[Future[T], BlockingError]

Runs work through the pool's boundary instead of a bare direct call; work may capture move-only values such as a File or Conn, and is consumed. Under a threadPoolExecutor it runs on a thread of its own, so awaiting the result suspends the task and the workers keep running other tasks; under currentThreadExecutor, or outside a running task, it runs on the caller before run returns. Dropping a result that is still pending waits for the closure, since blocking work cannot be interrupted.

BlockingError

pub type BlockingError = | CapacityExhausted

run's only failure: the pool already has capacity closures in flight.

BlockingError.message

pub fn BlockingError.message(self) -> String

Functions

currentThreadExecutor

pub fn currentThreadExecutor() -> Executor

An executor that drives tasks on the thread calling it.

threadPoolExecutor

pub fn threadPoolExecutor(workers: usize) -> Executor

An executor with workers worker threads besides the one that drives it; migratable tasks run on any of them.

spawn

pub fn spawn[T](future: Future[T]) -> Task[T]

Starts the future as a child task. Its panic is raised where it is awaited; if nothing awaits it, the panic cancels the parent and its other children, and the parent fails with it.

yieldNow

pub fn yieldNow() -> Future[Void]

A Future whose first poll puts the running task behind the other runnable tasks of its executor.

cancelRequested

pub fn cancelRequested() -> Bool

Whether the running task has been asked to stop.