Skip to main content

Module executor

Module executor 

Source
Expand description

Single-threaded task polling and waker ownership.

Spawning puts an Rc<Task> in new_tasks. Each step moves queued handles into a reusable buffer and drains it, polling each handle’s future if it has not already completed. Several queued handles can refer to the same task, so a pending future may be polled more than once in a step.

Each drained handle is dropped after use. A pending task stays alive only while another strong reference exists, such as a queued handle or a saved waker. There is no separate collection retaining all pending tasks.

The borrowed/owned distinction applies to wakers; both refer to the same heap-allocated task. There are two raw-waker representations:

  • The polling context uses BORROWED_VTABLE. Its data points to the local Rc<Task> handle, not directly to the task. waker_for_task returns a WakerRef whose lifetime is tied to that handle’s borrow, preventing safe code from retaining this representation after the handle goes away. ManuallyDrop suppresses destruction of the temporary waker. Constructing this context therefore needs no extra reference-count increment/decrement.
  • Cloning the context waker clones the borrowed Rc and passes that new owner through Rc::into_raw. The result uses VTABLE, points directly to the task, and owns one strong reference. It can outlive the poll. Further clones each acquire another reference; dropping an owned waker releases its reference. Consuming it with wake() queues a task reference and releases the reference owned by that waker.

The lifetimes enforce the borrowed context’s scope, but choosing the correct data pointer and vtable is an unsafe-code invariant: only owned-waker callbacks may reconstruct an Rc<Task> with Rc::from_raw, and their input must originate from Rc::into_raw. A borrowed pointer cannot be treated as an owned reference merely by suppressing its destructor. Both vtables support wake_by_ref by cloning one task reference into new_tasks while preserving the source waker. The borrowed vtable rejects consuming wake and drop, which safe use of WakerRef prevents. Those callbacks panic if called.

Completion removes the future from the task, so a later queued wake cannot poll it again. The task is destroyed when its last strong reference is released. These task references are separate from Rc<ExecutorState>, which keeps the shared executor state alive.

Structs§

Executor
Single-threaded executor
ExecutorSnapshot
Executor activity reported at a configured wall-clock interval.
ExecutorStats
Cumulative future activity from the most recent executor run.
Spawner
Spawner spawns new futures into the executor.

Functions§

new_executor_and_spawner