PHP fibers 怎样把阻塞工作包装成可暂停任务

PHP Fiber 适合把一段需要等待外部结果的工作包装成“可暂停、可恢复”的任务：任务在 Fiber 内执行，到达 Fiber::suspend() 后交出控制权，外部调度器拿到暂停信号，再用 resume() 或 throw() 送回结果。需要先划清一个边界：Fiber 只提供协作式暂停机制，不会自动把同步的数据库、文件或网络调用变成非阻塞 I/O。

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

最小可用模型是：start() 启动任务，suspend() 返回等待信息，外部代码准备好结果后调用 resume()；任务结束后再用 getReturn() 读取返回值。

Fiber 的暂停点与调度边界

Fiber 的回调函数可以在调用栈较深的位置暂停。start() 会执行到第一次暂停或直接执行结束；如果回调调用了 Fiber::suspend($value)，这个值会返回给调用 start() 或 resume() 的外部代码。之后传给 resume($value) 的值，又会成为 Fiber 内部那次 suspend() 的返回值。

因此，外部代码应该把 Fiber 当成一个有状态的任务对象，而不是普通函数。调度器至少要保存 Fiber 引用和暂停时携带的资源标识，等结果就绪后再恢复它。

用等待信号包装可暂停任务

下面的例子把“等待用户资料”抽象成一个暂停信号。示例没有执行真实网络请求，resume() 代表外部事件循环、消息队列消费者或 I/O 适配器在结果准备好后回传数据。

 'load-profile',
        'user_id' => 42,
    ]);

    // 外部恢复时把结果作为 suspend() 的返回值送回。
    if (!is_array($reply) || ($reply['ok'] ?? false) !== true) {
        throw new RuntimeException('资料读取失败');
    }

    // 任务正常返回后，调用方可用 getReturn() 取得结果。
    return (string) $reply['name'];
});

// start() 执行到 suspend()，这里拿到等待信号。
$signal = $fiber->start();

// 外部调度器根据信号等待结果，再恢复处于 suspended 状态的 Fiber。
if ($fiber->isSuspended()) {
    $fiber->resume([
        'ok' => true,
        'name' => 'Lin',
    ]);
}

// 只有终止后才能安全读取任务返回值。
$name = $fiber->getReturn();
echo $name;
?>

这个包装的关键不是把阻塞函数藏起来，而是把“等待点”和“恢复数据”变成明确协议。真实项目里，外部调度器可以把 $signal['user_id'] 映射到数据库查询或 HTTP 客户端；查询完成后，再把统一格式的结果交给 resume()。

正常恢复、异常注入和终态读取

恢复前先看状态：resume() 和 throw() 都要求 Fiber 当前处于 suspended 状态；已经结束的 Fiber 不能再次恢复。任务正常返回后，使用 getReturn() 读取回调返回值；尚未结束或因异常退出时调用它，会得到 FiberError。

getMessage();
    }
});

$fiber->start();

if ($fiber->isSuspended()) {
    // throw() 会让异常从 Fiber::suspend() 这一点抛出。
    $fiber->throw(new RuntimeException('上游超时'));
}

// 任务处理完异常后已终止；没有返回值时 getReturn() 返回 null。
if ($fiber->isTerminated()) {
    $result = $fiber->getReturn();
}
?>

如果恢复值代表失败，通常有两种做法：让 Fiber 内部检查结果对象并主动抛出业务异常，或由调度器调用 throw() 把异常送入暂停点。前者适合统一返回协议，后者适合让任务沿原来的 try/catch 结构处理取消、超时和传输错误。

上线前要确认的边界

实际接入时，建议为每个 Fiber 记录任务标识、当前状态、等待资源和超时策略；恢复操作要保持幂等，避免同一结果被重复投递。若项目没有事件循环或异步 I/O 适配器，Fiber 仍然有助于拆分控制流，但不能替代线程、进程或真正的非阻塞库。

相关问题

Fiber 能不能直接并行执行多个任务？

不能把 Fiber 当作 CPU 并行工具。它提供的是同一执行上下文里的协作式切换；是否能在等待 I/O 时推进其他任务，取决于外部调度器能否及时恢复不同 Fiber。

为什么调用 resume() 会报 FiberError？

最常见原因是 Fiber 尚未启动、已经终止，或者当前并不处于 suspended 状态。恢复前检查 isStarted()、isSuspended() 和 isTerminated()，并确保每个 Fiber 只由一个调度者管理。