Module task 

Internal implementation of the task state machine that manages a future’s lifecycle.

Task System

The unit of execution in the runtime.

Origin & Evolution

This module was originally derived from the tokio task system. It shares the same high-performance atomic state management and lock-free notification logic. However, it has been significantly evolved to support the specific requirements of a io_uring-based, thread-per-core runtime.

Key Architecture Differences

1. Thread-Local I/O & Resource Accounting

Unlike epoll-based runtimes where file descriptors can often be polled from any thread, io_uring instances are strictly thread-local. This runtime introduces fields in the task Header to track:

• Pending I/Os: We track the number of in-flight operations on the ring.
• Owned Resources: We track thread-local resources (like registered buffers or direct descriptors) owned by the task.

Why? This is critical for Safe Work Stealing. A task cannot be stolen by another worker thread if it has pending completion events on the current thread’s ring, or if it holds resources tied to the current thread’s driver. The scheduler uses these counters to enforce this invariant.

2. Structured Concurrency & The Global Task Tree

This runtime implements full Structured Concurrency. Unlike a flat list of tasks, every task exists within a global hierarchy tracked by TaskNode.

• Parent/Child Relationships: Every spawned task (unless explicitly detached via TaskOpts) is a child of the task that spawned it.
• Cascading Cancellation: When a parent task is cancelled or aborts, the runtime can walk the TaskNode tree and cancel all descendants efficiently.
• Orphan Policy: The system tracks “orphans” (tasks whose parents have died) to ensure resources are eventually reclaimed or policies are enforced. The default policy is OrphanPolicy::Enforced which prohibits the creation of orphaned tasks by cancelling all children when a task finishes.

Structs

AbortHandle

An owned permission to abort a spawned task, without awaiting its completion.

JoinError

Task failed to execute to completion.

JoinHandle

An owned permission to join on a task (await its termination).