PHP pcntl_signal 异步回调如何避免重入

在 PHP CLI 常驻脚本里，pcntl_async_signals(true) 会让注册过的信号处理器在脚本执行期间被异步调度。真正容易出问题的地方不是“回调能不能收到信号”，而是回调里直接刷新配置、写数据库或发起下一轮任务，导致同一业务动作在上一次尚未结束时再次进入。

官方地址：https://www.php.net/manual/en/function.pcntl-signal.php

先把信号回调变成轻量入口

pcntl_signal() 会为指定信号安装或替换处理器；处理器可以接收信号编号和可选的信号信息。它适合做“通知入口”，不适合承载一段可能阻塞的业务流程。尤其是多个相同信号接连到达时，回调里的刷新逻辑会把重入问题藏在异步时机里。

更稳妥的接口边界是：SIGUSR1 只表达“有刷新请求”，SIGTERM 只表达“请求在安全点退出”。回调不打开文件、不访问数据库、不调用刷新函数，只修改共享状态。

这里的 pending 也可以设计成布尔值。如果业务只关心“至少刷新一次”，计数会被合并成一次消费；如果每个信号都代表不可丢失的独立事件，就不能简单合并，而应把事件写入可靠队列。本文讨论的是常见的刷新、重载或重新读取配置场景。

让主循环独占真正的业务动作

回调变轻后，还需要在调用方设置明确的重入闸门。主循环每次看到 pending 时，先判断 busy；任务开始前置为 true，在 finally 中恢复为 false。这样即使任务期间又收到信号，也只会留下下一次消费的状态，不会嵌套调用 doRefresh()。

 0 && !$busy) {
        $pending = 0;
        $busy = true;
        try {
            doRefresh();
        } finally {
            // 无论业务成功或抛错，都必须释放重入闸门。
            $busy = false;
        }
    }

    // 阻塞等待可能被信号打断，下一轮仍要重新判断状态。
    sleep(1);
}

// 在退出前做资源释放、日志落盘等安全收尾。

这个结构的关键不是把信号“锁住”，而是让回调和业务拥有不同职责：回调收集状态，主循环决定时机。若刷新过程中又收到三个 SIGUSR1，它们通常只需要合并为一次后续刷新；若必须保留每次事件，则应把 $pending 换成有容量和失败策略的队列。

用可观察结果确认没有重入

验证时不要只看“脚本没有报错”。给每次刷新记录开始、结束和当前任务标识，并在入口处记录 busy 状态。正常结果应满足：同一任务标识不会出现交叠的开始记录；busy=true 期间收到信号只增加待处理状态；异常退出也会经过 finally 释放闸门。

还要留意阻塞调用的语义。PHP 手册说明，异步或 tick 分发时，像 sleep() 这样的阻塞函数可能被信号打断。因此循环不能把一次 sleep() 当作精确计时器；每次回到主循环都应重新判断待处理状态和退出标记。

常见问题

把处理器替换成另一个回调，会形成回调栈吗？

不会。pcntl_signal() 对同一信号是安装或替换处理器，不是自动叠加多个处理器。需要组合职责时，建议保留一个轻量入口，再把状态交给主循环或明确的分发函数。

为什么不用在回调里直接调用刷新函数？

因为回调触发时机由信号决定，可能打断当前工作；直接执行耗时逻辑会让资源边界、异常处理和重复请求都变得不可预测。把动作放回主循环，才能用 busy 和 finally 明确控制一次性执行。

归纳起来，避免 pcntl_signal 异步回调重入的最小方案是“回调只记状态、主循环串行消费、任务结束必释放闸门”。如果信号代表不可丢失事件，再把状态变量升级为可靠队列，而不要用一个计数器掩盖丢失语义。