PHP pcntl_async_signals 怎么实现收到信号后的优雅退出

PHP CLI 常驻脚本收到 SIGTERM 或 SIGINT 后，优雅退出的关键不是在信号处理器里立刻 exit，而是先记录“准备停止”，让主循环停止领取新任务，完成当前任务后再集中释放资源。pcntl_async_signals(true) 会启用异步分发，pcntl_signal() 负责注册处理器；处理器保持轻量，清理动作放进主流程的 finally。

官方手册：https://www.php.net/manual/en/function.pcntl-async-signals.php

把信号处理器当成“写状态”的入口，把主循环当成“做收尾”的地方，就能避免当前任务被硬切、资源没有关闭和重复清理。

为什么只在信号处理器里 exit 会丢任务

一次常见故障是消费者正在处理消息时收到停止信号，处理器直接调用 exit，进程看似退出了，但当前消息的确认、临时文件关闭或锁释放没有机会完成。另一种写法是把数据库关闭、日志落盘等耗时逻辑全部塞进处理器，结果信号重入时又触发第二次清理。

PHP 手册说明，pcntl_signal() 会安装或替换指定信号的处理器；启用异步分发后，处理器可以在脚本执行期间被调用。这个机制适合改变状态，不适合承担完整的业务收尾。

先注册信号，再让主循环读取停止标志

最小实现可以只维护一个布尔值。处理器收到两个常见的终止信号时只设置标志并记录信号编号；主循环每次准备领取新任务前读取标志。这样，正在执行的任务可以自然返回，下一轮不再取新任务。

这里的重点是“停止领取新任务”而不是“立刻停止当前任务”。如果 receiveTask() 可能长时间阻塞，应给它设置超时或使用可被信号打断的等待方式，否则标志虽然已经改变，主循环仍然无法及时观察到。

把清理动作放回主流程

连接、临时文件、锁和指标句柄都应该由主流程统一关闭。用 try/finally 包住任务循环，即使任务抛出异常，也能走到同一处释放逻辑；信号处理器只负责改变退出条件。

示例中的函数是业务占位名，重点在职责分配：信号处理器不碰连接，主循环不重复打开资源，finally 是所有正常结束和异常结束路径的共同出口。生产代码还应让清理函数具备幂等性，避免任务内部已经关闭文件后，finally 再次关闭导致新的异常。

重复信号、阻塞调用和人工派发怎么处理

优雅退出常见的复发点有三个。第一，多个 SIGTERM 到达时只需要把标志保持为 true，不要在处理器里重复释放资源。第二，阻塞的网络或队列调用要有超时，否则无法及时回到主循环。第三，如果项目没有启用异步分发，也可以在主循环中调用 pcntl_signal_dispatch() 手动处理待处理信号，但要保证循环有足够频率。

可以按下面的清单收尾：

• 处理器只写停止标志和信号编号，不直接关闭连接或删除临时文件。
• 领取任务设置超时，当前任务有明确的最大执行边界。
• 统一在 finally 中释放资源，清理函数允许重复调用。
• 将 SIGTERM、SIGINT 和异常退出分别记录，便于定位停止原因。

相关问题

pcntl_async_signals(true) 会替代 pcntl_signal() 吗？

不会。前者负责启用或关闭异步分发，后者负责为具体信号安装处理器，两者通常配合使用。

为什么不在处理器里直接清空队列？

处理器应尽量短小，复杂清理可能与当前业务操作交叉。记录状态后由主循环收尾，更容易控制资源依赖和异常路径。