PHP Fiber设计 suspend 与 resume 的值传递的实现方法

PHP Fiber 最容易混淆的不是“怎么暂停”，而是一次调用里有三种不同的值：suspend() 交给外部的值、resume() 送回暂停点的值，以及 Fiber 结束后 getReturn() 读取的最终结果。把这三段协议分开，生命周期就不会乱。

官方地址：https://www.php.net/manual/en/language.fibers.php

先把 Fiber 的三段值协议拆开

排查 Fiber 时，可以先把调用方向画成两条线。Fiber 执行到 Fiber::suspend('need-input')，外部的 start() 会拿到 need-input；外部随后调用 resume('approved')，Fiber 内部暂停的那一行会得到 approved。如果闭包最后执行 return 'done'，这个结果要等 Fiber 终止后通过 getReturn() 取出。

用两次 suspend 观察恢复点到底收到什么

下面的示例故意设置两个暂停点。第一个 start() 只负责让 Fiber 运行到第一处暂停；第一个 resume() 的参数回到第一处 suspend()；第二处暂停则把新的中间值交给下一次 resume()。代码中的注释只标出值的方向，避免把中间结果和最终结果混在一起。

 继续计算”的值协议。
$fiber = new Fiber(function (): string {
    // start() 会拿到这里交出的 need-user 值。
    $user = Fiber::suspend('need-user');

    // resume() 的参数成为上一行 suspend() 的返回值。
    $token = Fiber::suspend('need-token:' . $user);

    // return 是终止结果，只能在 Fiber 结束后用 getReturn() 读取。
    return 'authorized:' . $token;
});

$first = $fiber->start();
echo $first, PHP_EOL; // need-user

// 只有暂停状态才能 resume；这里的返回值是下一次 suspend() 的值。
$second = $fiber->resume('alice');
echo $second, PHP_EOL; // need-token:alice

// 继续执行到 return，Fiber 终止；此处返回 null 很正常。
$fiber->resume('token-7');

// 终止后才能取得闭包的最终 return 值。
echo $fiber->getReturn(), PHP_EOL; // authorized:token-7
?>

这里的关键观察是：第二次 resume() 没有返回 authorized:token-7，因为它只是把 Fiber 推到终点；最终结果属于 getReturn()。如果把业务结果误读成 resume() 的返回值，调度器就会提前结束或把 null 当成业务失败。

状态检查决定调用是否有效

resume() 只接受 suspended 状态。Fiber 尚未启动时要调用 start()，正在运行时不能从外部再次切入，已经终止后也不能继续 resume()。因此调用方最好把状态和动作放在同一处处理，而不是在多个回调里凭经验调用。

如果外部输入代表失败，而不是正常恢复值，可以用 throw() 把异常送入暂停点；Fiber 内部是否捕获它由业务决定。若异常没有被处理，Fiber 不会产生可读取的正常返回值，调用方应在异常边界记录失败，而不是继续调用 getReturn()。

把值协议写进调度器的检查清单

• 为每个暂停点命名协议：外部看到什么值、恢复时需要什么值。
• 把 start() 的首个输入和 resume() 的恢复输入分开记录，避免同名变量掩盖方向。
• 用 isSuspended() 判断是否允许恢复，用 isTerminated() 判断是否允许读取最终结果。
• 让正常结果走 return/getReturn()，让取消或失败走 throw() 和异常处理。

Fiber 只提供可中断的执行栈，不替你定义事件循环、超时策略或资源清理。设计时先固定值的方向，再把调度器接入外部 IO，问题会比“先写一个万能协程包装器”少很多。

相关问题

resume() 为什么有时返回 null？

当这次恢复直接让 Fiber 执行到 return 或异常结束时，没有下一处 suspend 可交出值，resume() 返回 null 并不等于业务结果为空。

getReturn() 能不能在 suspend 状态读取？

不能。Fiber 尚未终止、尚未启动或异常终止时，getReturn() 都不应被当作中间结果读取入口。

Fiber::suspend() 能否在 Fiber 外调用？

不能。它依赖当前 Fiber；在 Fiber 外调用会抛出 FiberError。