Struct TimerWheel

Source

pub struct TimerWheel { /* private fields */ }

Expand description

时间轮定时器管理器

Implementations§

Source §

impl TimerWheel

Source

pub fn new(config: WheelConfig) -> Self

创建新的定时器管理器

§参数

config: 时间轮配置（已经过验证）

§示例

use kestrel_protocol_timer::{TimerWheel, WheelConfig};
use std::time::Duration;

#[tokio::main]
async fn main() {
    let config = WheelConfig::builder()
        .tick_duration(Duration::from_millis(10))
        .slot_count(512)
        .build()
        .unwrap();
    let timer = TimerWheel::new(config);
}

Source

pub fn with_defaults() -> Self

创建带默认配置的定时器管理器

tick 时长: 10ms
槽位数量: 512

§示例

use kestrel_protocol_timer::TimerWheel;

#[tokio::main]
async fn main() {
    let timer = TimerWheel::with_defaults();
}

Source

pub fn create_service(&self) -> TimerService

创建与此时间轮绑定的 TimerService（使用默认配置）

§返回

绑定到此时间轮的 TimerService 实例

§示例

use kestrel_protocol_timer::TimerWheel;
use std::time::Duration;

#[tokio::main]
async fn main() {
    let timer = TimerWheel::with_defaults();
    let mut service = timer.create_service();
     
    // 直接通过 service 批量调度定时器
    let callbacks: Vec<_> = (0..5)
        .map(|_| (Duration::from_millis(100), || async {}))
        .collect();
    service.schedule_once_batch(callbacks).await;
     
    // 接收超时通知
    let mut rx = service.take_receiver().unwrap();
    while let Some(task_id) = rx.recv().await {
        println!("Task {:?} completed", task_id);
    }
}

Source

pub fn create_service_with_config(&self, config: ServiceConfig) -> TimerService

创建与此时间轮绑定的 TimerService（使用自定义配置）

§参数

config: 服务配置

§返回

绑定到此时间轮的 TimerService 实例

§示例

use kestrel_protocol_timer::{TimerWheel, ServiceConfig};

#[tokio::main]
async fn main() {
    let timer = TimerWheel::with_defaults();
    let config = ServiceConfig::builder()
        .command_channel_capacity(1024)
        .timeout_channel_capacity(2000)
        .build()
        .unwrap();
    let service = timer.create_service_with_config(config);
}

Source

pub async fn schedule_once<C>( &self, delay: Duration, callback: C, ) -> TimerHandle
where C: TimerCallback,

调度一次性定时器

§参数

delay: 延迟时间
callback: 实现了 TimerCallback trait 的回调对象

§返回

返回定时器句柄，可用于取消定时器

§示例

use kestrel_protocol_timer::TimerWheel;
use std::time::Duration;
use std::sync::Arc;

#[tokio::main]
async fn main() {
    let timer = TimerWheel::with_defaults();
     
    let handle = timer.schedule_once(Duration::from_secs(1), || async {
        println!("Timer fired!");
    }).await;
     
    tokio::time::sleep(Duration::from_secs(2)).await;
}

Source

pub async fn schedule_once_batch<C>( &self, callbacks: Vec<(Duration, C)>, ) -> BatchHandle
where C: TimerCallback,

批量调度一次性定时器

§参数

tasks: (延迟时间, 回调) 的元组列表

§返回

返回批量定时器句柄

§性能优势

批量处理减少锁竞争
内部优化批量插入操作
共享 Wheel 引用减少内存开销

§示例

use kestrel_protocol_timer::TimerWheel;
use std::time::Duration;
use std::sync::Arc;
use std::sync::atomic::{AtomicU32, Ordering};

#[tokio::main]
async fn main() {
    let timer = TimerWheel::with_defaults();
    let counter = Arc::new(AtomicU32::new(0));
     
    // 动态生成批量回调
    let callbacks: Vec<(Duration, _)> = (0..3)
        .map(|i| {
            let counter = Arc::clone(&counter);
            let delay = Duration::from_millis(100 + i * 100);
            let callback = move || {
                let counter = Arc::clone(&counter);
                async move {
                    counter.fetch_add(1, Ordering::SeqCst);
                }
            };
            (delay, callback)
        })
        .collect();
     
    let batch = timer.schedule_once_batch(callbacks).await;
    println!("Scheduled {} timers", batch.len());
     
    // 批量取消所有定时器
    let cancelled = batch.cancel_all();
    println!("Cancelled {} timers", cancelled);
}

Source

pub async fn schedule_once_notify(&self, delay: Duration) -> TimerHandle

调度一次性通知定时器（无回调，仅通知）

§参数

delay: 延迟时间

§返回

返回定时器句柄，可通过 into_completion_receiver() 获取通知接收器

§示例

use kestrel_protocol_timer::TimerWheel;
use std::time::Duration;

#[tokio::main]
async fn main() {
    let timer = TimerWheel::with_defaults();
     
    let handle = timer.schedule_once_notify(Duration::from_secs(1)).await;
     
    // 获取完成通知接收器
    handle.into_completion_receiver().0.await.ok();
    println!("Timer completed!");
}

Source

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

取消定时器

§参数

task_id: 任务 ID

§返回

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

Source

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

批量取消定时器

§参数

task_ids: 要取消的任务 ID 列表

§返回

成功取消的任务数量

§性能优势

批量处理减少锁竞争
内部优化批量取消操作

§示例

use kestrel_protocol_timer::TimerWheel;
use std::time::Duration;

#[tokio::main]
async fn main() {
    let timer = TimerWheel::with_defaults();
     
    // 创建多个定时器
    let handle1 = timer.schedule_once(Duration::from_secs(10), || async {}).await;
    let handle2 = timer.schedule_once(Duration::from_secs(10), || async {}).await;
    let handle3 = timer.schedule_once(Duration::from_secs(10), || async {}).await;
     
    // 批量取消
    let task_ids = vec![handle1.task_id(), handle2.task_id(), handle3.task_id()];
    let cancelled = timer.cancel_batch(&task_ids);
    println!("已取消 {} 个定时器", cancelled);
}