Module context 

Available on crate feature task-context only.

Task execution context and lifecycle tracking.

This module provides TaskContext, a lightweight handle for interacting with a task while it is being executed. A task context is associated with a single task and can be cloned and shared with sub-tasks.

Unlike WorkerContext, which represents state shared by all tasks running on a worker, TaskContext represents the lifecycle of one task. It can be used to request cancellation, observe completion, wait for execution to finish, access the task’s ExecutionContext, and track sub-tasks.

A task context is considered executed once the task has either completed or been cancelled. Sub-tasks spawned through TaskContext::run_until_executed are tied to their parent context and are tracked until they complete.

Lifecycle

A task context progresses through the following states:

Running
   ├── cancel() ──> Cancelled
   └── complete() ─> Completed

Once a task reaches a terminal state, subsequent attempts to cancel or complete it return a TaskStateError.

Waiting for execution

TaskContext::executed returns a future that resolves when the task is either completed or cancelled. The future registers a waker and therefore does not require polling in a loop.

Sub-tasks

TaskContext::run_until_executed can be used to associate additional asynchronous work with a task. A sub-task runs until it completes or its parent context is executed. Sub-tasks are counted by their parent context, allowing task execution to account for work spawned from the task.

Task state errors

TaskStateError describes failures when transitioning a task between lifecycle states. TerminalState identifies the terminal state that prevented the requested transition.

Structs

SubTaskFuture

A future that runs a sub-task tied to a TaskContext.

TaskContext

The context for a task, which can be used to cancel the task or spawn sub-tasks.

WaitForExecutionFuture

A future that resolves once its parent TaskContext is executed — either completed or cancelled.

Enums

TaskStateError

Errors that can occur when transitioning a TaskContext’s lifecycle state.

TerminalState

The terminal state a task had already reached, when a state transition fails.