如何在模块中利用 ngx_add_timer 管理自定义定时器任务-Nginx-PHP中文网

Nginx模块中应使用ngx_event_add_timer而非ngx_add_timer来为ngx_event_t事件添加毫秒级相对超时；需独立分配并长期持有事件结构，设置handler与log，在handler中根据ev->timedout判断触发状态，周期任务需手动重设，注意worker级生命周期管理。

如何在模块中利用 ngx_add_timer 管理自定义定时器任务

在 Nginx 模块开发中，ngx_add_timer 并不是一个直接暴露给模块开发者的公共 API。它属于 Nginx 内部事件调度机制的一部分，通常由核心（如 ngx_event_timer_init）初始化后，通过 ngx_event_add_timer（注意：不是 ngx_add_timer）供模块使用。你真正能调用的是 ngx_event_add_timer，用于为一个已注册的事件（ngx_event_t *）添加超时时间。

1. 准备一个可重用的定时器事件结构

每个定时任务需绑定一个独立的 ngx_event_t 实例。不能复用连接或请求的事件，应自行分配并长期持有（例如挂到模块配置或周期性任务上下文中）。

在模块配置结构体中定义：ngx_event_t *my_timer;
在 create_conf 或初始化阶段用 ngx_pcalloc(cf->pool, sizeof(ngx_event_t)) 分配
设置 ev->handler = my_timer_handler;，指向你的回调函数
确保 ev->log 已正确赋值（如 cf->log），否则日志可能崩溃

2. 正确注册并启动定时器

调用 ngx_event_add_timer(ev, delay) 启动定时器。注意：

delay 单位是毫秒，且是**相对当前时间的偏移量**（非绝对时间）
该函数仅设置超时值，不触发 handler；Nginx 主循环会在到期时自动调用 ev->handler
若定时器已处于待触发/已触发状态，再次调用会更新超时时间（即“重设”）
必须保证 ev 在整个生命周期内有效（不能分配在栈上或短生命周期内存中）

3. 在 handler 中处理逻辑并决定是否重复

你的 my_timer_handler 是唯一执行业务的地方。典型模式如下：

先检查 ev->timedout —— 正常到期时为 1，被显式取消则为 0
执行实际任务（如清理缓存、上报指标、重试失败请求等）
如需周期执行，再次调用 ngx_event_add_timer(ev, interval)
若不再需要，可调用 ngx_del_timer(ev) 显式移除（非必须，但推荐）

示例 handler 片段：

static void
my_timer_handler(ngx_event_t *ev)
{
    my_ctx_t *ctx = ev->data;

    if (!ev->timedout) {
        return; // 被主动删除，跳过
    }

    ngx_log_debug0(NGX_LOG_DEBUG_HTTP, ev->log, 0, "my timer fired");

    // 执行你的任务...
    do_my_background_work(ctx);

    // 重新设定下一次（比如每 5 秒一次）
    ngx_event_add_timer(ev, 5000);
}