delayqueue

Overview ¶

Package delayqueue 提供定点单次触发的延迟任务原语:注册一个未来时刻要执行的 回调,到点由后台 goroutine 触发;支持按 key 取消 / 改期。

与相邻原语的分工:

• pkg/scheduler 是即时工作池(投递即尽快执行),本包是"定点单次"(delay 后触发);
• pkg/service/cron 是周期任务(反复触发),本包是一次性(触发即销毁);
• pkg/ephemeral 是 TTL KV(到点删数据),本包是到点跑回调(可视作 ephemeral 的 "过期即回调"版)。

典型场景(实时游戏 / 社交):开局倒计时、buff/静音到期、房间空闲踢人、订单 15 分钟未支付取消、匹配 60s 超时兜底、限时活动结束结算。

实现:最小堆(按触发时刻排序)+ 单 goroutine 定时器驱动,堆顶最近到期时间用 一个 time.Timer 等待;Schedule/Cancel 通过唤醒信号让驱动 goroutine 重算等待时长。 回调在独立 goroutine 执行(复用 pkg/safe,panic 被恢复),不阻塞驱动循环。

零值不可用,用 New 构造。并发安全。Stop 后驱动 goroutine 退出,未触发的任务丢弃。