PHP pcntl_sigprocmask 怎样在关键区间暂时屏蔽信号

我在 PHP CLI 的常驻任务里遇到过一种很隐蔽的中断：文件刚写完索引还没落盘，进程就收到了 SIGTERM。如果这段工作必须保持连续，可以用 pcntl_sigprocmask() 暂时屏蔽指定信号；关键不是“屏蔽后就不管了”，而是先保存旧屏蔽集合，离开临界区后再原样恢复。

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

要暂时追加屏蔽信号，用 SIG_BLOCK；要恢复进入临界区前的完整状态，用 SIG_SETMASK 配合第三个参数保存的旧数组。不要用空数组或无条件的“解除全部”代替恢复。

一、问题现场：临界区被外部信号切开了

这类故障通常不是信号“消失”，而是信号到达时，任务正处在多个动作之间：数据文件已经替换，索引文件还没更新，或者事务边界外又多做了一步清理。直接把整个进程改成忽略信号会掩盖问题；更稳妥的边界是只临时调整屏蔽集合。

需要先分清三个概念：pcntl_signal() 安装的是处理器，pcntl_signal_dispatch() 负责手动分发，而 pcntl_sigprocmask() 只读写当前进程的 blocked signals。本文只讨论最后一项，不把它扩展成退出回调方案。

二、触发条件：SIG_BLOCK 追加而不是覆盖

PHP 手册定义了三种模式：SIG_BLOCK 把给定信号加入当前屏蔽集合，SIG_UNBLOCK 移除给定信号，SIG_SETMASK 则用给定集合替换当前屏蔽集合。临界区通常应该从 SIG_BLOCK 开始，因为调用方可能早已屏蔽了另一类信号。

这里的 $oldSignals 不是“本次新增的信号”，而是调用前的完整集合。假设上层已经屏蔽了 SIGHUP，当前代码又追加了 SIGTERM，恢复时应回到只含 SIGHUP 的状态，而不是把所有信号都解除。

三、修复动作：把恢复放在 finally

恢复动作必须和屏蔽动作成对出现，最小边界通常就是一个 try...finally。这样业务函数正常返回、抛出异常或上层捕获异常时，都有机会执行 SIG_SETMASK。如果只在函数末尾写恢复语句，一旦中间抛出异常，后续代码会继续处于临时屏蔽状态，排查时就会出现“信号为什么一直不处理”的假象。

我会把“取得旧集合”和“进入关键工作”放在同一层，避免在更深层函数里重新调用 SIG_BLOCK 却忘了保存自己的旧状态。若确实存在嵌套临界区，每一层都应保存自己的数组并按相反顺序恢复。

四、防复发：检查版本、数组和运行环境

PHP 手册当前说明，pcntl_sigprocmask() 成功返回 true，失败返回 false；从 PHP 8.4 起，非法模式或非法信号值会抛出 ValueError，非整数信号值会抛出 TypeError，空信号数组在非 SIG_SETMASK 模式下也有额外限制。因此生产代码要同时处理返回值和可能的参数异常。

常见问题

用 SIG_UNBLOCK 清除本次屏蔽可以吗？

不适合作为通用恢复方案。它只能移除你指定的信号，无法还原调用前可能已经存在的其他屏蔽关系；保存旧集合后用 SIG_SETMASK 更准确。

屏蔽 SIGTERM 后信号会永久丢失吗？

屏蔽与丢弃不是同一个概念。本文只讨论延后处理的临界区；是否排队、何时分发以及最终如何退出，还要结合操作系统和 PHP 的信号分发策略设计。

为什么不直接忽略 SIGINT？

忽略会改变进程语义，而且没有保存原状态。临界区结束后应该回到进入前的屏蔽集合，不能把“暂时保护”扩大成“整个进程都不响应”。