罗罗编程学习记录
本页内容 展开查看

06.5.7.3 Coroutine 核心 API

所属:全栈开发面试题库 / 06 后端框架与工程实践 / 06.5 PHP 后端 / 06.5.7 Swow

06.5.7.3-001 Swow\Coroutine 类的定位是什么?

一句话结论

Swow\Coroutine 是 Swow 对协程的面向对象抽象:每个协程是一个持有执行上下文、状态与观测信息的对象,负责协程体执行、让出、唤醒、状态查询与调试回溯。

概念解释

协程是可主动挂起的子例程:运行中遇到 IO 等待或主动让出时保存上下文,调度器切换到其他协程;条件满足后再恢复执行。Coroutine 类把这套能力封装为静态工厂方法与实例方法,协程间通过对象引用或 ID 互操作。类位于 Swow\ 命名空间,由扩展与库层共同提供。

原理流程

  1. 调用 Coroutine::run() 或 new Coroutine() 创建协程实体。
  2. 协程体在独立栈上下文中执行,局部变量与执行帧归该协程私有。
  3. 让出时保存栈帧,恢复时读取栈帧继续执行。
  4. 协程退出后进入 dead 状态,对象可用于观测但不可再唤醒。

代码或图示

<?php
// 文档示例(未实测):Coroutine 类的基本使用形态
use Swow\Coroutine;

$co = Coroutine::run(static function (): void {
    echo "coroutine body";
});
echo $co->getId();

常见误区

  • 以为 Coroutine 是纯 PHP 用户态协程:调度与栈切换由扩展底层完成,类只是门面。
  • 以为协程对象销毁等于协程退出:对象引用与协程生命周期需要分开理解。

追问

  • 协程与线程的区别?答:协程在单线程内协作调度,不绑定 OS 线程;切换由运行时控制,开销低于线程。
  • 如何确认类已注册?答:php -r "var_dump(class_exists('Swow\\Coroutine'));";本机未安装扩展时返回 false(待确认环境实测)。

06.5.7.3-002 如何用 run() 创建并立即运行协程?

一句话结论

Coroutine::run(callable $callable, mixed ...$data) 静态方法创建协程并立即调度执行,可变参数透传给协程体,返回新建协程对象;创建与首次切换在该调用点发生。

概念解释

run() 是最常用的协程入口:一步完成构造与唤醒。传入的 callable 可以是闭包、函数名或数组回调;...$data 按位置作为协程体参数。返回值是新协程对象,可用于后续观测、唤醒或注入异常。调用 run() 的当前协程会在调度点让出,由调度器决定先跑新协程还是继续当前协程。

原理流程

  1. 准备协程体 callable 与参数。
  2. 调用 Coroutine::run($callable, ...$args)。
  3. 扩展分配协程上下文,进入调度切换。
  4. 返回新协程对象引用,供后续状态查询使用。

代码或图示

<?php
// 文档示例:run 传参与返回对象
use Swow\Coroutine;

$co = Coroutine::run(static function (int $a, string $b): void {
    echo $a, $b;
}, 1, "ok");

echo $co->getId();

常见误区

  • 以为 run() 会阻塞等待协程结束:它只启动协程,不等待其完成;等待需用 Sync 或 Channel。
  • 闭包 use 与 ...$data 混用导致参数错乱:优先选一种传参方式并保持一致。

追问

  • 协程体签名必须无返回值吗?答:协程体可以有返回语句,但返回值不自动作为 run() 的返回值;取值方式见 06.5.7.3-010。
  • run() 返回的对象一定存活吗?答:返回时协程已创建并进入调度,是否已退出需用状态方法判断。

06.5.7.3-003 new Coroutine 与 Coroutine::run() 有什么区别?

一句话结论

new Coroutine(callable) 只构造协程对象、申请上下文,处于 waiting 待唤醒状态;Coroutine::run() 等价于构造后立即 resume()。延迟构造的对象可提前占用资源,再在合适时机唤醒。

概念解释

Swow 设计上统一唤醒路径:刚创建未运行的协程与运行中挂起的协程在抽象上都是 waiting,都通过 resume() 唤醒,因此不单独提供 start() 方法。先构造后唤醒的模式可用于预分配协程资源(协程池思路),避免运行期内存紧张时创建失败;常规业务直接用 run() 即可。

原理流程

  1. new Coroutine($callable):分配结构体与栈,协程进入 waiting。
  2. 持有对象引用,必要时做预检或登记。
  3. 调用 $co->resume() 唤醒执行。
  4. 协程体返回后进入 dead,对象不再可唤醒。

代码或图示

<?php
// 文档示例:延迟构造与唤醒
use Swow\Coroutine;

$pending = new Coroutine(static function (): void {
    echo "started later";
});
// 此时状态为 waiting,尚未执行协程体
$pending->resume();

常见误区

  • 构造后等待自动运行:不调 resume() 协程体不会执行。
  • 对 dead 协程再次 resume():退出后的协程不可复用。

追问

  • 预分配协程池有什么收益?答:提前占用栈与结构体内存,避免高峰期创建失败;是否需要取决于并发规模与内存预算。
  • 构造失败如何表现?答:构造阶段异常由扩展抛出;具体异常类型以文档为准(待确认)。

06.5.7.3-004 如何获取当前协程与协程 ID?

一句话结论

Coroutine::getCurrent() 返回当前协程对象,Coroutine::getMain() 返回主协程对象;实例方法 getId() 取数字协程 ID。只有在当前协程上观测自己才能得到 running 状态。

概念解释

单线程内同一时刻只有一个协程在运行,观测其他协程时它们必然处于 waiting 或 dead。getCurrent() 在协程上下文内调用返回自身;在主协程上下文返回主协程对象。ID 是数字标识,可用于日志关联与 Coroutine::get($id) 反查对象。跨协程观测时状态不会是 running。

原理流程

  1. 协程体内调用 Coroutine::getCurrent() 取得自身对象。
  2. 通过 getId() 读取数字 ID,写入日志或上下文标识。
  3. 需要主协程引用时调用 Coroutine::getMain()。
  4. 持有 ID 后可用 Coroutine::get($id) 反查对象(可能已不存在,返回 null)。

代码或图示

<?php
// 文档示例:当前协程标识采集
use Swow\Coroutine;

Coroutine::run(static function (): void {
    $current = Coroutine::getCurrent();
    echo "cid=", $current->getId(), PHP_EOL;
});

常见误区

  • 在 A 协程里读 B 协程状态期望看到 running:被观测协程不在运行态。
  • 把 ID 当长期句柄:协程退出后反查返回 null,需先做可用性判断。

追问

  • 主协程是什么?答:最外层协程,进程脚本主体运行在主协程中;主协程退出会带动进程退出。
  • 如何遍历全部存活协程?答:Coroutine::getAll() 返回 ID 到对象的映射数组。

06.5.7.3-005 yield() 的语义与数据传递方式是什么?

一句话结论

Coroutine::yield(mixed $data): mixed 让当前协程主动挂起,$data 作为让出值传给唤醒方;唤醒方 resume(...$data) 传入的数据则作为 yield() 的返回值回到当前协程。

概念解释

yield 是协程级的显式让出:保存当前栈帧,切回调度器或唤醒方。数据双向流动:协程 yield 出去的值由 resume 调用方接收;resume 时带入的值成为 yield 表达式结果。协程体 return $value 在语义上等价于 yield($value) 后退出,因此不再单独设计 getReturn() 实例方法。

原理流程

  1. 当前协程执行到 Coroutine::yield($data)。
  2. 协程挂起,$data 交给唤醒它的 resume 调用方。
  3. 调度器切到其他协程;后续 resume(...$args) 恢复本协程。
  4. yield() 调用以 $args 为返回值,协程继续执行后续语句。

代码或图示

<?php
// 文档示例:yield/resume 双向传值(数值为文档示意,未实测)
use Swow\Coroutine;

$co = new Coroutine(static function (int $a, int $b): int {
    $sum = $a + $b;
    $multiplier = Coroutine::yield($sum);
    return $sum * $multiplier;
});
$sum = $co->resume(1, 1);
$result = $co->resume(2);

常见误区

  • 在业务代码里滥用 yield/resume 做通信:CSP 模型下协程间传值应优先用 Channel,裸调度 API 心智负担高。
  • 以为 yield 后协程结束:yield 只是挂起,resume 后继续执行。

追问

  • 为什么不提供 getReturn()?答:返回值被设计为 yield 一个值并退出的组合操作,统一数据传递路径;需要取返回值可在应用层封装。
  • yield 可以在主协程调用吗?答:主协程同样可让出;具体边界行为待确认,以官方文档为准。

06.5.7.3-006 resume() 的语义与参数传递规则是什么?

一句话结论

resume(mixed ...$data): mixed 唤醒目标 waiting 协程,可变参数作为该协程上次 yield() 的返回值;resume 调用点发生上下文切换,其返回值是目标协程下一次 yield 或退出时交出的值。

概念解释

resume 是统一唤醒入口:无论是新建待运行协程还是 IO 挂起协程,都通过它恢复。参数流向被唤醒协程的 yield 表达式;返回值流向 resume 调用方,对应被唤醒协程下一次让出或退出交出的数据。对已 dead 的协程调用 resume 属于无效操作,底层有防护。

原理流程

  1. 持有目标协程对象,确认其可用且未退出。
  2. 调用 $co->resume(...$args),当前协程让出执行权。
  3. 目标协程从挂起点恢复,yield() 表达式得到 $args。
  4. 目标协程再次 yield 或退出时,控制权与交出值回到 resume 调用方。

代码或图示

<?php
// 文档示例:分步 resume 驱动协程
use Swow\Coroutine;

$co = new Coroutine(static function (): string {
    $input = Coroutine::yield("first");
    return "got:" . $input;
});
$first = $co->resume();
$final = $co->resume("payload");

常见误区

  • 对同一协程并发 resume:唤醒路径需要由调度规则保证,重复唤醒行为待确认,业务上不应这样使用。
  • 忽略 resume 返回值类型:返回的是被唤醒协程交出的值,不是协程体最终业务结果的通用通道。

追问

  • 新建协程首次 resume 传参给谁?答:首次唤醒时参数传入协程体 callable,而非 yield 表达式;与后续 resume 语义不同。
  • resume 内部会切走当前协程吗?答:文档标注成功时发生上下文切换;具体调度顺序以实现为准。

06.5.7.3-007 协程有哪几个状态?如何查询?

一句话结论

Swow 协程只有 waiting、running、dead 三个基本状态,常量为 STATE_WAITING、STATE_RUNNING、STATE_DEAD(另有 STATE_NONE);getState() 返回状态枚举值,getStateName() 返回状态名。

概念解释

waiting 覆盖两种情况:刚构造尚未运行,或运行中等待 IO/事件唤醒;抽象上两者都是“等待被唤醒”,因此不单独设 init 状态。running 表示正在执行;dead 表示协程体已返回且析构完成。状态由调度器在切换点维护,观测时以对象方法读取为准。

原理流程

  1. 构造完成:waiting。
  2. resume 后进入 running,执行协程体。
  3. IO 等待或 yield:回到 waiting。
  4. 协程体返回/终止:进入 dead,析构完成后不可再操作。

代码或图示

<?php
// 文档示例:状态读取
use Swow\Coroutine;

$co = Coroutine::run(static function (): void {
    echo Coroutine::getCurrent()->getStateName();
});
echo $co->getState(), $co->getStateName();

常见误区

  • 寻找 init/suspended 等额外状态:Swow 基本状态只有三个,细分判断用复合检查方法。
  • 以为 waiting 一定是在等 IO:也可能是尚未首次运行。

追问

  • 状态常量值是多少?答:STATE_NONE=0、STATE_WAITING=1、STATE_RUNNING=2、STATE_DEAD=3(以当前 API 文档为准)。
  • 状态变化时机?答:在调度切换与退出节点更新;业务代码不应假设两次读取之间状态不变。

06.5.7.3-008 isAvailable()、isAlive()、isExecuting() 复合检查有什么区别?

一句话结论

isAvailable() 判断协程是否构造完成且未退出、可被操作;isAlive() 判断是否已开始运行且尚未退出;isExecuting() 判断是否正在执行。三者基于基本状态与起止时间复合得出,用于区分“没开始”“活着等待”“正在跑”。

概念解释

可用性:构造成功后到退出前都可用,未构造完成或已退出不可用。存活:首次运行后到退出前为存活,未开始或已结束都不算存活。执行中:仅当前正在运行的协程为 true。复合检查不引入新状态实体,而是在三状态基础上结合开始/结束时间计算,保持状态模型最简。

原理流程

  1. 操作协程对象前先 isAvailable(),避免访问未构造或已退出对象。
  2. 判断任务是否在跑用 isAlive(),区分未启动与运行中等待。
  3. 判断自身是否执行中用 isExecuting()。
  4. 组合三个方法覆盖排障中的状态判断场景。

代码或图示

<?php
// 文档示例:复合检查分支
use Swow\Coroutine;

$co = new Coroutine(static function (): void {
});
var_dump($co->isAvailable(), $co->isAlive());
$co->resume();
var_dump($co->isAlive(), $co->getStateName());

常见误区

  • 用 isAlive() 判断对象能否操作:未启动协程 alive 为 false 但 available 为 true。
  • 跨协程读到 isExecuting 为 true:只有观测者自身才可能处于执行中。

追问

  • 未构造完成的协程如何产生?答:继承重写构造函数跳过父类构造的特殊场景;底层有防护,常规业务不会遇到。
  • 这些方法在 dead 对象上返回什么?答:available 与 alive 均为 false;具体返回以实现为准(待确认)。

06.5.7.3-009 协程内抛出未捕获异常会怎样?

一句话结论

未捕获异常中断当前协程执行,协程进入退出流程;异常不会自动冒泡到父协程,其他协程继续运行。必须在协程体顶层兜底捕获,记录日志并回收资源,否则异常信息可能丢失。

概念解释

协程异常传播范围限于协程自身执行栈:未被 catch 的 Throwable 导致协体终止,状态走向 dead。框架层通常注册全局协程异常处理器记录日志;裸用运行时时需要在每个入口闭包内 try/catch。异常路径上连接、缓冲、文件句柄等资源必须通过 finally/defer 回收。

原理流程

  1. 协程体内 IO 或业务代码抛出 Throwable。
  2. 沿协程栈向上查找 catch,未找到则协程终止。
  3. 调度器继续运行其他就绪协程,不连带终止进程(除非框架/进程策略规定退出)。
  4. 兜底 catch 记录协程 ID、消息与调用栈,执行资源清理。

代码或图示

<?php
// 文档示例:协程入口异常兜底与清理
use Swow\Coroutine;

Coroutine::run(static function (): void {
    try {
        // IO 与业务调用
    } catch (\Throwable $e) {
        echo "cid=", Coroutine::getCurrent()->getId(), ": ", $e->getMessage(), PHP_EOL;
    } finally {
        // 归还连接、释放缓冲等清理动作
    }
});

常见误区

  • 以为父协程 catch 能接住子协程异常:协程异常不自动向上冒泡。
  • 异常分支跳过资源归还:连接与句柄泄漏会在并发下逐步放大。

追问

  • 能否向指定协程注入异常?答:Coroutine::throw(Throwable) 可向目标协程抛出异常;用途与边界见 06.5.7.3-017。
  • 异常处理专题在哪一批?答:06.5.7.10 错误处理与异常传播(规划中)。

06.5.7.3-010 协程体 return 的值如何被外部取得?

一句话结论

Swow 不提供通用的 getReturn() 实例方法:协程体 return $value 语义上等价于 yield($value) 后退出;需要取返回值时,通过 resume 收回让出值,或在应用层封装协程子类把返回值存入属性。

概念解释

按 CSP 设计哲学,协程间数据传递应走 Channel,而不是为协程返回值设计专用 API;线程模型中线程函数返回值表示退出状态而非数据。run() 返回的是协程对象,不是协程体返回值。确需取回结果时,可在闭包内调用业务 callable,把结果写入对象属性或通过 Channel 发送给汇总协程。

原理流程

  1. 方案一:Channel 传值——业务协程把结果 push 到通道,汇总协程 pop。
  2. 方案二:封装子类——构造时包裹 callable,把返回值存入公开属性。
  3. 方案三:裸调度——resume() 收回协程退出时交出的值。
  4. 多数业务场景优先方案一,符合 CSP 模型。

代码或图示

<?php
// 文档示例:应用层封装返回值属性
use Swow\Coroutine;

$co = new class (static function (): string {
    return "Hello Swow";
}) extends Coroutine {
    public mixed $returnValue = null;

    public function __construct(callable $callable)
    {
        parent::__construct(function () use ($callable): void {
            $this->returnValue = $callable();
        });
    }
};
$co->resume();
var_dump($co->returnValue);

常见误区

  • 把 Coroutine::run() 返回值当业务结果:返回的是协程对象。
  • 为取返回值绕开 Channel:在多协程汇总场景下,Channel 收集结果更清晰。

追问

  • 为什么官方不提供 getReturn?答:设计上引导协程间通过 Channel 通信,避免把数据传递耦合到调度 API。
  • 结果汇总怎么做?答:WaitGroup 等全部完成,Channel/数组收集各协程结果;注意共享数组的写入顺序与同步。

06.5.7.3-011 协程嵌套与父协程退出顺序有什么规则?

一句话结论

协程可以在协程体内再派生新协程,嵌套协程与父协程在同一调度器内并发运行;父协程先退出不会自动等待子协程,但若主协程退出,整个进程随之退出,未完成的子协程被终止。

概念解释

Coroutine::run() 在任意协程上下文内都可调用,新协程与调用方是并发关系,不是“函数调用返回值”关系。父协程退出后子协程是否继续,取决于是否仍有存活的主协程/事件循环维持进程。需要明确等待子任务时,显式使用 WaitGroup、WaitReference 或 Channel,不能依赖父子隐式 join。

原理流程

  1. 父协程执行中调用 run() 派生子协程。
  2. 父子协程由调度器交替调度,互不阻塞返回。
  3. 父协程先结束:子协程继续存活直到自身结束或进程退出。
  4. 需要汇聚时,在派生前登记同步设施,父/汇总协程 wait 到完成。

代码或图示

<?php
// 文档示例:派生协程并显式等待
use Swow\Coroutine;
use Swow\Sync\WaitGroup;

$wg = new WaitGroup();
$wg->add(1);
Coroutine::run(static function () use ($wg): void {
    Coroutine::run(static function () use ($wg): void {
        // 嵌套子协程任务
        $wg->done();
    });
});
$wg->wait(5000);

常见误区

  • 以为父协程退出会 join 子协程:没有隐式父子等待关系。
  • 在父协程局部变量上保存子协程结果:子协程异步执行,父协程继续往下走时结果尚未产生。

追问

  • 如何获取当前协程的前驱协程?答:getPrevious() 返回上一个协程对象;语义以 API 文档为准。
  • 嵌套层数有限制吗?答:栈深度受协程栈容量约束;过深调用链需实测,具体上限待确认。

06.5.7.3-012 主协程退出对子协程有什么影响?

一句话结论

Swow 采用类似 Go 的模型:主协程退出后所有协程一同退出,进程结束;因此脚本或服务必须在主协程路径上等待任务完成,或由常驻服务循环维持进程存活。

概念解释

主协程是最外层协程,脚本主体运行在其中。如果主协程跑完脚本末尾就返回,即便子协程还在 IO 等待,进程也会退出。常驻服务由 Server/Selector 循环或等待设施维持;命令行脚本可用 waitAll()、WaitGroup 或 Channel 等待任务收敛。这是与 FPM 请求模型的重要区别。

原理流程

  1. 主协程启动业务协程后继续执行后续语句。
  2. 若主协程先返回,运行时判定无存活主流程,结束进程。
  3. 子协程被一并终止,未完成的 IO 结果丢失。
  4. 正确做法:主协程内 wait 到任务完成,或进入常驻事件循环。

代码或图示

<?php
// 文档示例:主协程等待子任务收敛后再退出
use Swow\Coroutine;
use function Swow\Sync\waitAll;

Coroutine::run(static function (): void {
    echo "worker started";
});
waitAll(); // 主协程在此等待,避免进程提前结束

常见误区

  • 启动协程后主脚本直接结束:子协程来不及执行就被终止。
  • 把 waitAll 当业务级同步设施:它粒度粗,适合脚本收尾,核心链路优先 WaitGroup/Channel。

追问

  • 常驻服务如何维持主协程?答:监听循环或事件等待持续阻塞在主协程;具体骨架见 Server 主题批次。
  • 主协程异常退出怎么办?答:兜底异常处理器记录日志,必要时通过外部 supervisor 重启进程。

06.5.7.3-013 如何按 ID 获取协程、遍历全部存活协程?

一句话结论

Coroutine::get(int $id): ?static 按数字 ID 反查协程对象,不存在时返回 null;Coroutine::getAll(): array<int, Coroutine> 返回全部已开始运行且未死亡的协程映射;Coroutine::count() 返回协程数量。

概念解释

这些方法是观测与排障入口:日志记录了 CID 后可反查对象状态与调用栈;getAll() 用于观测器协程周期性打印挂起协程清单。反查结果可能为 null(协程已退出),使用前需判断。遍历得到的是快照,调度并发下状态会持续变化。

原理流程

  1. 日志或监控记录协程 ID。
  2. 调用 Coroutine::get($id) 取得对象,判空后读状态与栈。
  3. 无特定目标时 Coroutine::getAll() 遍历存活协程。
  4. Coroutine::count() 辅助判断协程规模是否异常膨胀。

代码或图示

<?php
// 文档示例:存活协程观测器骨架
use Swow\Coroutine;

Coroutine::run(static function (): void {
    while (true) {
        foreach (Coroutine::getAll() as $id => $co) {
            echo $id, $co->getStateName(), PHP_EOL;
        }
        sleep(1);
    }
});

常见误区

  • 反查不判空:已退出协程返回 null,直接调方法会报错。
  • 把 getAll 快照当实时状态:遍历过程中协程状态可能已变化。

追问

  • 观测器本身占用资源吗?答:周期性遍历有轻微开销,生产环境按需开启,避免高频打印。
  • 有没有调试器组件?答:Swow 提供 SDB 调试能力用于动态调试;细节归调试观测批次(06.5.7.13)。

06.5.7.3-014 kill() 与 killAll() 的用途与风险是什么?

一句话结论

kill() 终止目标协程,killAll() 终止全部协程;二者用于异常兜底与进程退出前的强制清理,但会跳过正常业务收尾,可能导致资源不归还、数据不完整,业务流程中应谨慎使用。

概念解释

正常退出路径是协程体返回或异常被 catch 后走 finally/defer 清理。kill 属于强制终止:协程在挂起或运行中被打断,未执行的清理语句不会执行。killAll() 常用于死锁兜底或进程关闭阶段;注册死锁处理器可在全部协程卡住时触发回调介入。

原理流程

  1. 识别需要终止的协程:超时未完成、失控循环、关闭流程。
  2. 优先走正常取消路径:通知协程退出循环、归还资源。
  3. 兜底场景调用 kill() 或 killAll() 强制结束。
  4. 强制终止后检查资源句柄与外部副作用是否一致。

代码或图示

<?php
// 文档示例:受控终止目标协程(风险动作,生产需谨慎)
use Swow\Coroutine;

$co = Coroutine::run(static function (): void {
    while (true) {
        sleep(1);
    }
});
// 超时判定后:$co->kill();

常见误区

  • 用 kill 代替业务取消逻辑:被 kill 的协程不执行 finally 之外的收尾,连接可能泄漏。
  • 在请求协程里 killAll:会误杀其他并发请求协程。

追问

  • 死锁处理器如何注册?答:Coroutine::registerDeadlockHandler(callable) 注册回调,返回处理器句柄;触发条件与回调语义以文档为准(待确认)。
  • 协程退出状态如何读取?答:getExitStatus() 返回退出状态码;具体取值规则待确认。

06.5.7.3-015 协程的退出状态与耗时统计如何读取?

一句话结论

实例方法提供 getExitStatus()(退出状态)、getStartTime()/getEndTime()(起止时间戳)、getElapsed()/getElapsedAsString()(耗时)、getSwitches()(切换次数)等观测字段,可用于排查慢协程与调度次数异常。

概念解释

观测信息在协程结构体上维护:开始/结束时间、累计切换次数、执行耗时。var_dump 协程对象时 debugInfo 会展示 id、state、switches、elapsed 等字段。这些指标用于识别长时间挂起、频繁切换与异常存活的协程;时间单位与返回类型以 API 文档为准,不凭印象写死。

原理流程

  1. 持有协程对象,记录启动时点。
  2. 协程运行与切换过程中累计 switches 与耗时。
  3. 退出后读取 exitStatus、endTime 与 elapsed。
  4. 汇总到监控或日志,对比正常基线发现长尾协程。

代码或图示

<?php
// 文档示例:协程观测字段读取
use Swow\Coroutine;

$co = Coroutine::run(static function (): void {
    sleep(1);
});
// 退出后读取统计信息
echo $co->getElapsedAsString(), $co->getSwitches();

常见误区

  • 在协程刚启动时读耗时:此时统计尚未完成,数值无参考意义。
  • 把 switches 当业务指标:切换次数反映调度交互,需结合场景解读。

追问

  • 全局切换次数怎么看?答:Coroutine::getGlobalSwitches() 返回全局切换计数。
  • 时间单位是什么?答:elapsed 整数单位与字符串格式以文档为准(待确认),避免在文档中写死毫秒/微秒。

06.5.7.3-016 协程内注册的 defer 任务何时执行?

一句话结论

Swow\defer(callable) 注册的任务在当前函数帧结束时运行(return 或抛异常都会触发),多个 defer 按注册逆序执行;主作用域中的 defer 在请求关闭阶段执行。

概念解释

defer 是退出清理设施,类似其他语言的 defer/析构钩子:注册时不执行,帧结束时统一跑。逆序执行保证后注册的先清理,符合栈式资源释放。协程异常退出时已注册的 defer 同样会执行,因此适合归还连接、关闭句柄等收尾动作。defer 与 finally 的分工:finally 针对单个 try 块,defer 跟随函数帧。

原理流程

  1. 在函数/协程体内调用 defer(function () { ... }) 登记清理任务。
  2. 业务代码正常返回或抛出异常,函数帧结束。
  3. 按注册逆序依次执行 defer 任务。
  4. 清理完成后帧销毁,协程继续退出流程。

代码或图示

<?php
// 文档示例:defer 逆序清理
use function Swow\defer;

function process(): void
{
    defer(static function (): void {
        echo "cleanup second";
    });
    defer(static function (): void {
        echo "cleanup first";
    });
    // 业务逻辑,返回或异常都会触发 defer
}

常见误区

  • 以为 defer 在协程退出时才执行:它跟随当前函数帧,不是跟随整个协程生命周期。
  • defer 内再做阻塞等待:清理阶段应轻量快速,避免阻塞退出流程。

追问

  • Swow\Defer 类与 defer() 函数关系?答:命名空间下存在 Swow\Defer 类;函数式注册是常见入口,类用法对照 API 文档(待确认)。
  • defer 中抛异常会怎样?答:异常在清理阶段的传播规则待确认;关键清理动作应在内部自行 catch 记录。

06.5.7.3-017 如何在目标协程内注入或抛出异常?

一句话结论

Coroutine::throw(Throwable $throwable) 向目标协程注入异常,方法返回值为调度恢复后交出的数据;用于调试中断、超时取消或测试场景,误用会打断其他协程正常流程。

概念解释

与主动 kill 不同,throw 让目标协程在其执行栈内收到一个 Throwable,可被目标协程的 catch 捕获处理;目标处于挂起状态时,注入异常会唤醒并在挂起点抛出。调用前需确认目标协程可用、存活,避免对 dead 对象操作。异常类型选择应与目标代码的 catch 分支匹配。

原理流程

  1. 持有目标协程对象并确认 isAlive()。
  2. 构造需要抛出的 Throwable(含消息与错误码)。
  3. 调用 $co->throw($exception),调度切到目标协程。
  4. 目标协程在挂起点/运行点进入对应 catch 分支处理。

代码或图示

<?php
// 文档示例:向挂起协程注入取消异常(骨架,未实测)
use Swow\Coroutine;

$co = Coroutine::run(static function (): void {
    try {
        // 等待 IO 或同步信号
    } catch (\RuntimeException $e) {
        echo "cancelled: ", $e->getMessage();
    }
});
$co->throw(new \RuntimeException("cancel"));

常见误区

  • 对未持有引用的协程盲目 throw:不知道目标在做什么,可能中断正常请求。
  • 注入异常后不观察目标处理结果:需配合日志或状态确认 catch 已执行。

追问

  • throw 与 kill 的区别?答:throw 走目标异常栈可被捕获;kill 强制终止,不保证收尾。
  • 注入异常的错误码如何对齐?答:使用 Swow\Errno 常量或业务自定义异常,保证 catch 分支可识别。

06.5.7.3-018 协程局部变量与作用域信息如何观测?

一句话结论

Coroutine 提供 getDefinedVars(int $level) 读取指定作用域已定义变量,setLocalVar() 在指定作用域设置变量,配合 getTrace() 系列方法定位执行帧;这类能力主要用于调试、框架反射与工具开发,业务代码一般不直接使用。

概念解释

协程对象保存了执行栈帧,调试能力沿帧层级回溯:getTrace($level, $limit, $options) 返回帧数组,getTraceAsString() 输出字符串栈,getDefinedVars() 取某帧局部变量。$level 正数从当前向顶部数,负数反向计数,规则与 debug_backtrace 选项相通。修改局部变量属于高危调试能力,setLocalVar() 默认保持参数默认值。

原理流程

  1. 通过 getTraceDepth() 了解栈深度。
  2. getTrace($level, $limit, $options) 定位目标帧。
  3. getDefinedVars($level) 读取该帧变量快照。
  4. 调试场景下才考虑 setLocalVar() 写回变量。

代码或图示

<?php
// 文档示例:读取当前协程调用栈
use Swow\Coroutine;

Coroutine::run(static function (): void {
    $co = Coroutine::getCurrent();
    echo $co->getTraceAsString(0, 0, 0);
});

常见误区

  • 在生产业务里读局部变量做决策:依赖内部帧结构,脆弱且影响性能。
  • 混淆 level 方向:正负 level 计数方向不同,按文档示例核对。

追问

  • 还有哪些调试方法?答:getExecutedFilename()、getExecutedFunctionName()、getExecutedLineno() 读取帧位置;eval()、call() 在指定作用域执行,使用风险高。
  • 回溯信息与 Xdebug 兼容吗?答:调试扩展对协程栈的支持需单独验证(待确认)。

06.5.7.3-019 阻塞在 IO 上的协程如何被唤醒?

一句话结论

协程调用被 hook 的 IO 操作且暂时不可完成时挂起并登记等待条件;事件循环检测到 fd 可读可写或超时后,调度器把对应协程放回就绪队列,下次调度时从挂起点恢复。

概念解释

IO 并发的核心:等待期间不占着 CPU,让出给其他协程。等待条件包括 fd 可读/可写、定时器到期、Channel 有数据、同步计数归零等。唤醒后协程继续执行挂起点之后的语句;IO 结果通过返回值或异常返回。未被 hook 的阻塞调用不会走这条路径,会卡住事件循环。

原理流程

  1. 协程执行被 hook 的读写/等待调用。
  2. 条件不满足:保存栈帧,登记等待事件,让出调度。
  3. 事件循环等待下一就绪事件;其他就绪协程先运行。
  4. 事件就绪/超时:协程回到就绪队列,恢复执行并拿到结果或异常。

代码或图示

<?php
// 文档示例:Channel 空队列时 pop 挂起,有数据后唤醒
use Swow\Channel;
use Swow\Coroutine;

$channel = new Channel(1);
Coroutine::run(static function () use ($channel): void {
    $item = $channel->pop(3000); // 空则挂起等待
});
$channel->push("item");

常见误区

  • 以为 IO 调用忙等轮询:hook 后是事件驱动挂起,不靠循环 sleep 检查。
  • 忽略超时分支:未超时唤醒与超时异常要分开处理。

追问

  • 调度器实现要点在哪一页?答:06.5.7.7 调度器与 hook 机制。
  • 挂起协程怎么查?答:Coroutine::getAll() 遍历状态与调用栈,定位挂起点。

06.5.7.3-020 排查当前协程问题的常用观测手段有哪些?

一句话结论

常用手段包括:getCurrent()/getId() 记录协程标识,getStateName()/isAlive() 判断状态,getAll() 遍历存活协程,getTraceAsString() 读取调用栈,配合耗时与切换次数字段定位挂起点;进阶使用 SDB 调试器动态观测。

概念解释

排障从“哪个协程、什么状态、卡在哪一帧、等了多久”四个问题入手。日志中带 CID;怀疑挂起时遍历 getAll 找 waiting 协程并打印栈;慢协程看 elapsed 与 switches;异常协程看退出状态。观测代码本身要轻量,避免高频遍历影响服务。

原理流程

  1. 入口日志记录 CID 与请求标识。
  2. 异常/超时时抓取当前协程栈与状态字段。
  3. 独立观测协程周期性 getAll 快照,发现长期 waiting 协程。
  4. 必要时接入调试器或外部诊断工具深入查看。

代码或图示

<?php
// 文档示例:排障快照采集
use Swow\Coroutine;

function dumpCoroutineSnapshot(): void
{
    foreach (Coroutine::getAll() as $id => $co) {
        echo $id, $co->getStateName(), $co->getElapsedAsString(), PHP_EOL;
        echo $co->getTraceAsString(0, 5, 0), PHP_EOL;
    }
}

常见误区

  • 只记错误消息不记 CID 与栈:并发下无法关联是哪个请求协程出的问题。
  • 生产环境长期开启全量遍历打印:观测开销需压测评估。

追问

  • 调试观测专题在哪一批?答:06.5.7.13 调试观测与性能分析(规划中)。
  • 如何确认本机扩展可用并支持这些方法?答:php --ri swow 加载扩展后反射类方法列表;本批环境未安装,方法名以官方 API 文档为准(待确认)。