Fiber 怎样安全取得恢复值

PHP Fiber 里最容易混淆的是“恢复时传进去的值”和“Fiber 最终返回的值”。$fiber->resume($value) 会把 $value 交给当前的 Fiber::suspend()，而闭包里的 return 要等 Fiber 终止后，才能用 $fiber->getReturn() 读取。安全的判断顺序是：先用 start() 或 resume() 推进，再确认 isTerminated()，最后读取 getReturn()。

先把 Fiber 的三种值分开

可以把一次 Fiber 运行看成两条通道。第一条是暂停/恢复通道：Fiber 调用 Fiber::suspend('暂停通知')，外部从 start() 或 resume() 收到这个通知；外部再次调用 resume('继续参数') 后，suspend() 在 Fiber 内部返回“继续参数”。第二条是最终结果通道：闭包自然执行到 return '最终结果' 后，Fiber 进入终止状态，外部再通过 getReturn() 取回这个结果。

所以，下面三个表达式的含义不同：

resume 的参数会回到当前 suspend

如果 Fiber 在内部暂停，外部的 resume($value) 参数就会成为这次 Fiber::suspend() 调用的返回值。这个返回值可以继续参与校验、分支或下一次计算；它不会自动变成 Fiber 的最终返回值。

start();
echo $notice, PHP_EOL; // 输出：等待确认

$next = $fiber->resume(true);
echo var_export($next, true), PHP_EOL; // Fiber 终止时输出 NULL

// resume() 没有返回“已完成”，最终结果要在终止后单独读取。
echo $fiber->getReturn(), PHP_EOL; // 输出：已完成

这里的 $next 是“下一次暂停值”，而不是 return '已完成'。因为闭包没有第二个 suspend()，resume(true) 会把 Fiber 直接推进到终止，调用结果为 null；之后 getReturn() 才能读到字符串。

最终返回值要等 Fiber 终止后读取

getReturn() 对应的是构造 Fiber 时传入的回调最终返回值。它不是“当前暂停值的快捷别名”，也不会替调用方自动推进 Fiber。若 Fiber 还处于暂停状态，直接读取最终值没有意义，PHP 会抛出 FiberError。

start();
echo $stage, PHP_EOL; // 输出：第一阶段完成

if ($fiber->isSuspended()) {
    // 继续推进，resume() 的返回值仍代表下一次暂停或终止信号。
    $finished = $fiber->resume();
    echo var_export($finished, true), PHP_EOL; // 输出：NULL
}

if ($fiber->isTerminated()) {
    // 状态确认后再读取回调的最终 return。
    echo $fiber->getReturn(), PHP_EOL; // 输出：42
}

如果把 getReturn() 放在第一次 start() 后面，Fiber 仍停在 suspend()，读取会落入错误边界。把“推进”和“读取最终值”拆成两个动作，调用方就不会把阶段性值误当成最终结果。

用状态判断保护 getReturn

Fiber 的状态方法适合做读取前的门槛：isStarted() 判断是否已经启动，isSuspended() 判断当前是否可以用 resume() 继续，isTerminated() 判断最终结果是否已经存在。实际封装时，通常只把终止状态映射为“可读取”，其它状态返回明确的业务分支。

isTerminated()) {
        throw new LogicException('Fiber 尚未终止，不能读取最终结果');
    }

    try {
        // 终止状态下读取回调的最终返回值。
        return $fiber->getReturn();
    } catch (FiberError $e) {
        // 保留 FiberError 的原始信息，便于区分状态误用和业务异常。
        throw new RuntimeException('Fiber 最终值不可用', 0, $e);
    }
}

这个封装仍然不能替你处理 Fiber 回调内部抛出的业务异常。若回调在返回前抛出异常，Fiber 不会产生可用的最终 return；调用 start()、resume() 或 throw() 的位置应负责捕获原异常，不能把异常结束当成普通结果读取。

重复推进和异常注入要单独处理

resume() 只适用于已经启动且当前处于暂停状态的 Fiber。对未启动、正在运行或已经终止的 Fiber 调用它，都会越过方法的状态边界。需要把异常送入暂停点时，使用 Fiber::throw()，不要把异常对象当成普通恢复值传给 resume()。

getMessage();
    }
});

$fiber->start();
$fiber->throw(new InvalidArgumentException('数据格式不正确'));

// throw() 让回调走到 return，终止后再读取最终值。
echo $fiber->getReturn(), PHP_EOL;

如果只是要传递“继续”“取消”“确认”等数据，使用 resume($value)；如果要改变控制流并让 Fiber 在暂停点进入异常处理，才使用 throw($exception)。两条路径的返回值读取规则仍然相同：最终结果以终止后的 getReturn() 为准。

写 Fiber 调用代码时的判断清单

• 外部拿到的是暂停通知，还是闭包最终 return？先确认数据来源。
• resume($value) 的参数是否确实对应当前一次 Fiber::suspend()？
• 调用 getReturn() 前是否已经确认 isTerminated()？
• Fiber 结束前是否可能抛出异常？异常是否在推进调用点被单独处理？
• 是否可能重复调用 resume()？如果可能，先检查 isSuspended()。

常见问题

resume() 能直接拿到 Fiber 闭包的 return 吗？

不能把它当成最终结果接口。resume() 返回下一个 suspend() 的值，若本次推进直接终止则返回 null；闭包的最终 return 用 getReturn() 读取。

Fiber 没有调用 suspend()，怎样取得 return？

直接调用 start() 让回调执行；当 Fiber 已终止后调用 getReturn()。start() 本身在终止时返回 null，不代表回调的 return 也是 null。

getReturn() 抛出 FiberError 怎么办？

先检查 Fiber 是否仍未启动、处于暂停状态或因异常结束。只有正常终止且存在可读取的回调结果时，getReturn() 才是合适的读取动作。