PHP pcntl_waitpid 怎么非阻塞检查子进程是否退出

在 PHP CLI 的多进程 worker 里，如果主进程直接调用 pcntl_waitpid($pid, $status, 0)，就会一直等到目标子进程结束；主循环因此无法继续接收任务或处理其它子进程。需要边轮询边做事时，把第三个参数改成 WNOHANG：子进程还没退出就立即返回 0，已经退出则返回被回收的 PID，调用失败才返回 -1。

先分清阻塞等待和非阻塞轮询

pcntl_waitpid() 的第二个参数是引用传出的 status，第三个参数是等待选项。选项为 0 时，当前进程会等目标子进程结束；选项包含 WNOHANG 时，如果目标子进程暂时还没结束，函数会马上把控制权交回主循环。

可以把返回值先按三个结果处理。只有返回正数 PID 时，status 才代表一次成功回收得到的状态；返回 0 时不要读取它当退出码；返回 -1 时则应按调用错误处理。

WNOHANG 返回 0 时不要误判成退出成功

这是最容易写错的地方。0 描述的是“这次调用没有等到已退出的子进程”，不是子进程执行了 exit(0)。如果把它当成成功退出，worker 可能提前删除仍在工作的 PID，后续也就失去了回收入口。

轮询频率也要有边界：循环过快会空转占用 CPU，间隔过长又会延迟回收。常见做法是每轮先检查一遍已经结束的 PID，再处理一小批业务，必要时用很短的休眠让出调度时间。

拿到目标 PID 后再解析 status

成功回收后，status 不是一个可以直接打印的业务退出码，而是操作系统编码后的状态信息。先用 pcntl_wifexited($status) 判断是否正常退出，只有它为真时才调用 pcntl_wexitstatus($status) 读取子进程传入的退出码。

如果使用 pcntl_wifsignaled() 分支，pcntl_wtermsig() 能补充终止信号。这样日志里可以区分“业务返回非零”与“进程被信号结束”，调度器才能决定重试、降级还是直接停止。

把回收动作放进 worker 管理循环

非阻塞等待的价值不在于单独调用一次，而在于它成为主进程的固定回收步骤。下面的结构保存 PID 到任务名的映射，每轮先扫一遍，已退出的子进程从表中删除，仍运行的子进程留到下一轮。

 'import-orders',
    $pidB => 'rebuild-index',
];

while ($children !== []) {
    foreach ($children as $pid => $taskName) {
        $status = 0;
        $result = pcntl_waitpid((int) $pid, $status, WNOHANG);

        if ($result === 0) {
            // 该任务还没结束，保留映射并继续处理其它任务。
            continue;
        }

        if ($result === -1) {
            // 失败时不要假装已回收；保留上下文并让上层决定退出策略。
            error_log("waitpid failed for {$taskName}, pid={$pid}");
            continue;
        }

        if (pcntl_wifexited($status)) {
            $code = pcntl_wexitstatus($status);
            error_log("{$taskName} exited with code {$code}");
        } elseif (pcntl_wifsignaled($status)) {
            $signal = pcntl_wtermsig($status);
            error_log("{$taskName} was terminated by signal {$signal}");
        }

        // 只有成功返回已等待的 PID 后才移除记录。
        unset($children[$pid]);
    }

    if ($children !== []) {
        // 避免没有退出子进程时持续空转；间隔按任务时延调整。
        usleep(20_000);
    }
}
?>

这里的关键顺序是“返回 PID—解析 status—删除 PID”。如果先删除映射，再遇到 -1，主进程就很难判断这个子进程到底是已经被其它代码回收，还是 waitpid 调用失败。

几个容易混淆的边界

• 把 0 当退出码：WNOHANG 下它表示未回收到子进程，与 exit(0) 没有同一层含义。
• 直接读取 pcntl_wexitstatus()：先确认 pcntl_wifexited() 为真，否则返回值没有正常退出语义。
• 只等一个 PID 却想回收全部子进程：传入正数 PID 只关注该 PID；调度器需要遍历自己的 PID 表，或根据需求使用其它 process_id 语义。
• 重复等待已经回收的 PID：成功返回后应从管理表删除，避免把后续的 -1 误认为新故障。

相关问题

pcntl_waitpid 返回 0 是错误吗？

不是。在使用 WNOHANG 时，它表示指定的子进程还没有退出，本轮调用没有发生回收。

什么时候可以读取退出码？

先确认 waitpid 返回目标 PID，再确认 pcntl_wifexited($status) 为真，之后才读取 pcntl_wexitstatus($status)。

子进程被信号杀死时怎样记录？

用 pcntl_wifsignaled($status) 判断信号终止，再用 pcntl_wtermsig($status) 记录信号编号，不要把它写成普通业务退出码。

为什么非阻塞轮询仍然会占 CPU？

因为 WNOHANG 只让单次等待立即返回，不会自动替循环限速。需要在没有回收结果时安排适当的 usleep() 或其它调度间隔。

所以，PHP 的非阻塞子进程检查可以记成一句话：WNOHANG 负责“不等”，返回 PID 负责“已回收”，status 解析负责“为什么退出”。把这三个层次分开，主循环就能继续工作，同时不把僵尸进程和业务失败混为一谈。