Crate kestrel_protocol_timer 

高性能异步定时器系统

基于时间轮（Timing Wheel）算法实现的高性能异步定时器，支持 tokio 运行时。

特性

• 高性能: 使用时间轮算法，插入和删除操作的时间复杂度为 O(1)
• 大规模支持: 能够高效管理 10000+ 并发定时器
• 异步支持: 基于 tokio 异步运行时
• 线程安全: 使用 parking_lot 提供高性能的锁机制

快速开始

use kestrel_protocol_timer::{TimerWheel, CallbackWrapper};
use std::time::Duration;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建定时器管理器
    let timer = TimerWheel::with_defaults();
     
    // 步骤 1: 创建定时器任务（使用回调）
    let callback = Some(CallbackWrapper::new(|| async {
        println!("Timer fired after 1 second!");
    }));
    let task = TimerWheel::create_task(Duration::from_secs(1), callback);
    let task_id = task.get_id();
     
    // 步骤 2: 注册定时器任务并获取完成通知
    let handle = timer.register(task);
     
    // 等待定时器完成
    handle.into_completion_receiver().0.await?;
    Ok(())
}

架构说明

时间轮算法

采用分层时间轮（Hierarchical Timing Wheel）算法，包含 L0 和 L1 两层：

• L0 层（底层）: 处理短延迟任务

  • 槽位数量: 默认 512 个（可配置，必须是 2 的幂次方）
  • 时间精度: 默认 10ms（可配置）
  • 最大时间跨度: 5.12 秒

• L1 层（高层）: 处理长延迟任务

  • 槽位数量: 默认 64 个（可配置，必须是 2 的幂次方）
  • 时间精度: 默认 1 秒（可配置）
  • 最大时间跨度: 64 秒

• 轮次机制: 超出 L1 层范围的任务使用轮次计数处理

性能优化

• 使用 parking_lot::Mutex 替代标准库的 Mutex，提供更好的性能
• 使用 FxHashMap（rustc-hash）替代标准 HashMap，减少哈希冲突
• 槽位数量为 2 的幂次方，使用位运算优化取模操作
• 任务执行在独立的 tokio 任务中，避免阻塞时间轮推进

Structs

BatchConfig

批处理配置

BatchHandle

批量定时器句柄，用于管理批量调度的定时器

BatchHandleIter

BatchHandle 的迭代器

CallbackWrapper

回调包装器，用于规范化创建和管理回调

CompletionNotifier

完成通知器，用于在任务完成时发送通知

CompletionReceiver

完成通知接收器，用于接收定时器完成通知

HierarchicalWheelConfig

分层时间轮配置

ServiceConfig

服务配置

ServiceConfigBuilder

服务配置构建器

TaskId

定时器任务的唯一标识符

TimerConfig

顶层定时器配置

TimerConfigBuilder

顶层定时器配置构建器

TimerHandle

定时器句柄，用于管理定时器的生命周期

TimerService

TimerService - 基于 Actor 模式的定时器服务

TimerTask

定时器任务

TimerWheel

时间轮定时器管理器

WheelConfig

时间轮配置

WheelConfigBuilder

时间轮配置构建器

Enums

TaskCompletionReason

任务完成原因

TimerError

定时器错误类型

Traits

TimerCallback

定时器回调 trait