跳到主要内容

GTimer - 高性能时间轮定时器

基于多级时间轮算法的高精度定时器服务，专为GS语言游戏服务器设计

📋 目录​

快速开始​

安装​

# 在package.json中添加依赖
"dependencies": {
  "pkg.gtimer": "^1.0.0"
}

10秒上手示例​

import pkg.gtimer;
import gs.util.time;

// 1. 初始化定时器服务（程序启动时执行一次）
gtimer.init_timer_service((: time.time_ms :));

// 2. 创建一次性定时器（1000ms后执行）
int timer_id = gtimer.create_timer(time.time_ms() + 1000, 1, 0, parallel () {
    printf("定时器触发！\n");
});

// 3. 删除定时器（可选）
gtimer.delete_timer(timer_id);

// 4. 程序关闭时清理
gtimer.shutdown_timer_service();

🌱 入门级：基本概念​

什么是GTimer？​

GTimer是一个高性能定时器服务，用于在指定时间触发回调函数。它基于时间轮算法实现，能够：

  • ✅ 精确到毫秒级的定时触发
  • ✅ 支持一次性和循环定时器
  • ✅ 支持动态间隔（固定值或函数计算）
  • ✅ 支持最长约34.8年的定时范围
  • ✅ 线程安全的并行调用

核心概念​

1. 定时器ID​

每个定时器都有唯一的ID，用于标识和管理：

int timer_id = gtimer.create_timer(...);  // 返回定时器ID
gtimer.delete_timer(timer_id);            // 通过ID删除定时器

2. 触发时间（dst_timeout_ms）​

定时器的绝对触发时间（毫秒时间戳）：

import gs.util.time;

// 1秒后触发
int trigger_time = time.time_ms() + 1000;
gtimer.create_timer(trigger_time, 1, 0, callback);

// 立即触发（传0）
gtimer.create_timer(0, 1, 0, callback);

3. 循环次数（loop_count）​

控制定时器执行次数：

// 执行1次（一次性定时器）
gtimer.create_timer(time.time_ms() + 1000, 1, 0, callback);

// 执行5次
gtimer.create_timer(time.time_ms() + 1000, 5, 1000, callback);

// 无限循环（传-1）
gtimer.create_timer(time.time_ms() + 1000, -1, 1000, callback);

4. 循环间隔（interval_ms）​

重要：间隔参数支持两种类型：

固定间隔（int类型）​
// 每隔1000ms执行一次
gtimer.create_timer(time.time_ms() + 1000, -1, 1000, callback);
动态间隔（function类型）​
// 间隔函数接收上次触发时间，返回下次间隔
parallel function calc_interval = parallel (int last_trigger_ms) {
    // 可以根据业务逻辑动态计算间隔
    return random(500, 2000);  // 随机500-2000ms
};

gtimer.create_timer(time.time_ms() + 1000, -1, calc_interval, callback);

⚠️ 注意：

  • 间隔函数必须是parallel函数
  • 函数必须返回int类型（下次间隔的毫秒数）
  • 不允许跨域调用或阻塞操作

5. 回调函数（callback）​

定时器触发时执行的函数：

// 定义并行回调函数（强制要求）
public parallel void my_timer_callback()
{
    printf("定时器被触发了！\n");
    // 执行业务逻辑
}

// 创建定时器
gtimer.create_timer(time.time_ms() + 1000, 1, 0, (: my_timer_callback :));

⚠️ 强制要求：

  • 回调函数必须是parallel函数
  • 这确保高性能的并行执行
  • 避免频繁跨域导致性能问题

基础示例​

示例1：简单一次性定时器​

import pkg.gtimer;
import gs.util.time;

// 3秒后执行一次
parallel void on_timer_triggered()
{
    printf("3秒已到！\n");
}

void setup_timer()
{
    int trigger_time = time.time_ms() + 3000;
    int timer_id = gtimer.create_timer(trigger_time, 1, 0, (: on_timer_triggered :));
    printf("创建定时器，ID: %d\n", timer_id);
}

示例2：固定间隔循环定时器​

// 每隔1秒执行一次，共执行10次
parallel void heartbeat()
{
    printf("心跳检测...\n");
    check_server_status();
}

void setup_heartbeat()
{
    int start_time = time.time_ms() + 1000;  // 1秒后开始
    gtimer.create_timer(start_time, 10, 1000, (: heartbeat :));
}

示例3：无限循环定时器​

int _save_timer_id = 0;

parallel void auto_save()
{
    printf("自动保存游戏数据...\n");
    save_all_player_data();
}

void setup_auto_save()
{
    // 每5分钟自动保存一次，无限循环
    int start_time = time.time_ms() + 300000;  // 5分钟后开始
    _save_timer_id = gtimer.create_timer(start_time, -1, 300000, (: auto_save :));
}

void stop_auto_save()
{
    gtimer.delete_timer(_save_timer_id);
}

示例4：动态间隔定时器​

// 根据服务器负载动态调整检查间隔
parallel int calculate_check_interval(int last_trigger_ms)
{
    float load = get_server_load();
    if (load > 0.8)
        return 500;   // 高负载时500ms检查一次
    else if (load > 0.5)
        return 2000;  // 中负载时2秒检查一次
    else
        return 5000;  // 低负载时5秒检查一次
}

parallel void check_server()
{
    printf("服务器检查...\n");
}

void setup_dynamic_timer()
{
    gtimer.create_timer(
        time.time_ms() + 1000,
        -1,  // 无限循环
        (: calculate_check_interval :),
        (: check_server :)
    );
}

常见错误示例​

❌ 错误1：回调函数不是parallel​

// ❌ 错误：普通函数作为回调
void my_callback()  // 缺少parallel关键字
{
    printf("这会导致错误！\n");
}

gtimer.create_timer(time.time_ms() + 1000, 1, 0, (: my_callback :));
// 错误信息：定时器回调函数无效 或者不是并行方法

✅ 正确做法：

// ✅ 正确：使用parallel函数
public parallel void my_callback()
{
    printf("正确的回调！\n");
}

gtimer.create_timer(time.time_ms() + 1000, 1, 0, (: my_callback :));

❌ 错误2：循环定时器间隔为0或负数​

// ❌ 错误：循环定时器间隔必须大于0
gtimer.create_timer(time.time_ms() + 1000, -1, 0, callback);
// 错误信息：循环定时器的间隔参数必须大于0

✅ 正确做法：

// ✅ 正确：指定合理的间隔
gtimer.create_timer(time.time_ms() + 1000, -1, 1000, callback);

❌ 错误3：触发时间超出范围​

// ❌ 错误：触发时间过大
int far_future = time.time_ms() + 40 * 365 * 24 * 3600 * 1000;  // 40年后
gtimer.create_timer(far_future, 1, 0, callback);
// 错误信息：定时器触发时间不能大于 init_ms + MAX_INTERVAL

✅ 正确做法：

// ✅ 正确：使用合理的时间范围（最大约34.8年）
int reasonable_future = time.time_ms() + 30 * 24 * 3600 * 1000;  // 30天后
gtimer.create_timer(reasonable_future, 1, 0, callback);

❌ 错误4：在回调中跨域调用​

object _user_manager = nil;  // 在其他域的对象

// ❌ 错误：回调中进行跨域调用会影响性能
public parallel void bad_callback()
{
    // 这是跨域调用，会降低性能
    _user_manager=>process_timeout_users();
}

✅ 正确做法：

// ✅ 正确：使用消息队列或其他机制通知其他域
readonly queue _timer_events := queue.create("timer_events");

public parallel void good_callback()
{
    // 发送事件到队列，避免直接跨域调用
    _timer_events.send_dup({"event": "timeout_check"});
}

🌿 进阶级：内部原理​

时间轮算法详解​

什么是时间轮？​

时间轮是一种高效的定时器数据结构，类似于手表的表盘：

        [0级轮 - 秒针]
           256个槽
    每槽代表 1ms
    ┌─────────────┐
    │  [0][1][2]  │ ← 当前槽
    │ [255] ... [3]│
    └─────────────┘
         ↓
    轮转一圈后驱动
         ↓
    [1级轮 - 分针]
       256个槽
  每槽代表 256ms

GTimer使用5级时间轮，形成一个层次结构：

轮级每槽时长总时长比喻
0级1ms256ms秒针
1级256ms65.5秒分针
2级65.5秒4.66小时时针
3级4.66小时49.7天日历
4级49.7天34.8年年历

定时器分配策略​

当创建一个定时器时，系统会从高级轮向低级轮查找合适的位置：

// 核心算法：add_timer_to_wheel()
for (int i = 4; i >= 0; i--)  // 从4级轮开始
{
    CTimeWheel wheel = wheels[i];
    int slot_idx = get_slot_idx_in_child(timer.dst_timeout_ms, i);
    int wheel_offset = slot_idx - wheel.current_slot;

    if (wheel_offset == 0)
        continue;  // 【情况1】当前槽位，继续向下查找

    if (wheel_offset > 0)
    {
        wheel.get_slot(slot_idx).add_timer(timer);  // 【情况2】未来槽位
        return;
    }

    trigger_timer(timer);  // 【情况3】过期槽位，立即触发
    return;
}

trigger_timer(timer);  // 【情况4】精确当前时刻

4种分配情况图解：

假设当前时间：1000ms，定时器触发时间：1500ms

计算过程：
1. 相对时间 = 1500 - init_ms
2. 在1级轮的槽位 = (相对时间 >> 8) & 255
3. wheel_offset = 目标槽 - 当前槽

【情况1】wheel_offset == 0（当前槽位）
    ┌─────┐
    │ ● ← │ 目标就在这个槽
    └─────┘
    继续向下级轮查找精确位置

【情况2】wheel_offset > 0（未来槽位）
    ┌─────┐
    │ →   │ 当前槽
    │   ● │ 目标槽（后面）
    └─────┘
    放入目标槽，等待轮转

【情况3】wheel_offset < 0（过期槽位）
    ┌─────┐
    │ ●   │ 目标槽（已过）
    │   ← │ 当前槽
    └─────┘
    立即触发执行

【情况4】所有轮都是当前槽
    所有轮的wheel_offset都为0
    说明触发时间就是现在
    立即触发执行

槽的两种类型​

EventSlot（事件槽）- 0级轮专用​

class CEventSlot
{
    private array timers;  // 定时器数组

    // 触发时直接执行所有定时器
    public void fire()
    {
        for (timer : timers)
        {
            scheduler.trigger_timer(timer);  // 直接触发
        }
    }
}

特点：

  • 只在0级轮使用
  • 槽被触发时直接执行定时器回调
  • 执行完成后处理循环逻辑

ContainerSlot（容器槽）- 1-4级轮专用​

class CContainerSlot
{
    private array timers;
    private CTimeWheel wheel;

    // 触发时重新分配到子轮
    public void fire()
    {
        CTimeWheel child_wheel = wheel.get_child();
        for (timer : timers)
        {
            int slot_idx = scheduler.get_slot_idx_in_child(
                timer.dst_timeout_ms,
                child_wheel.index
            );
            child_wheel.get_slot(slot_idx).add_timer(timer);  // 分配到子轮
        }
    }
}

特点：

  • 在1-4级轮使用
  • 槽被触发时将定时器重新分配到下级轮
  • 实现时间精度的逐级细化

图解槽的触发过程：

高级轮触发 → 重新分配到低级轮 → 最终在0级轮执行

[4级轮 slot_10]
    ↓ 轮转到，触发
    ↓
[3级轮 slot_25]  ← 重新计算分配
    ↓ 继续轮转
    ↓
[2级轮 slot_100] ← 再次分配
    ↓
[1级轮 slot_50]  ← 再次分配
    ↓
[0级轮 slot_200] ← 最终执行
    ↓
 执行回调函数

驱动机制​

单协程驱动模型​

// TimerD中的驱动协程
private void drive_timer_loop()
{
    while (true)
    {
        // 1. 处理命令队列（添加/删除定时器）
        process_timer_commands();

        // 2. 驱动时间轮
        _timer_scheduler.drive_time_wheels(get_time_ms());

        // 3. 协程睡眠1ms，保证精度
        coroutine.sleep(0.001);
    }
}

驱动流程：

每1ms一次循环：
  ┌────────────────────┐
  │ 1. 处理命令队列    │ ← 添加/删除定时器
  ├────────────────────┤
  │ 2. 驱动0级时间轮   │ ← current_ms++
  │    ├─ 触发当前槽   │
  │    └─ 可能驱动上级轮│
  ├────────────────────┤
  │ 3. 协程睡眠1ms     │ ← 精度控制
  └────────────────────┘

时间跳跃优化​

当检测到空槽时，系统会跳过空隙，加速时间推进：

// 优化：如果当前槽没有定时器，直接跳到下一个有定时器的槽
if (wheel_index > 0 && slot.get_timer_count() == 0)
{
    // 查找下一个有定时器的槽位
    array next_slot = scheduler.get_target_time_wheel_slot_with_overdue();

    if (can_skip)
    {
        // 直接跳跃时间
        int accelerate_gap = get_wheel_interval(wheel_index);
        scheduler.drive_accelerate_current_time(accelerate_gap);
    }
}

完整示例：游戏Buff系统​

// 游戏Buff定时器示例
class BuffManager
{
    private map _active_buffs;  // buff_id -> timer_id

    // 添加Buff（10秒后过期）
    public void add_buff(int player_id, int buff_id, int duration_ms)
    {
        int expire_time = time.time_ms() + duration_ms;

        int timer_id = gtimer.create_timer(
            expire_time,
            1,  // 执行1次
            0,
            parallel () {
                this.on_buff_expired(player_id, buff_id);
            }
        );

        _active_buffs[buff_id] = timer_id;
        printf("玩家%d的Buff%d将在%dms后过期\n", player_id, buff_id, duration_ms);
    }

    // Buff过期回调
    public parallel void on_buff_expired(int player_id, int buff_id)
    {
        printf("玩家%d的Buff%d已过期\n", player_id, buff_id);
        remove_buff_from_player(player_id, buff_id);
        _active_buffs.delete(buff_id);
    }

    // 手动移除Buff
    public void remove_buff(int buff_id)
    {
        int timer_id = _active_buffs[buff_id];
        if (timer_id)
        {
            gtimer.delete_timer(timer_id);
            _active_buffs.delete(buff_id);
        }
    }
}

🌿 进阶级：内部原理​

架构设计​

整体架构图​

┌─────────────────────────────────────────┐
│          gtimer.gs (对外接口层)          │
│  - init_timer_service()                 │
│  - create_timer()                       │
│  - delete_timer()                       │
│  - shutdown_timer_service()             │
└──────────────┬──────────────────────────┘
               │ 委托调用
               ↓
┌─────────────────────────────────────────┐
│        TimerD (服务管理层)               │
│  - 独立域(domain)                       │
│  - 驱动协程(coroutine)                  │
│  - 命令队列(queue)                      │
│  - 原子ID生成器(atomic)                 │
└──────────────┬──────────────────────────┘
               │ 管理
               ↓
┌─────────────────────────────────────────┐
│   TimerScheduler (调度核心层)           │
│  - 5级时间轮数组                        │
│  - 活跃定时器映射表                     │
│  - 时间轮驱动逻辑                       │
│  - 定时器分配算法                       │
└──────────────┬──────────────────────────┘
               │ 组织
               ↓
┌─────────────────────────────────────────┐
│      TimeWheel (时间轮层)               │
│  - 256个槽(Slot)                        │
│  - 父子轮级联                           │
│  - 槽位计算                             │
└──────────────┬──────────────────────────┘
               │ 包含
               ↓
┌─────────────────────────────────────────┐
│     Slot (槽位层)                       │
│  - EventSlot: 直接触发(0级轮)           │
│  - ContainerSlot: 重新分配(1-4级轮)     │
└──────────────┬──────────────────────────┘
               │ 持有
               ↓
┌─────────────────────────────────────────┐
│    TaskTimer (定时器实体层)             │
│  - timer_id                             │
│  - dst_timeout_ms                       │
│  - callback                             │
│  - loop_count                           │
│  - interval_ms                          │
└─────────────────────────────────────────┘

核心组件详解​

1. TimerD - 服务管理器​

职责：

  • 服务生命周期管理（初始化/关闭）
  • 独立域隔离（避免竞态条件）
  • 驱动协程管理
  • 命令队列处理
  • 原子ID生成

关键设计：

#pragma disable_new_object  // 禁止外部创建实例

parallel int _timer_id_generator := 1;       // 原子ID生成器
readonly coroutine _drive_coroutine := nil;  // 驱动协程
readonly queue _timer_commands := nil;       // 命令队列
CTimerScheduler _timer_scheduler = nil;      // 调度器实例

并行接口设计：

// 并行接口：无锁创建定时器
public parallel int create_timer(int dst_timeout_ms, int loop_count,
                                  mixed interval_ms, function callback)
{
    // 1. 原子操作生成唯一ID
    int timer_id = atomic.lock_fetch_add("_timer_id_generator", 1);

    // 2. 创建命令对象
    CTimerCommand cmd = CTimerCommand.new(TimerOp.ADD_TIMER, timer_id, ...);

    // 3. 投递到队列（无锁操作）
    _timer_commands.send_dup(cmd);

    return timer_id;
}

为什么使用队列？

  • ✅ 解耦：业务线程和定时器线程分离
  • ✅ 无锁：避免锁竞争，提高并发性能
  • ✅ 异步：调用立即返回，不阻塞
  • ✅ 顺序：保证命令按顺序处理

2. TimerScheduler - 调度核心​

职责：

  • 管理5级时间轮
  • 维护活跃定时器映射表
  • 实现定时器分配算法
  • 处理循环定时器逻辑

核心数据结构：

class CTimerScheduler
{
    private array wheels;          // 5级时间轮数组
    private map active_timers;     // timer_id -> CTaskTimer
    private int current_ms;        // 当前毫秒计数
    private int init_ms;           // 初始化时间戳
    private int target_ms;         // 当前帧目标时间
}

槽位计算公式：

// 计算定时器在指定轮中的槽索引
public int get_slot_idx_in_child(int dst_timeout_ms, int wheel_id)
{
    int ms = dst_timeout_ms - init_ms;

    // wheel_id << 3 相当于 wheel_id * 8
    // 每个轮占8位（256 = 2^8）
    int result = (ms >> (wheel_id << 3)) & 255;

    return result;
}

示例计算：

假设：
- init_ms = 0
- dst_timeout_ms = 300000 (5分钟)
- 二进制: 0x493E0 = 0000 0000 0000 0100 1001 0011 1110 0000

计算各级轮的槽位：
- 0级轮: (0x493E0 >> 0) & 0xFF = 0xE0 = 224
- 1级轮: (0x493E0 >> 8) & 0xFF = 0x3E = 62
- 2级轮: (0x493E0 >> 16) & 0xFF = 0x49 = 73
- 3级轮: (0x493E0 >> 24) & 0xFF = 0x00 = 0
- 4级轮: (0x493E0 >> 32) & 0xFF = 0x00 = 0

3. TimeWheel - 时间轮​

职责：

  • 管理256个槽位
  • 处理父子轮级联
  • 驱动槽位轮转
  • 触发到期槽位

轮级联关系：

// 初始化时建立父子关系
public void init_wheels()
{
    CTimeWheel child = nil;
    for (int i = 0; i < 5; i++)
    {
        wheels[i] = CTimeWheel.new(i, 256, scheduler, child);
        child = wheels[i];  // 下一轮的child是当前轮
    }
}

驱动逻辑：

public void drive_once()
{
    // 槽位满了？
    if (current_slot == slot_count - 1)
    {
        if (parent_wheel)
            parent_wheel.drive_once();  // 驱动上级轮（进位）
        else
            error("超出时间轮最大运行时间限制!");

        current_slot = 0;  // 归零
    }
    else
    {
        current_slot++;  // 槽位+1
    }

    // 触发当前槽
    slots[current_slot].fire();
}

4. TaskTimer - 定时器实体​

职责：

  • 存储定时器元数据
  • 处理循环间隔计算
  • 管理定时器生命周期

核心字段：

class CTaskTimer
{
    private int timer_id;          // 定时器ID
    private function callback;     // 回调函数（必须parallel）
    private int dst_timeout_ms;    // 目标触发时间
    private int loop_count;        // 剩余循环次数
    private bool is_dead;          // 是否已死亡
    private mixed interval_ms;     // 间隔参数（int或function）
}

循环定时器处理：

// 定时器触发后的循环处理
public void trigger_timer(CTaskTimer timer)
{
    // 执行回调
    execute_timer(timer);

    // 处理循环逻辑
    if (timer.loop_count == -1)  // 无限循环
    {
        timer.update_next_loop_time();
        add_timer_to_wheel(timer);  // 重新添加到时间轮
    }
    else if (timer.loop_count > 1)  // 还有剩余次数
    {
        timer.add_loop_count(-1);
        timer.update_next_loop_time();
        add_timer_to_wheel(timer);
    }
    else
    {
        delete_timer_directly(timer.timer_id);  // 销毁
    }
}

动态间隔计算：

public void update_next_loop_time()
{
    if (is_function(interval_ms))
    {
        // 调用函数计算下次间隔
        int next_interval = interval_ms.call_local(dst_timeout_ms);
        dst_timeout_ms += next_interval;
    }
    else  // 固定间隔
    {
        dst_timeout_ms += interval_ms;
    }
}

并发控制详解​

无锁并行设计​

业务协程（多个）              定时器协程（单个）
    │                              │
    ├─ create_timer() ─┐          │
    │                  │          │
    ├─ create_timer() ─┼─→ [队列] ┼─→ process_commands()
    │                  │          │        ↓
    ├─ delete_timer() ─┘          │   调度器处理
    │                              │        ↓
                                   │   驱动时间轮
                                   │        ↓
                                   │   触发回调（并行）
                                   │        ↓
                                 触发    触发    触发
                                   ↓      ↓      ↓
                              callback callback callback
                              (并行执行，无需跨域)

关键技术：

  1. 原子ID生成：
int timer_id = atomic.lock_fetch_add("_timer_id_generator", 1);
// 无锁并发安全，性能极高
  1. 队列通信：
readonly queue _timer_commands;
_timer_commands.send_dup(cmd);  // 无锁异步投递
  1. 独立域隔离：
load_static(TimerD, domain.create("TimerD"));  // 专用域
  1. 并行回调：
public parallel void callback()  // 强制parallel
{
    // 无需域切换，直接执行
}

时间复杂度分析​

创建定时器：O(1)​

create_timer()
  → atomic.lock_fetch_add()     // O(1) 原子操作
  → CTimerCommand.new()         // O(1) 对象创建
  → queue.send_dup()            // O(1) 队列入队

总复杂度：O(1)

删除定时器：O(1)​

delete_timer()
  → CTimerCommand.new()         // O(1)
  → queue.send_dup()            // O(1)

总复杂度：O(1)

添加到时间轮：O(1)​

add_timer_to_wheel()
  → for i in [4, 3, 2, 1, 0]   // O(5) = O(1) 常数次循环
    → get_slot_idx_in_child()   // O(1) 位运算
    → slot.add_timer()          // O(1) 数组追加

总复杂度：O(1)

驱动时间轮：O(N/256)​

drive_time_wheels()
  → drive_once() on 0级轮      // O(1)
    → slot.fire()               // O(K) K=该槽定时器数量

平均情况：假设有N个定时器均匀分布在256个槽
  每槽平均定时器数：K = N/256

平均复杂度：O(N/256)

对比传统方案：

操作传统堆实现时间轮实现优势
创建定时器O(log N)O(1)🚀 快数百倍
删除定时器O(log N)O(1)🚀 快数百倍
驱动触发O(log N)O(N/256)✓ 分摊开销

数据流转详解​

创建定时器的完整流程​

[业务代码]
    │
    ├─ gtimer.create_timer(trigger_time, count, interval, callback)
    │
    ↓
[gtimer.gs 接口层]
    │
    ├─ 委托给 TimerD.create_timer()
    │
    ↓
[TimerD 服务层 - parallel函数，可并行调用]
    │
    ├─ 1. atomic.lock_fetch_add() 生成唯一ID
    ├─ 2. CTimerCommand.new() 创建命令对象
    ├─ 3. cmd.check_valid() 验证参数
    └─ 4. _timer_commands.send_dup(cmd) 投递到队列
        │
        ↓
[驱动协程 - 独立线程运行]
    │
    ├─ process_timer_commands() 处理队列
    │   │
    │   ├─ 取出所有命令：_timer_commands.receive_all()
    │   │
    │   └─ switch (cmd.op_type)
    │       ├─ ADD_TIMER:
    │       │   └─ _timer_scheduler.add_timer(cmd)
    │       │
    │       └─ DEL_TIMER:
    │           └─ _timer_scheduler.delete_timer(cmd.timer_id)
    │
    ↓
[TimerScheduler 调度层]
    │
    ├─ add_timer(cmd)
    │   ├─ 1. CTaskTimer.new() 创建定时器对象
    │   ├─ 2. active_timers[timer_id] = timer 加入映射表
    │   └─ 3. add_timer_to_wheel(timer) 分配到时间轮
    │       │
    │       └─ 从4级轮开始查找合适位置
    │           ├─ 计算槽位: slot_idx = get_slot_idx_in_child()
    │           ├─ 计算偏移: offset = slot_idx - current_slot
    │           │
    │           ├─ offset == 0: 继续向下查找
    │           ├─ offset > 0: wheel.get_slot(slot_idx).add_timer(timer)
    │           └─ offset < 0: trigger_timer(timer) 立即触发
    │
    ↓
[TimeWheel 时间轮层]
    │
    └─ Slot.add_timer(timer)
        │
        ├─ EventSlot (0级轮):
        │   └─ timers.push_back(timer)  直接加入数组
        │
        └─ ContainerSlot (1-4级轮):
            └─ timers.push_back(timer)  加入数组待分配

定时器触发的完整流程​

[驱动协程每1ms执行]
    │
    ├─ drive_time_wheels(current_time_ms)
    │
    ↓
[TimerScheduler]
    │
    ├─ while (current_ms < target_ms)
    │   │
    │   ├─ wheels[0].drive_once()  驱动0级轮
    │   └─ current_ms++
    │
    ↓
[TimeWheel - 0级轮]
    │
    ├─ current_slot++  槽位推进
    │
    ├─ 如果current_slot == 255（满了）
    │   ├─ parent_wheel.drive_once()  驱动上级轮（进位）
    │   └─ current_slot = 0
    │
    ├─ slots[current_slot].fire()  触发当前槽
    │
    ↓
[EventSlot.fire() - 0级轮槽]
    │
    ├─ 取出所有定时器
    │
    └─ for (timer : timers)
        │
        ├─ 跳过已死亡的定时器
        │
        └─ scheduler.trigger_timer(timer)
            │
            ├─ execute_timer(timer)
            │   └─ timer.trigger()
            │       └─ callback.call_local()  执行回调
            │
            └─ 处理循环逻辑
                │
                ├─ loop_count == -1 (无限循环)
                │   ├─ update_next_loop_time()  计算下次时间
                │   └─ add_timer_to_wheel(timer)  重新添加
                │
                ├─ loop_count > 1 (还有次数)
                │   ├─ loop_count--
                │   ├─ update_next_loop_time()
                │   └─ add_timer_to_wheel(timer)
                │
                └─ else (执行完毕)
                    └─ delete_timer_directly(timer_id)  销毁
[ContainerSlot.fire() - 1-4级轮槽]
    │
    ├─ 取出所有定时器
    │
    └─ for (timer : timers)
        │
        └─ 重新分配到子轮
            │
            ├─ child_wheel = wheel.get_child()
            ├─ slot_idx = get_slot_idx_in_child(timer.dst_timeout_ms, child_wheel.index)
            └─ child_wheel.get_slot(slot_idx).add_timer(timer)

说明：
- 高级轮槽被触发时，不直接执行定时器
- 而是将定时器重新分配到下级轮，获得更精确的时间定位
- 最终定时器会层层下沉到0级轮被执行

时间跳跃优化机制​

为什么需要优化？​

传统方式：逐毫秒驱动
current_ms: 1000 → 1001 → 1002 → ... → 5000
            ↓      ↓      ↓             ↓
         检查槽  检查槽  检查槽  ...  检查槽
         (空)   (空)   (空)        (有定时器)

问题：如果未来4秒都没有定时器，会空转4000次！

优化方案：

// 检测到空槽时，查找下一个有定时器的槽
if (wheel_index > 0 && slot.get_timer_count() == 0)
{
    // 获取目标时间对应的最高级过期槽位
    array [wheel_id, slot_id] = get_target_time_wheel_slot_with_overdue();

    if (wheel_id > wheel_index)
    {
        // 可以跳跃！
        int gap = get_wheel_interval(wheel_index);  // 如1级轮=256ms
        scheduler.drive_accelerate_current_time(gap);
        continue_driving = true;
    }
}

跳跃效果：

优化后：
current_ms: 1000 ──跳跃256ms──→ 1256 ──跳跃256ms──→ 1512 → ... → 5000
                                                            ↓
                                                        找到定时器

优化收益：

  • 当定时器稀疏分布时，性能提升数倍到数十倍
  • 避免无效的槽位检查
  • CPU占用大幅降低

🌳 高级：性能优化​

最佳实践​

1. 回调函数设计​

✅ 推荐做法：轻量级回调 + 消息传递

readonly queue _game_events := queue.create("game_events");

// ✅ 好的做法：回调中只做轻量级操作
public parallel void on_pvp_timeout()
{
    // 发送事件消息
    _game_events.send_dup({
        "type": "pvp_timeout",
        "timestamp": time.time_ms()
    });
}

// 在游戏主循环中处理事件
void game_loop()
{
    while (true)
    {
        array events = _game_events.receive_all();
        for (event : events)
        {
            process_game_event(event);  // 在主线程处理
        }
    }
}

❌ 避免做法：回调中执行重度操作

// ❌ 避免：回调中执行数据库操作
public parallel void bad_callback()
{
    // 这会阻塞定时器驱动协程！
    database.save_player_data(player_id);  // 可能耗时数百ms

    // 这会导致其他定时器延迟触发
}

2. 定时器粒度控制​

原则：根据业务需求选择合适的精度

// ✅ 好：秒级精度的任务使用秒级间隔
gtimer.create_timer(
    time.time_ms() + 60000,  // 1分钟后
    -1,
    60000,  // 每60秒执行
    (: hourly_task :)
);

// ❌ 避免：过度精确反而浪费
gtimer.create_timer(
    time.time_ms() + 60001,  // 没必要精确到1ms
    -1,
    59999,  // 间隔也不需要这么精确
    (: hourly_task :)
);

建议粒度：

  • 实时战斗逻辑：10-50ms
  • Buff/Debuff：100-500ms
  • 定期任务：1-60秒
  • 日常刷新：分钟-小时级

3. 定时器生命周期管理​

✅ 推荐模式：集中管理

class TimerManager
{
    private map _active_timers;  // name -> timer_id

    public void add_timer(string name, int delay, int loop, int interval, function cb)
    {
        // 先清理旧定时器
        remove_timer(name);

        // 创建新定时器
        int timer_id = gtimer.create_timer(
            time.time_ms() + delay,
            loop,
            interval,
            cb
        );

        _active_timers[name] = timer_id;
    }

    public void remove_timer(string name)
    {
        int timer_id = _active_timers[name];
        if (timer_id)
        {
            gtimer.delete_timer(timer_id);
            _active_timers.delete(name);
        }
    }

    public void clear_all()
    {
        for (name, timer_id : _active_timers)
        {
            gtimer.delete_timer(timer_id);
        }
        _active_timers.clear();
    }
}

4. 内存优化​

问题：大量短周期定时器导致频繁创建/销毁

优化方案：批量处理

// ❌ 避免：为每个玩家创建独立定时器
for (player : all_players)
{
    gtimer.create_timer(time.time_ms() + 1000, 1, 0, parallel () {
        check_player_status(player);  // 1000个定时器
    });
}

// ✅ 推荐：使用单个定时器批量处理
gtimer.create_timer(time.time_ms() + 1000, -1, 1000, parallel () {
    // 一个定时器处理所有玩家
    array players = get_all_online_players();
    for (player : players)
    {
        check_player_status(player);
    }
});

收益：

  • 内存占用降低1000倍
  • 创建/销毁开销降低1000倍
  • 驱动效率提升（槽中定时器更少）

5. 动态间隔优化​

✅ 好的用法：根据业务状态动态调整

map _boss_state = {"hp_percent": 100};

parallel int calculate_boss_check_interval(int last_time)
{
    int hp_percent = _boss_state["hp_percent"];

    if (hp_percent < 10)
        return 100;   // 残血阶段每100ms检查
    else if (hp_percent < 50)
        return 500;   // 半血阶段每500ms检查
    else
        return 2000;  // 满血阶段每2秒检查
}

parallel void check_boss_skill()
{
    // 检查Boss技能释放
}

gtimer.create_timer(
    time.time_ms() + 1000,
    -1,
    (: calculate_boss_check_interval :),
    (: check_boss_skill :)
);

优势：

  • 根据实际需要调整检查频率
  • 降低不必要的CPU开销
  • 提升系统整体性能

6. 错误处理​

✅ 推荐：监控定时器创建失败

int timer_id = gtimer.create_timer(...);
if (timer_id == -1)
{
    LOG_ERROR(L_GAME, "定时器创建失败！检查参数是否正确");
    // 记录错误日志
    // 尝试降级处理
}

✅ 推荐：监控活跃定时器数量

// 定期检查定时器数量
parallel void monitor_timer_count()
{
    int count = gtimer.get_active_timer_count();
    if (count > 50000)
    {
        LOG_WARN(L_GAME, "活跃定时器过多: %d，可能存在泄漏", count);
    }
}

// 每分钟检查一次
gtimer.create_timer(time.time_ms() + 60000, -1, 60000, (: monitor_timer_count :));

调试技巧​

1. 使用dump_timer_status()​

// 输出定时器内部状态
gtimer.dump_timer_status();

// 输出示例：
=== TimerScheduler Status Dump ===
Current time: 123456789 ms
Active timers: 1523
Statistics:
Time wheels status:
  Wheel[0]: current_slot=45
    slot[45]: 12 timers
    slot[100]: 5 timers
  Wheel[0] total: 17 timers
  Wheel[1]: current_slot=123
    slot[123]: 8 timers
  Wheel[1] total: 8 timers
  ...
Active timer details:
  Timer[1]: dst_timeout_ms=123457000, loop_count=5, interval_ms=1000, dead=false
  Timer[2]: dst_timeout_ms=123460000, loop_count=-1, interval_ms=function, dead=false
=== End of Status Dump ===

2. 监控轮盘执行计数​

import pkg.gtimer.monitor.TimerCounterD;

// 重置计数器
GTIMER_MONITOR_RESET();

// 运行一段时间...
coroutine.sleep(10);

// 输出统计
GTIMER_MONITOR_DUMP();

// 输出示例：
wheel execute counter: {
    "wheel_0_execute_counter": 10000,  // 0级轮执行了10000次
    "wheel_1_execute_counter": 39,     // 1级轮执行了39次
    "wheel_2_execute_counter": 0,      // 2级轮未执行
    "wheel_3_execute_counter": 0,
    "wheel_4_execute_counter": 0
}

分析：

  • wheel_0_execute_counter：应该约等于运行时间（ms）
  • 如果1-4级轮计数异常高，可能有问题

3. 检查定时器泄漏​

// 定期检查活跃定时器趋势
int _last_timer_count = 0;

parallel void check_timer_leak()
{
    int current_count = gtimer.get_active_timer_count();
    int delta = current_count - _last_timer_count;

    if (delta > 100)
    {
        LOG_WARN(L_GAME, "定时器数量增长异常：从%d增长到%d",
                 _last_timer_count, current_count);
        gtimer.dump_timer_status();  // 输出详情
    }

    _last_timer_count = current_count;
}

高级应用场景​

场景1：分布式定时任务​

// 多服务器环境下的定时任务协调
class DistributedTimer
{
    private int _server_id;
    private int _server_count;

    // 只在负责的服务器上执行
    public parallel void distributed_task()
    {
        int hash = hash_current_time();
        if (hash % _server_count == _server_id)
        {
            execute_global_task();  // 只有一个服务器会执行
        }
    }

    public void setup()
    {
        gtimer.create_timer(
            time.time_ms() + 60000,
            -1,
            60000,
            (: distributed_task :)
        );
    }
}

场景2：自适应定时器​

// 根据系统负载自适应调整频率
parallel int adaptive_interval(int last_time)
{
    float cpu_usage = system.get_cpu_usage();
    float memory_usage = system.get_memory_usage();

    // 系统压力大时降低检查频率
    if (cpu_usage > 0.9 || memory_usage > 0.9)
        return 5000;   // 高压力：5秒
    else if (cpu_usage > 0.7 || memory_usage > 0.7)
        return 2000;   // 中压力：2秒
    else
        return 1000;   // 低压力：1秒
}

gtimer.create_timer(
    time.time_ms() + 1000,
    -1,
    (: adaptive_interval :),
    (: system_health_check :)
);

场景3：定时器池模式​

// 复用定时器，避免频繁创建销毁
class TimerPool
{
    private array _pool;
    private int _pool_size;

    public void init(int size)
    {
        _pool = array.allocate(size);
        _pool_size = size;

        // 预创建定时器池
        for (int i = 0; i < size; i++)
        {
            _pool[i] = {
                "timer_id": -1,
                "in_use": false,
                "callback": nil
            };
        }
    }

    public int acquire_timer(int delay, function cb)
    {
        // 从池中获取空闲定时器
        for (int i = 0; i < _pool_size; i++)
        {
            if (!_pool[i]["in_use"])
            {
                _pool[i]["in_use"] = true;
                _pool[i]["callback"] = cb;

                int timer_id = gtimer.create_timer(
                    time.time_ms() + delay,
                    1,
                    0,
                    parallel () {
                        this.on_pooled_timer_fired(i);
                    }
                );

                _pool[i]["timer_id"] = timer_id;
                return timer_id;
            }
        }

        return -1;  // 池已满
    }

    public parallel void on_pooled_timer_fired(int pool_idx)
    {
        function cb = _pool[pool_idx]["callback"];

        // 执行回调
        if (cb)
            cb.call_local();

        // 归还到池
        _pool[pool_idx]["in_use"] = false;
        _pool[pool_idx]["callback"] = nil;
    }
}

性能陷阱​

陷阱1：过多的极短周期定时器​

// ❌ 性能陷阱：1000个10ms周期的定时器
for (int i = 0; i < 1000; i++)
{
    gtimer.create_timer(time.time_ms() + 10, -1, 10, parallel () {
        fast_check();
    });
}

// 问题：每10ms触发1000次回调，CPU占用极高

✅ 解决方案：合并或分时执行

// ✅ 方案1：合并为单个定时器
gtimer.create_timer(time.time_ms() + 10, -1, 10, parallel () {
    for (int i = 0; i < 1000; i++)
    {
        fast_check();
    }
});

// ✅ 方案2：分时执行（每次只处理100个）
int _current_batch = 0;

gtimer.create_timer(time.time_ms() + 10, -1, 10, parallel () {
    int start = _current_batch * 100;
    int end = math.min(start + 100, 1000);

    for (int i = start; i < end; i++)
    {
        fast_check();
    }

    _current_batch = (_current_batch + 1) % 10;
});

陷阱2：定时器泄漏​

class Player
{
    private int _buff_timer_id;

    // ❌ 陷阱：玩家下线没清理定时器
    public void on_player_logout()
    {
        save_data();
        // 忘记删除定时器！
        // _buff_timer_id对应的定时器会一直存在
    }
}

✅ 解决方案：使用defer或析构函数

class Player
{
    private int _buff_timer_id;

    public void on_player_logout()
    {
        defer cleanup_timers();  // 确保清理
        save_data();
    }

    private void cleanup_timers()
    {
        if (_buff_timer_id > 0)
        {
            gtimer.delete_timer(_buff_timer_id);
            _buff_timer_id = 0;
        }
    }

    // 或使用析构函数
    public void __destruct()
    {
        cleanup_timers();
    }
}

陷阱3：间隔函数中的错误返回值​

// ❌ 陷阱：返回无效值
parallel int bad_interval_func(int last_time)
{
    mixed result = calculate_something();
    return result;  // 可能返回nil、负数等无效值
}

// 导致错误：定时器interval_ms函数返回无效值

✅ 解决方案：严格验证返回值

// ✅ 正确：确保返回有效值
parallel int safe_interval_func(int last_time)
{
    int interval = calculate_dynamic_interval();

    // 验证并限制范围
    if (interval <= 0)
        interval = 1000;  // 默认值

    interval = math.clamp(interval, 100, 60000);  // 限制范围

    return interval;
}

API参考​

初始化与关闭​

init_timer_service(function fn_get_time_ms)​

初始化定时器服务（全局只调用一次）。

参数：

  • fn_get_time_ms: 获取当前时间毫秒数的函数

示例：

import gs.util.time;
gtimer.init_timer_service((: time.time_ms :));

注意：

  • 必须在使用定时器前调用
  • 重复调用会被忽略
  • 使用独立域确保线程安全

shutdown_timer_service()​

关闭定时器服务，清理所有资源。

示例：

gtimer.shutdown_timer_service();

注意：

  • 关闭后所有定时器失效
  • 驱动协程被停止
  • 命令队列被销毁

定时器操作​

create_timer(int dst_timeout_ms, int loop_count, mixed interval_ms, function callback)​

创建定时器并返回定时器ID。

参数：

  • dst_timeout_ms (int): 目标触发时间（绝对毫秒时间戳）

    • 范围：[0, MAX_INTERVAL) 约34.8年
    • 0表示立即执行
    • 必须 < init_ms + MAX_INTERVAL

  • loop_count (int): 循环次数

    • 1: 一次性定时器
    • >1: 执行指定次数
    • -1: 无限循环

  • interval_ms (mixed): 循环间隔

    • int类型：固定间隔（毫秒）
    • function类型：动态间隔函数
      • 签名：parallel int func(int last_trigger_ms)
      • 必须返回int（下次间隔ms）

  • callback (function): 回调函数

    • 必须是parallel函数
    • 签名：public parallel void callback()

返回值：

  • 成功：定时器ID（正整数）
  • 失败：-1

示例：

// 一次性定时器
int id1 = gtimer.create_timer(time.time_ms() + 5000, 1, 0, parallel () {
    printf("5秒后触发\n");
});

// 固定间隔循环
int id2 = gtimer.create_timer(time.time_ms() + 1000, 10, 1000, parallel () {
    printf("每秒触发，共10次\n");
});

// 动态间隔
int id3 = gtimer.create_timer(
    time.time_ms() + 1000,
    -1,
    parallel (int last_time) { return random(500, 2000); },
    parallel () { printf("随机间隔触发\n"); }
);

delete_timer(int timer_id)​

删除指定ID的定时器。

参数：

  • timer_id (int): 要删除的定时器ID

示例：

int timer_id = gtimer.create_timer(...);
// 稍后删除
gtimer.delete_timer(timer_id);

注意：

  • 删除不存在的ID不会报错
  • 删除后定时器立即失效
  • 监控会记录：delete_timer_not_found_count

监控与调试​

get_active_timer_count()​

获取当前活跃定时器数量。

返回值：活跃定时器数量（int）

示例：

int count = gtimer.get_active_timer_count();
printf("当前活跃定时器：%d个\n", count);

dump_timer_status()​

输出定时器内部状态（用于调试）。

示例：

gtimer.dump_timer_status();

输出内容：

  • 当前时间
  • 活跃定时器数量
  • 各级时间轮状态
  • 每个槽的定时器分布
  • 活跃定时器详细信息

设计思想​

为什么选择时间轮？​

对比传统方案​

方案插入删除查找最小空间优缺点
有序链表O(N)O(N)O(1)O(N)❌ 插入删除慢
最小堆O(log N)O(log N)O(1)O(N)⚠️ 中等性能
红黑树O(log N)O(log N)O(log N)O(N)⚠️ 实现复杂
时间轮O(1)O(1)O(1)O(M)✅ 高性能

时间轮的优势：

  1. O(1)复杂度：创建、删除都是常数时间
  2. 分摊触发：每个槽平均定时器少，触发快
  3. 空间可控：固定槽位数（5×256=1280个槽）
  4. 适合游戏：大量定时器场景性能最优

设计权衡​

精度 vs 性能​

精度提升 → 更多时间轮 → 内存增加
    ↓           ↓            ↓
当前设计： 5级轮   1ms精度   ~60KB基础开销

可选方案：
- 4级轮：10ms精度，~50KB，适合低精度需求
- 6级轮：1ms精度支持更长时间，~70KB

当前配置：

  • 精度：1ms（满足绝大多数游戏需求）
  • 范围：34.8年（远超游戏运行周期）
  • 内存：60KB + 150B×N（N为活跃定时器数）

单协程 vs 多协程​

当前设计：单协程驱动

优点：

  • ✅ 简单可靠
  • ✅ 无锁设计
  • ✅ 顺序保证

缺点：

  • ⚠️ 单核CPU利用
  • ⚠️ 回调阻塞影响全局

为什么不用多协程？

  1. 定时器触发本身是轻量操作（O(1)）
  2. 实际耗时在回调执行，回调已经是并行的
  3. 多协程会引入复杂的同步问题
  4. 实测单协程性能已经足够

技术亮点​

1. 无锁并发设计​

// 业务代码可以从任意协程并行调用
parallel int create_timer(...)  // 无锁
{
    int id = atomic.lock_fetch_add("_timer_id_generator", 1);  // 原子操作
    _timer_commands.send_dup(cmd);  // 无锁队列
    return id;
}

2. 域隔离保护​

// TimerD在独立域运行
load_static(TimerD, domain.create("TimerD"));

// 优势：
// - 避免与业务逻辑竞争
// - 驱动协程不受其他域影响
// - 内部数据天然线程安全

3. 位运算优化​

// 槽位计算使用位运算，极快
int slot_idx = (ms >> (wheel_id << 3)) & 255;

// 相当于：
int slot_idx = (ms / (256 ^ wheel_id)) % 256;
// 但位运算快10倍以上

4. 死亡标记延迟清理​

// 删除定时器时只标记，不立即清理
public void delete_timer(int timer_id)
{
    timer.mark_dead();  // 标记为死亡
    active_timers.delete(timer_id);
}

// 触发时跳过死亡定时器
public void fire()
{
    for (timer : timers)
    {
        if (timer.is_dead())
            continue;  // 跳过
        trigger_timer(timer);
    }
}

// 优势：
// - 避免从数组中删除（O(N)操作）
// - 延迟到触发时批量清理
// - 减少内存分配开销

常见问题​

Q1: 定时器的精度是多少？​

A：理论精度1ms，实际精度取决于：

  • 协程调度开销（~0.1-0.5ms）
  • 回调执行时间
  • 系统负载

建议：不要依赖绝对精确的1ms，允许±5ms的误差。

Q2: 可以创建多少个定时器？​

A：理论上无限制，实际受限于：

  • 内存：每个定时器约150字节
    • 10万个定时器：~15MB
    • 100万个定时器：~150MB

建议：

  • 一般游戏服：1万-10万个
  • 如果超过10万，考虑优化设计（批量处理）

Q3: 定时器可以跨域调用吗？​

A：回调函数必须是parallel，不允许跨域。

原因：

  • 定时器在独立域的单协程中驱动
  • 跨域调用会导致域切换，严重影响性能
  • parallel回调可以无域切换直接执行

解决方案：使用消息队列通知其他域

readonly queue _notifications := queue.create("notifications");

public parallel void timer_callback()
{
    _notifications.send_dup({"event": "timeout"});  // 发送消息
}

Q4: 如何处理服务器时间跳变？​

A：GTimer基于相对时间设计，受绝对时间影响小。

但如果时间大幅回退（如NTP同步），可能导致：

  • 定时器提前触发
  • 部分定时器延迟触发

建议：

  • 使用单调时钟作为时间源
  • 或在时间跳变时重置定时器服务

Q5: 定时器执行顺序是什么？​

A：同一槽内的定时器按添加顺序执行。

// 都在当前时间触发
gtimer.create_timer(0, 1, 0, parallel () { printf("A\n"); });
gtimer.create_timer(0, 1, 0, parallel () { printf("B\n"); });
gtimer.create_timer(0, 1, 0, parallel () { printf("C\n"); });

// 输出：
// A
// B
// C

注意：不同槽的定时器顺序由时间轮决定。

总结​

核心要点​

  1. 高性能：O(1)创建、删除，基于时间轮算法
  2. 高精度：1ms级别精度，5级时间轮
  3. 大范围：支持最长约34.8年的定时
  4. 线程安全：无锁并发设计，原子操作
  5. 灵活：支持固定/动态间隔，一次性/循环定时器

使用检查清单​

  • 初始化时调用init_timer_service()
  • 回调函数必须是parallel
  • 间隔函数必须是parallel且返回有效int
  • 触发时间在合理范围内（< 34.8年）
  • 循环定时器的间隔>0
  • 及时删除不需要的定时器
  • 监控活跃定时器数量
  • 关闭时调用shutdown_timer_service()

适用场景​

✅ 推荐使用：

  • Buff/Debuff系统
  • 技能冷却
  • 定时刷新（怪物、资源等）
  • 定期任务（日常、周常等）
  • 会话超时
  • 心跳检测
  • 延迟操作

❌ 不推荐：

  • 微秒级精度需求（使用GS内置timer）
  • 实时性要求极高的战斗逻辑（直接在主循环处理）
  • 一次性简单延迟（使用coroutine.sleep）

参考资料​

作者: hongkx 项目: pkg.gtimer 协议: MIT 版本: 1.0.0