Struct Wheel 

pub struct Wheel { /* private fields */ }

Timing wheel data structure (hierarchical mode)

时间轮数据结构（分层模式）

Implementations

impl Wheel

pub fn new(config: WheelConfig, batch_config: BatchConfig) -> Self

Create new timing wheel

Parameters

• config: Timing wheel configuration (already validated)
• batch_config: Batch processing configuration

Notes

Configuration parameters have been validated in WheelConfig::builder().build(), so this method will not fail.

创建新的时间轮

参数

• config: 时间轮配置（已验证）
• batch_config: 批处理配置

注意

配置参数已在 WheelConfig::builder().build() 中验证，因此此方法不会失败。

pub fn current_tick(&self) -> u64

Get current tick (L0 layer tick)

获取当前 tick（L0 层 tick）

pub fn tick_duration(&self) -> Duration

Get tick duration (L0 layer tick duration)

获取 tick 持续时间（L0 层 tick 持续时间）

pub fn slot_count(&self) -> usize

Get slot count (L0 layer slot count)

获取槽数量（L0 层槽数量）

pub fn delay_to_ticks(&self, delay: Duration) -> u64

Calculate the number of ticks corresponding to the delay (based on L0 layer)

计算延迟对应的 tick 数量（基于 L0 层）

pub fn insert( &mut self, task: TimerTask, notifier: CompletionNotifier, ) -> TaskId

Insert timer task

Parameters

• task: Timer task
• notifier: Completion notifier (used to send notifications when tasks expire or are cancelled)

Returns

Unique identifier of the task (TaskId)

Implementation Details

• Automatically calculate the layer and slot where the task should be inserted
• Hierarchical mode: short delay tasks are inserted into L0, long delay tasks are inserted into L1
• Use bit operations to optimize slot index calculation
• Maintain task index to support O(1) lookup and cancellation

插入定时器任务

参数

• task: 定时器任务
• notifier: 完成通知器（用于在任务过期或取消时发送通知）

返回值

任务的唯一标识符（TaskId）

实现细节

• 自动计算任务应该插入的层级和槽位
• 分层模式：短延迟任务插入 L0，长延迟任务插入 L1
• 使用位运算优化槽索引计算
• 维护任务索引以支持 O(1) 查找和取消

pub fn insert_batch( &mut self, tasks: Vec<(TimerTask, CompletionNotifier)>, ) -> Vec<TaskId>

Batch insert timer tasks

Parameters

• tasks: List of tuples of (task, completion notifier)

Returns

List of task IDs

Performance Advantages

• Reduce repeated boundary checks and capacity adjustments
• For tasks with the same delay, calculation results can be reused

批量插入定时器任务

参数

• tasks: (任务, 完成通知器) 元组列表

返回值

任务 ID 列表

性能优势

• 减少重复的边界检查和容量调整
• 对于相同延迟的任务，可以重用计算结果

pub fn cancel(&mut self, task_id: TaskId) -> bool

Cancel timer task

Parameters

• task_id: Task ID

Returns

Returns true if the task exists and is successfully cancelled, otherwise returns false

取消定时器任务

参数

• task_id: 任务 ID

返回值

如果任务存在且成功取消则返回 true，否则返回 false

pub fn cancel_batch(&mut self, task_ids: &[TaskId]) -> usize

Batch cancel timer tasks

Parameters

• task_ids: List of task IDs to cancel

Returns

Number of successfully cancelled tasks

Performance Advantages

• Reduce repeated HashMap lookup overhead
• Multiple cancellation operations on the same slot can be batch processed
• Use unstable sort to improve performance
• Small batch optimization: skip sorting based on configuration threshold, process directly

批量取消定时器任务

参数

• task_ids: 要取消的任务 ID 列表

返回值

成功取消的任务数量

性能优势

• 减少重复的 HashMap 查找开销
• 同一槽位的多个取消操作可以批量处理
• 使用不稳定排序提高性能
• 小批量优化：根据配置阈值跳过排序，直接处理

pub fn advance(&mut self) -> Vec<TimerTask>

Advance the timing wheel by one tick, return all expired tasks

Returns

List of expired tasks

Implementation Details

• L0 layer advances 1 tick each time (no rounds check)
• L1 layer advances once every (L1_tick / L0_tick) times
• L1 expired tasks are batch demoted to L0

推进时间轮一个 tick，返回所有过期的任务

返回值

过期任务列表

实现细节

• L0 层每次推进 1 个 tick（无轮数检查）
• L1 层每 (L1_tick / L0_tick) 次推进一次
• L1 层过期任务批量降级到 L0

pub fn is_empty(&self) -> bool

Check if the timing wheel is empty

检查时间轮是否为空

pub fn postpone( &mut self, task_id: TaskId, new_delay: Duration, new_callback: Option<CallbackWrapper>, ) -> bool

Postpone timer task (keep original TaskId)

Parameters

• task_id: Task ID to postpone
• new_delay: New delay time (recalculated from current tick, not continuing from original delay time)
• new_callback: New callback function (if None, keep original callback)

Returns

Returns true if the task exists and is successfully postponed, otherwise returns false

Implementation Details

• Remove task from original layer/slot, keep its completion_notifier (will not trigger cancellation notification)
• Update delay time and callback function (if provided)
• Recalculate target layer, slot, and rounds based on new_delay
• Cross-layer migration may occur (L0 <-> L1)
• Re-insert to new position using original TaskId
• Keep consistent with external held TaskId reference

延期定时器任务（保留原始 TaskId）

参数

• task_id: 要延期的任务 ID
• new_delay: 新延迟时间（从当前 tick 重新计算，而非从原延迟时间继续）
• new_callback: 新回调函数（如果为 None，则保留原回调）

返回值

如果任务存在且成功延期则返回 true，否则返回 false

实现细节

• 从原层级/槽位移除任务，保留其 completion_notifier（不会触发取消通知）
• 更新延迟时间和回调函数（如果提供）
• 根据 new_delay 重新计算目标层级、槽位和轮数
• 可能发生跨层迁移（L0 <-> L1）
• 使用原始 TaskId 重新插入到新位置
• 与外部持有的 TaskId 引用保持一致

pub fn postpone_batch(&mut self, updates: Vec<(TaskId, Duration)>) -> usize

Batch postpone timer tasks

Parameters

• updates: List of tuples of (task ID, new delay)

Returns

Number of successfully postponed tasks

Performance Advantages

• Batch processing reduces function call overhead
• All delays are recalculated from current_tick at call time

Notes

• If a task ID does not exist, that task will be skipped without affecting other tasks’ postponement

批量延期定时器任务

参数

• updates: (任务 ID, 新延迟) 元组列表

返回值

成功延期的任务数量

性能优势

• 批处理减少函数调用开销
• 所有延迟在调用时从 current_tick 重新计算

注意

• 如果任务 ID 不存在，该任务将被跳过，不影响其他任务的延期

pub fn postpone_batch_with_callbacks( &mut self, updates: Vec<(TaskId, Duration, Option<CallbackWrapper>)>, ) -> usize

Batch postpone timer tasks (replace callbacks)

Parameters

• updates: List of tuples of (task ID, new delay, new callback)

Returns

Number of successfully postponed tasks

批量延期定时器任务（替换回调）

参数

• updates: (任务 ID, 新延迟, 新回调) 元组列表

返回值

成功延期的任务数量