Crate kestrel_timer 

高性能异步定时器系统 (High-Performance Async Timer System)

基于时间轮（Timing Wheel）算法实现的高性能异步定时器，支持 tokio 运行时。 (High-performance async timer based on Timing Wheel algorithm, supports tokio runtime)

特性 (Features)

• 高性能 (High Performance): 使用时间轮算法，插入和删除操作的时间复杂度为 O(1) (Uses timing wheel algorithm, insert and delete operations are O(1))
• 大规模支持 (Large-Scale Support): 能够高效管理 10000+ 并发定时器 (Efficiently manages 10000+ concurrent timers)
• 异步支持 (Async Support): 基于 tokio 异步运行时 (Based on tokio async runtime)
• 线程安全 (Thread-Safe): 使用 parking_lot 提供高性能的锁机制 (Uses parking_lot for high-performance locking mechanism)

快速开始 (Quick Start)

use kestrel_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 任务中，避免阻塞时间轮推进

English Architecture Description

Timing Wheel Algorithm

Uses hierarchical timing wheel algorithm with L0 and L1 layers:

• L0 Layer (Bottom): Handles short delay tasks

  • Slot count: Default 512, configurable, must be power of 2
  • Time precision: Default 10ms, configurable
  • Maximum time span: 5.12 seconds

• L1 Layer (Upper): Handles long delay tasks

  • Slot count: Default 64, configurable, must be power of 2
  • Time precision: Default 1 second, configurable
  • Maximum time span: 64 seconds

• Round Mechanism: Tasks beyond L1 range use round counting

Performance Optimization

• Uses parking_lot::Mutex instead of standard library Mutex for better performance
  • Uses FxHashMap (rustc-hash) instead of standard HashMap to reduce hash collisions
  • Slot count is power of 2, uses bitwise operations to optimize modulo
  • Task execution in separate tokio tasks to avoid blocking timing wheel advancement

Structs

BatchConfig

批处理配置 (Batch Processing Configuration)

BatchHandle

批量定时器句柄，用于管理批量调度的定时器 (Batch timer handle for managing batch-scheduled timers)

BatchHandleIter

BatchHandle 的迭代器 (Iterator for BatchHandle)

CallbackWrapper

回调包装器，用于规范化创建和管理回调 (Callback wrapper for standardized callback creation and management)

CompletionNotifier

完成通知器，用于在任务完成时发送通知 (Completion notifier for sending notifications when tasks complete)

CompletionReceiver

完成通知接收器，用于接收定时器完成通知 (Completion receiver for receiving timer completion notifications)

ServiceConfig

服务配置 (Service Configuration)

ServiceConfigBuilder

服务配置构建器 (Service Configuration Builder)

TaskId

定时器任务的唯一标识符 (Unique identifier for timer tasks)

TimerConfig

顶层定时器配置 (Top-level Timer Configuration)

TimerConfigBuilder

顶层定时器配置构建器 (Top-level Timer Configuration Builder)

TimerHandle

定时器句柄，用于管理定时器的生命周期 (Timer handle for managing timer lifecycle)

TimerService

TimerService - 基于 Actor 模式的定时器服务 (TimerService - timer service based on Actor pattern)

TimerTask

定时器任务 (Timer Task)

TimerWheel

时间轮定时器管理器 (Timing Wheel Timer Manager)

WheelConfig

时间轮配置 (Timing Wheel Configuration)

WheelConfigBuilder

时间轮配置构建器 (Timing Wheel Configuration Builder)

Enums

TaskCompletionReason

任务完成原因 (Task Completion Reason)

TimerError

定时器错误类型 (Timer Error Type)

Traits

TimerCallback

定时器回调 trait (Timer Callback Trait)