PHP Fiber 协作式暂停与恢复的状态管理

PHP Fiber 的状态管理关键不在于把它当成线程，而在于明确谁拥有下一次切换的控制权：Fiber::suspend() 把执行权交回 start()、resume() 或 throw() 的调用方；之后调用 resume($value) 时，暂停点会收到这个值，调用 throw($exception) 时，暂停点会像执行到 throw 一样抛出异常。这样，调度器只需要围绕“已启动、已暂停、已结束、异常退出”维护边界。

官方文档：https://www.php.net/manual/en/language.fibers.php

最容易出错的地方是把“暂停时返回给调度器的值”和“恢复时传回 Fiber 的值”混成一个方向。前者来自 suspend()，后者回到暂停点；异常则通过 throw() 进入同一个暂停点。

• 启动一次：start() 只能用于尚未启动的 Fiber。
• 恢复有条件：resume() 和 throw() 应针对当前处于 suspended 状态的 Fiber。
• 结果分两类：正常返回用 getReturn() 读取，未捕获异常则从切换调用处向外传播。

先看 Fiber 的状态，再决定调用哪个方法

一个 Fiber 创建后还没有启动，第一次只能调用 start()。闭包执行到 Fiber::suspend() 后，Fiber 进入 suspended，暂停时传出的值会成为 start() 或后续切换方法的返回值。闭包正常返回后，Fiber 进入 terminated；此时才能读取 getReturn()。

调度器可以把状态判断写成独立分支。不要用“上一次调用成功”猜状态，因为闭包可能在一次恢复后直接结束，也可能在下一次暂停前抛出异常。

用 suspend 和 resume 管理双向值

start();
echo $signal, PHP_EOL;

if ($fiber->isSuspended()) {
    // 只有暂停状态才能安全地把数据送回 Fiber。
    $next = $fiber->resume('继续执行');
}

if ($fiber->isTerminated()) {
    // 闭包已经正常结束后，再读取最终返回值。
    echo $fiber->getReturn(), PHP_EOL;
}

这个例子有两个独立结果：第一次调用得到“等待调度”，第二次调用让暂停点得到“继续执行”，最终返回值则要等 Fiber 终止后从 getReturn() 读取。若闭包在恢复后再次 suspend()，resume() 的返回值仍然是下一次暂停点传出的值，而不是上一次的最终结果。

用 throw 把异常送到暂停点

getMessage(), PHP_EOL;
        return;
    }
});

$fiber->start();
if ($fiber->isSuspended()) {
    // throw() 会让异常从 suspend() 这一行抛出。
    $fiber->throw(new RuntimeException('外部事件失败'));
}

throw() 不是在调度器所在位置直接抛出，而是把异常送进当前的 suspend()。Fiber 内部有 try/catch 时，可以把异常转换成正常结束；如果没有捕获，异常会从调用 throw() 的位置继续向外传播。调用前仍要先确认 Fiber 处于 suspended，否则会得到 FiberError。

调度器的四个边界判断

实际封装时，可以把以下判断作为最小状态机：

另外，Fiber::getCurrent() 只在 Fiber 内部运行时返回当前实例，在外部调度器中得到的是 null。因此不要用它替代外部保存的 Fiber 引用；外部需要的是每个任务的状态、待处理事件和最后结果。

常见问题

resume() 传入的值会返回给谁？

它会作为当前 Fiber::suspend() 调用的返回值，回到 Fiber 内部暂停点之后的代码；调度器调用 resume() 得到的返回值，则来自 Fiber 下一次 suspend() 或正常返回。

throw() 之后为什么调度器仍可能收到异常？

只有 Fiber 内部捕获了该异常，异常才会在 Fiber 内部被转换或结束；如果没有匹配的 catch，异常会从 throw() 调用处继续传播，调度器应在外层统一处理。

什么时候可以调用 getReturn()？

仅在 Fiber 已经终止且是正常返回时读取。暂停中的 Fiber 尚未产生最终返回值；如果 Fiber 因未捕获异常退出，也不应把 getReturn() 当成错误读取接口。