定时器的使用

timer.lua

基于分级时间轮（Hierarchical Timing Wheel）实现的高性能定时器模块，提供了创建、取消、延长、循环、单次触发、剩余时间查询等功能。

性能特征

  • create O(1)
  • cancel O(1) —— 双向链表直接摘除
  • extend O(1) —— cancel + create
  • dispatch O(k) —— k = 当前 tick 到期数量
  • 最大可调度延迟：67108863 ticks ≈ 671088 秒 ≈ 7.77 天
  • 内置对象池复用，减少 GC 压力

常量

常量 值 说明
M.loop 0 循环触发标记
M.second 100 1秒
M.minute 6000 1分钟
M.hour 360000 1小时
M.day 8640000 1天

创建定时器

  • M:new(expire, times, callback, …)
    描述: 创建一个定时器对象
    参数:
    - expire (number): 过期时间 100等于1秒
    - times (number): 次数，0表示循环触发
    - callback (function): 回调函数
    - … 回调参数
    返回值:

    1. timer_obj(table): 定时器对象

  • M:once(expire, callback, …)
    描述: 创建一个单次触发的定时器（等同于 M:new(expire, 1, callback, ...)）
    参数:
    - expire (number): 过期时间 100等于1秒
    - callback (function): 回调函数
    - … 回调参数
    返回值:

    1. timer_obj(table): 定时器对象

  • M:new_loop(expire, callback, …)
    描述: 创建一个循环定时器（等同于 M:new(expire, 0, callback, ...)）
    参数:
    - expire (number): 过期时间 100等于1秒
    - callback (function): 回调函数
    - … 回调参数
    返回值:

    1. timer_obj(table): 定时器对象

定时器对象方法

  • timer_obj:cancel()
    描述: 取消定时器
    返回值:

    1. timer_obj(table): 自身，支持链式调用

  • timer_obj:after_next()
    描述: 设置”之后下一次”模式：回调函数执行完再注册下一次，默认是先注册下一次再执行回调
    返回值:

    1. timer_obj(table): 自身，支持链式调用

  • timer_obj:extend(ex_expire)
    描述: 延长定时器触发时间
    参数:
    - ex_expire (number): 延长时间 100等于1秒
    返回值:

    1. timer_obj(table): 自身，支持链式调用
      说明:
      • 已取消或已完成的定时器调用无效
      • 延长时间会在当前剩余时间基础上追加

  • timer_obj:remain_expire()
    描述: 获取剩余触发时间
    返回值:

    1. remain(number): 剩余tick数，0表示已触发完或已取消

  • timer_obj:is_cancelled()
    描述: 是否已被取消
    返回值:

    1. ret(boolean)

  • timer_obj:is_finished()
    描述: 是否已完成（所有次数都触发了）
    返回值:

    1. ret(boolean)

  • timer_obj:is_loop()
    描述: 是否是循环定时器
    返回值:

    1. ret(boolean)

  • timer_obj:remain_times()
    描述: 剩余触发次数
    返回值:

    1. times(number): 剩余次数，0表示循环或已结束

  • timer_obj:is_valid()
    描述: 定时器是否仍有效（未取消且未完成）
    返回值:

    1. ret(boolean)

  • timer_obj:release()
    描述: 释放定时器对象，允许对象池回收复用
    说明:
    - 引用计数减1，当计数<=0且定时器已结束时归还对象池
    - 如果忘记调用，对象由Lua GC自然回收（不会泄漏）

全局配置

  • M.set_warn_threshold(ticks)
    描述: 设置回调执行耗时告警阈值
    参数:
    - ticks (number): 阈值（100=1秒），0表示不检测

  • M.set_pool_max(max)
    描述: 设置对象池最大缓存数量
    参数:
    - max (number): 最大数量，默认256

使用示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
local timer = require "skynet-fly.timer"

-- 5秒后单次触发
local t1 = timer:once(timer.second * 5, function(a, b)
    log.info("once fired!", a, b)
end, "hello", "world")

-- 循环定时器，每2秒触发
local t2 = timer:new_loop(timer.second * 2, function()
    log.info("loop tick")
end)

-- 触发3次，间隔1秒
local t3 = timer:new(timer.second, 3, function(count)
    log.info("fired", count)
end, 0)

-- 取消定时器
t2:cancel()

-- 延长定时器
t1:extend(timer.second * 3)  -- 再延长3秒

-- 查询状态
print(t1:is_valid())       -- true/false
print(t1:remain_expire())  -- 剩余tick数
print(t3:remain_times())   -- 剩余次数

-- 释放对象（可选，允许对象池复用）
t1:release()

timer_point

使用基础的timer.lua模块，封装的整点报时功能，功能的概念类似闹钟，比如设置每天下午2点半第30秒，就只需要这样设置。

1
2
3
4
5
6
7
8
9
10
11
12
local function call_back(a, b ,c, d)

end

local a,b,c,d = 1,2,3,4
local point = timer_point:new(time_point.EVERY_DAY)
:set_hour(14) --下午2点
:set_min(30)  --30分
:set_sec(30)  --30秒
:builder(call_back, a, b, c, d)

point:cancel()  --取消整点报时

目前支持设置的时间刻度有：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
local M = {
    --每分钟
    EVERY_MINUTE = 1,
    --每小时
    EVERY_HOUR = 2,
    --每天
    EVERY_DAY = 3,
    --每周
    EVERY_WEEK = 4,
    --每月 超过适配到最后一天
    EVERY_MOUTH = 5,
    --每年几月几日几时几分几秒 超过适配到最后一天
    EVERY_YEAR = 6,
    --每年的第几天 超过适配到最后一天
    EVERY_YEAR_DAY = 7,
}

  • new(type)
    函数作用域：M 对象的成员函数
    函数名称：new
    描述: 创建整点报时对象
    参数:
    - type (number): 时间刻度类型

  • set_month
    函数作用域：M:new 对象的成员函数
    函数名称：set_month
    描述: 指定几月,如果刻度不是每年的话，这个设置没有作用
    参数:
    - month (number): 月份 1-12

  • set_day
    函数作用域：M:new 对象的成员函数
    函数名称：set_day
    描述: 每月第几天,超过适配到最后一天，比如设置31天，这月只有30天，适配到30天触发。
    参数:
    - day (number): 天数 1-31

  • set_hour
    函数作用域：M:new 对象的成员函数
    函数名称：set_hour
    描述: 几时
    参数:
    - hour (number): 几时 0-23

  • set_min
    函数作用域：M:new 对象的成员函数
    函数名称：set_min
    描述: 几分
    参数:
    - min (number): 几分 0-59

  • set_sec
    函数作用域：M:new 对象的成员函数
    函数名称：set_sec
    描述: 几秒
    参数:
    - sec (number): 几秒 0-59

  • set_wday
    函数作用域：M:new 对象的成员函数
    函数名称：set_wday
    描述: 周几（仅仅设置每周有效）
    参数:
    - wday (number): 周几 1-7 星期天为 1

  • set_yday
    函数作用域：M:new 对象的成员函数
    函数名称：set_yday
    描述: 一年第几天（仅仅设置每年第几天有效）
    参数:
    - yday (number): 第几天 1-366 超过适配到最后一天。

  • builder
    函数作用域：M:new 对象的成员函数
    函数名称：builder
    描述: 构建。
    参数:
    - callback (function): 回调函数。
    - … (any): 回调参数。

skynet_fly_api
#skynet_fly_api
定时器的使用
https://huahua132.github.io/2024/01/21/skynet_fly_api/timer/
作者
huahua132
发布于
2024年1月21日
许可协议