Crate kestrel_timer 

High-Performance Async Timer System

High-performance async timer based on Timing Wheel algorithm, supports tokio runtime

Features

• High Performance: Uses timing wheel algorithm, insert and delete operations are O(1)
• Large-Scale Support: Efficiently manages 10000+ concurrent timers
• Async Support: Based on tokio async runtime
• Thread-Safe: Uses parking_lot for high-performance locking mechanism

高性能异步定时器库

基于分层时间轮算法的高性能异步定时器库，支持 tokio 运行时

特性

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

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>> {
    // Create timer manager (创建定时器管理器)
    let timer = TimerWheel::with_defaults();
     
    // Step 1: Create timer task (使用回调创建定时器任务)
    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();
     
    // Step 2: Register timer task and get completion notification (注册定时器任务并获取完成通知)
    let handle = timer.register(task);
     
    // Wait for timer completion (等待定时器完成)
    let (rx, _handle) = handle.into_parts();
    rx.0.await?;
    Ok(())
}

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

中文架构说明

时间轮算法

采用分层时间轮（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 任务中，避免阻塞时间轮推进

Re-exports

pub use task::CallbackWrapper;

pub use task::TaskId;

pub use task::TimerTask;

pub use task::TaskCompletionReason;

pub use timer::handle::TimerHandle;

pub use timer::handle::TimerHandleWithCompletion;

pub use timer::handle::BatchHandle;

pub use timer::handle::BatchHandleWithCompletion;

pub use timer::handle::CompletionReceiver;

pub use timer::TimerWheel;

Modules

config

Timer Configuration Module

error

task

timer

wheel

Structs

TimerService

TimerService - timer service based on Actor pattern Manages multiple timer handles, listens to all timeout events, and aggregates TaskId to be forwarded to the user.