Struct Scheduler 

pub struct Scheduler { /* private fields */ }

The three-lane scheduler.

Uses binary heaps for O(log n) insertion instead of O(n) VecDeque insertion. Generation counters provide FIFO ordering within same priority/deadline.

Implementations

impl Scheduler

pub fn new() -> Self

Creates a new empty scheduler.

pub fn with_capacity(capacity: usize) -> Self

Creates a scheduler with pre-allocated capacity for lanes and dedup set.

The capacity is applied per lane to reduce heap growth on bursty workloads.

pub fn len(&self) -> usize

Returns the total number of scheduled tasks.

pub fn is_empty(&self) -> bool

Returns true if no tasks are scheduled.

pub fn has_runnable_work(&self, now: Time) -> bool

Returns true if there is work that can be executed immediately.

Returns true if:

• Cancel lane is not empty
• Ready lane is not empty
• Timed lane has a task with deadline <= now

pub fn next_deadline(&self) -> Option<Time>

Returns the earliest deadline from the timed lane, if any.

pub fn schedule(&mut self, task: TaskId, priority: u8)

Schedules a task in the ready lane.

Does nothing if the task is already scheduled. O(log n) insertion via binary heap.

pub fn schedule_cancel(&mut self, task: TaskId, priority: u8)

Schedules or promotes a task into the cancel lane.

If the task is already scheduled, it is moved to the cancel lane to ensure cancellation preempts timed/ready work. O(log n) insertion for new tasks; O(n) for promotions.

pub fn schedule_timed(&mut self, task: TaskId, deadline: Time)

Schedules a task in the timed lane.

Does nothing if the task is already scheduled. O(log n) insertion via binary heap.

pub fn pop(&mut self) -> Option<TaskId>

Pops the next task to run.

Order: cancel lane > timed lane > ready lane. O(log n) pop via binary heap.

pub fn pop_with_rng_hint(&mut self, rng_hint: u64) -> Option<TaskId>

Pops the next task to run, using rng_hint for tie-breaking among equal-priority tasks.

Order: cancel lane > timed lane > ready lane. O(log n) pop via binary heap.

pub fn pop_with_lane(&mut self, rng_hint: u64) -> Option<(TaskId, DispatchLane)>

Pop the highest-priority task across all three lanes, returning both the task and the lane it was dispatched from.

Lane priority: Cancel > Timed > Ready (same as pop_with_rng_hint).

This method is deadline-agnostic for timed tasks. If your caller keeps future timed tasks in the scheduler, use Self::pop_with_lane_if_due instead to prevent dispatch before deadline.

pub fn pop_with_lane_if_due( &mut self, rng_hint: u64, now: Time, ) -> Option<(TaskId, DispatchLane)>

Pop across all three lanes while enforcing timed deadline readiness.

Lane priority remains Cancel > Timed > Ready, but timed tasks are dispatched only when deadline <= now.

pub fn pop_cancel_with_rng( &mut self, rng_hint: u64, ) -> Option<(TaskId, DispatchLane)>

Pop a task from the cancel lane using deterministic RNG tie-breaking.

pub fn pop_non_cancel_with_rng( &mut self, rng_hint: u64, ) -> Option<(TaskId, DispatchLane)>

Pop a task from timed or ready lanes (excluding cancel lane).

Timed lane has priority over ready lane.

This method is deadline-agnostic for timed tasks. If your caller keeps future timed tasks in the scheduler, use Self::pop_non_cancel_with_rng_if_due to prevent early dispatch.

pub fn pop_non_cancel_with_rng_if_due( &mut self, rng_hint: u64, now: Time, ) -> Option<(TaskId, DispatchLane)>

Pop from timed or ready lanes while enforcing timed deadline readiness.

Timed lane retains priority over ready lane, but timed tasks are dispatched only when deadline <= now.

pub fn remove(&mut self, task: TaskId)

Removes a specific task from the scheduler.

O(n) rebuild of affected lane. This is acceptable since removal is rare compared to schedule/pop operations.

pub fn move_to_cancel_lane(&mut self, task: TaskId, priority: u8)

Moves a task to the cancel lane (highest priority).

If the task is not currently scheduled, it will be added to the cancel lane. If the task is already in the cancel lane, its priority may be updated.

This is the key operation for ensuring cancelled tasks get priority: the cancel lane is always drained before timed and ready lanes.

O(n) for finding and removing from other lanes, O(log n) for insertion.

pub fn is_in_cancel_lane(&self, task: TaskId) -> bool

Returns true if a task is in the cancel lane.

pub fn pop_cancel_only(&mut self) -> Option<TaskId>

Pops only from the cancel lane.

Use this for strict cancel-first processing in multi-worker scenarios. O(log n) pop via binary heap.

pub fn pop_cancel_only_with_hint(&mut self, rng_hint: u64) -> Option<TaskId>

Pops only from the cancel lane with RNG tie-breaking.

pub fn pop_timed_only(&mut self, now: Time) -> Option<TaskId>

Pops only from the timed lane if the earliest deadline is due.

Returns None if no timed tasks exist or the earliest deadline has not yet been reached. This prevents timed tasks from firing before their deadline when in the local scheduler.

O(log n) pop via binary heap.

pub fn pop_timed_only_with_hint( &mut self, rng_hint: u64, now: Time, ) -> Option<TaskId>

Pops only from the timed lane if the earliest deadline is due, with RNG tie-breaking among tasks sharing the earliest deadline.

pub fn pop_ready_only(&mut self) -> Option<TaskId>

Pops only from the ready lane.

Use this for strict lane ordering in multi-worker scenarios. O(log n) pop via binary heap.

pub fn pop_ready_only_with_hint(&mut self, rng_hint: u64) -> Option<TaskId>

Pops only from the ready lane with RNG tie-breaking among equal priorities.

pub fn pop_any_lane_with_hint( &mut self, rng_hint: u64, now: Time, ) -> Option<(u8, TaskId)>

Checks all local lanes in priority order (cancel > timed > ready) in a single call, avoiding repeated lock acquisitions when the caller would check each lane sequentially.

Returns (lane_tag, task_id) where lane_tag is 0=cancel, 1=timed, 2=ready.

pub fn steal_ready_batch(&mut self, max_steal: usize) -> Vec<(TaskId, u8)>

Steals a batch of ready tasks for another worker.

Only steals from the ready lane to preserve cancel/timed priority semantics. Returns the stolen tasks with their priorities.

O(k log n) where k is the number of tasks stolen.

pub fn steal_ready_batch_into( &mut self, max_steal: usize, out: &mut Vec<(TaskId, u8)>, ) -> usize

Steals ready tasks into a caller-provided buffer.

Returns the number of tasks stolen.

pub fn has_cancel_work(&self) -> bool

Returns true if the cancel lane has pending tasks.

pub fn has_timed_work(&self) -> bool

Returns true if the timed lane has pending tasks.

pub fn has_ready_work(&self) -> bool

Returns true if the ready lane has pending tasks.

pub fn clear(&mut self)

Clears all scheduled tasks.

Trait Implementations

impl Debug for Scheduler

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Scheduler

fn default() -> Self

Returns the “default value” for a type.