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

06.5.7.5 Sync 等待与同步

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

06.5.7.5-001 Swow\Sync 模块的整体定位是什么?

一句话结论

Swow\Sync 提供多协程同步等待设施:WaitGroup 显式计数等待一组任务完成,WaitReference 基于引用计数等待对象销毁,另有 waitAll() 辅助函数与 ThreadBarrier;模块只负责“等待与唤醒”,数据传递仍走 Channel。

概念解释

协程并发后,主流程需要知道一组任务何时收敛。Sync 设施维护计数或引用状态,等待协程在条件未满足时挂起,条件达成后被唤醒。与 Channel 的分工:Channel 传数据,Sync 只做完成通知。模块内类位于 Swow\Sync\ 命名空间,锁与信号量等底层同步原语在 Swow\ 根命名空间。

原理流程

  1. 确定同步目标:等一组任务完成、等对象销毁、等全部协程退出。
  2. 选择对应设施:WaitGroup / WaitReference / waitAll。
  3. 任务协程内更新计数或解除引用。
  4. 等待协程在设施上挂起,条件达成后唤醒继续。

代码或图示

<?php
// 文档示例(未实测):Sync 设施入口形态
use Swow\Sync\WaitGroup;
use Swow\Sync\WaitReference;
use function Swow\Sync\waitAll;

$wg = new WaitGroup();
$wr = new WaitReference();

常见误区

  • 用 Sync 设施传结果数据:结果收集应配合 Channel 或共享结果结构。
  • 把 WaitGroup 当 Channel:它不传元素,只通知计数归零。

追问

  • 根命名空间还有哪些同步原语?答:Swow\Mutex、Swow\Semaphore、Swow\Futex;临界区保护见 06.5.7.8。
  • ThreadBarrier 用途?答:线程/协程会合屏障;适用边界以 API 文档为准(待确认)。

06.5.7.5-002 WaitGroup 的内部模型与三个核心方法是什么?

一句话结论

Swow\Sync\WaitGroup 内部维护一个计数器:add(int $delta) 增加计数表示新任务加入,done() 计数减一表示任务完成,wait(int $timeout) 挂起等待计数归零;归零时唤醒等待协程。

概念解释

WaitGroup 是显式计数的汇合设施,思路与 Go WaitGroup 一致。计数大于零时 wait 挂起;每次 done 后检查是否归零,归零则唤醒等待者。add 通常在派生协程之前调用,保证等待方看到计数变化。设施本身不传任务结果,结果由任务协程写入 Channel 或结果结构。

原理流程

  1. 创建 WaitGroup,在启动任务前 add($delta)。
  2. 派生任务协程,任务结束调用 done()。
  3. 汇总协程调用 wait($timeout),计数未归零则挂起。
  4. 最后一个任务 done 使计数归零,等待协程唤醒继续。

代码或图示

<?php
// 文档示例:WaitGroup 标准用法
use Swow\Coroutine;
use Swow\Sync\WaitGroup;

$wg = new WaitGroup();
$wg->add(2);
foreach ([1, 2] as $i) {
    Coroutine::run(static function () use ($wg, $i): void {
        // 任务逻辑
        $wg->done();
    });
}
$wg->wait(5000);

常见误区

  • 在协程内部 add:wait 可能先于 add 执行,计数仍为零而提前返回。
  • 任务异常退出不调 done:计数不归零,等待方超时或永久挂起。

追问

  • wait 是阻塞当前协程吗?答:条件未满足时挂起当前协程并发生上下文切换;不是忙等轮询。
  • 可以有多个协程同时 wait 同一个 WaitGroup 吗?答:等待者模型以文档为准(待确认),常规用法是单一汇总协程等待。

06.5.7.5-003 add(delta) 的计数规则与调用时机是什么?

一句话结论

add(int $delta) 把计数器增加指定增量(通常为 1);必须在派生对应任务之前调用,确保 wait 不会看到“计数为零”的中间状态;增量为正表示登记新任务。

概念解释

计数正确性依赖调用顺序:先登记任务,再启动协程。若先 run 后 add,调度器可能在 add 之前切到汇总协程,wait 看到零计数直接返回。批量任务可一次性 add($n),也可逐个 add。计数变化的边界(减到负数、重复 add)行为按实现与文档确认。

原理流程

  1. 确定任务数量 N,一次性 add(N) 或循环内逐个 add(1)。
  2. 登记完成后再 run() 派生任务协程。
  3. 每个任务结束路径保证 done() 被调用。
  4. 汇总协程 wait 等待归零。

代码或图示

<?php
// 文档示例:批量预登记计数
use Swow\Coroutine;
use Swow\Sync\WaitGroup;

$wg = new WaitGroup();
$tasks = ["a", "b", "c"];
$wg->add(count($tasks));
foreach ($tasks as $tag) {
    Coroutine::run(static function () use ($wg, $tag): void {
        // 处理 $tag
        $wg->done();
    });
}
$wg->wait(5000);

常见误区

  • add 写在 run 闭包内部:存在竞态窗口,等待方可能提前返回。
  • 任务数量动态变化时不补 add:新增任务未登记,wait 提前结束。

追问

  • delta 可以传负数吗?答:方法签名为 add(int $delta);负数语义与边界行为待确认,常规用法只传正数。
  • 重复 add 同一任务会怎样?答:计数多算一次,必须对应多次 done,否则不归零。

06.5.7.5-004 done() 的语义与计数归零唤醒规则是什么?

一句话结论

done() 将计数器减一;减到零时所有等待者被唤醒。任务无论成功还是异常结束,都必须保证 done 被调用,通常放在 finally 块中。

概念解释

done 是任务完成的通知点。计数归零的判定在每次 done 后执行;等待协程从 wait 挂起点恢复。如果任务抛异常跳过 done,计数残留,等待方只能靠超时兜底。把 done 放进 finally 可覆盖正常返回与异常两条路径。

原理流程

  1. 任务协程执行业务与 IO。
  2. 正常结束或进入 catch 后,finally 中调用 done()。
  3. 计数器减一,若归零则唤醒 wait 等待者。
  4. 等待协程恢复后检查任务结果与异常状态。

代码或图示

<?php
// 文档示例:finally 保证 done 执行
use Swow\Coroutine;
use Swow\Sync\WaitGroup;

$wg = new WaitGroup();
$wg->add(1);
Coroutine::run(static function () use ($wg): void {
    try {
        // 业务与 IO
    } catch (\Throwable $e) {
        // 记录异常
    } finally {
        $wg->done();
    }
});
$wg->wait(5000);

常见误区

  • done 写在业务成功分支:异常路径漏调导致计数残留。
  • 一个任务多次 done:计数变负,行为异常。

追问

  • 计数减到负数会抛错吗?答:边界行为待确认,以 WaitGroup 实现与文档为准;业务上应保证 done 次数与 add 一致。
  • 如何收集任务异常?答:任务协程把异常存入结果结构或错误 Channel,wait 返回后统一检查。

06.5.7.5-005 wait(timeout) 的阻塞与唤醒行为是什么?

一句话结论

wait(int $timeout) 在计数未归零时挂起当前协程等待,超时毫秒数到达仍未归零则抛异常;计数归零后唤醒继续。等待期间调度器可运行其他就绪协程。

概念解释

wait 是汇合点:调用方协程让出 CPU,不占用循环轮询。超时防止任务永久挂起拖垮主流程;超时后计数可能仍未归零,残留任务继续在后台运行(除非另行终止)。超时参数单位与异常类型以 API 文档为准,与 Channel 超时机制保持一致风格。

原理流程

  1. 汇总协程调用 $wg->wait($timeoutMs)。
  2. 计数为零:直接返回;非零:挂起并登记等待。
  3. 计数归零:唤醒继续执行。
  4. 超时到期:抛超时异常,调用方决定降级或终止残留任务。

代码或图示

<?php
// 文档示例:带超时的等待
use Swow\Sync\WaitGroup;
use Swow\SyncException;

$wg = new WaitGroup();
$wg->add(1);
try {
    $wg->wait(3000);
} catch (SyncException $e) {
    // 超时或同步设施异常,按错误码处理
    echo $e->getCode();
}

常见误区

  • 省略超时无限等待:单个任务卡死会拖住整个汇总流程。
  • 超时后假设任务已结束:残留协程可能仍在运行,需评估是否 kill 或忽略。

追问

  • 等待超时抛哪个异常类?答:Swow\SyncException 及其子类;具体异常映射以 API 文档为准(待确认)。
  • wait 可以重复调用吗?答:归零后再次 wait 的行为待确认;常规用法只在汇总点调用一次。

06.5.7.5-006 WaitReference 的引用计数原理是什么?

一句话结论

WaitReference 借用 PHP 对象引用计数作为计数器:闭包/协程引用该对象使计数增加,闭包退出引用释放使计数减少;引用归零时对象析构,wait() 等待方被唤醒。

概念解释

这是 PHP 引用计数语言特有的同步设施:不需要手写 done,任务协程闭包 use 引用 WaitReference 对象,引用关系本身就是计数。闭包执行结束释放 use 引用,计数回落;所有引用解除后对象销毁,等待方感知销毁并唤醒。语义比 WaitGroup 简洁,但计数隐式依赖引用关系,调试不如图文计数直观。

原理流程

  1. 创建 WaitReference 对象。
  2. 派生协程闭包 use ($wr) 引用对象。
  3. 协程运行期间计数大于零;闭包退出引用释放,计数递减。
  4. 计数归零对象析构,WaitReference::wait() 等待方唤醒。

代码或图示

<?php
// 文档示例:引用计数等待
use Swow\Coroutine;
use Swow\Sync\WaitReference;

$wr = new WaitReference();
for ($i = 0; $i < 3; $i++) {
    Coroutine::run(static function () use ($wr, $i): void {
        // 任务逻辑;闭包持有 $wr 引用
    });
}
WaitReference::wait($wr, 5000);

常见误区

  • 在协程外额外保存 $wr 引用不释放:计数不归零,wait 永久挂起。
  • 把 WaitReference 当 WaitGroup 调 done:它没有显式 done 方法。

追问

  • 引用计数何时增加?答:闭包 use 绑定、对象赋值等引用关系都会影响计数;需理解 PHP 引用计数规则。
  • 与 WaitGroup 怎么选?答:计数关系清晰、需要显式控制选 WaitGroup;闭包自然绑定、不愿手写 done 选 WaitReference。

06.5.7.5-007 WaitReference::wait 的静态调用形式是什么?

一句话结论

WaitReference::wait(self &$ref, int $timeout) 是静态方法,通过引用传参接收 WaitReference 对象,等待其被销毁;调用形式为 WaitReference::wait($wr, $timeoutMs)。

概念解释

方法签名要求按引用传递对象变量,便于在等待过程中处理对象生命周期。等待方持有变量引用,任务闭包持有另一引用;所有任务退出后引用归零,对象析构,静态 wait 返回。超时参数与其他 Sync 设施一致,单位以文档为准。

原理流程

  1. 创建 $wr = new WaitReference()。
  2. 任务闭包 use $wr。
  3. 等待方调用 WaitReference::wait($wr, $timeout)。
  4. 对象销毁后 wait 返回;超时抛对应异常。

代码或图示

<?php
// 文档示例:静态 wait 调用
use Swow\Coroutine;
use Swow\Sync\WaitReference;

$wr = new WaitReference();
Coroutine::run(static function () use ($wr): void {
    // 任务
});
WaitReference::wait($wr, 5000);

常见误区

  • 实例化后当成 $wr->wait() 调用:wait 是静态方法,调用形式不要写错。
  • 传值而非引用:按签名要求传变量引用,具体行为以文档为准(待确认)。

追问

  • wait 返回值是什么?答:文档签名为 void;等待结束后通过结果结构获取任务产物。
  • 对象提前析构会怎样?答:若任务闭包尚未执行完引用已释放,等待方可能提前唤醒;需检查引用绑定是否完整。

06.5.7.5-008 waitAll() 的用途与定位是什么?

一句话结论

Swow\Sync\waitAll(int $timeout) 等待当前所有协程退出,粒度粗,适合脚本收尾与简单原型;官方不推荐在业务核心链路使用,正式同步优先 WaitGroup/WaitReference 精确控制。

概念解释

waitAll 不区分任务归属,等全部已启动协程收敛。优点是写法简单;缺点是无法区分哪些任务完成、无法收集部分失败、与常驻服务模型冲突。命令行脚本验证逻辑时可用;服务请求链路必须用精确同步设施,避免把无关协程纳入等待。

原理流程

  1. 脚本内启动若干协程。
  2. 主流程调用 waitAll($timeout) 等待全部退出。
  3. 所有协程结束后继续脚本后续逻辑。
  4. 常驻服务不要用 waitAll 维持运行,应由事件循环或服务循环保持。

代码或图示

<?php
// 文档示例:脚本级等待全部协程
use Swow\Coroutine;
use function Swow\Sync\waitAll;

for ($i = 0; $i < 3; $i++) {
    Coroutine::run(static function (): void {
        // 任务
    });
}
waitAll(5000);

常见误区

  • 在服务请求处理中用 waitAll:会等到所有协程(含其他请求)结束,完全错误。
  • 用 waitAll 代替任务级同步:无法定位未完成任务,也无法收集结果。

追问

  • waitAll 超时后行为?答:超时抛异常,残留协程状态需自行评估;具体语义以文档为准(待确认)。
  • 粗粒度等待还有哪些替代?答:按业务边界建 WaitGroup,逐组等待与汇总。

06.5.7.5-009 超时控制参数的单位与超时后的行为是什么?

一句话结论

Sync 设施的 timeout 参数按毫秒传入(与 Channel/Socket 超时单位一致,具体以当前 API 文档为准);超时未满足条件抛同步异常,等待方解除挂起,被等待任务是否继续运行取决于其自身逻辑。

概念解释

超时是兜底保护,避免同步设施永久挂起。超时发生后:等待协程从 wait 恢复并进入异常分支;任务协程不被自动终止,可能继续执行或后续自行退出。需要强制取消时,结合协程 kill 或任务取消标志处理。异常码区分超时与其他同步错误。

原理流程

  1. wait 调用传入超时毫秒数。
  2. 条件在超时内达成:正常返回。
  3. 超时未达成:抛超时异常,等待方走降级分支。
  4. 评估残留任务:忽略、通知取消或强制终止。

代码或图示

<?php
// 文档示例:超时降级骨架
use Swow\Sync\WaitGroup;
use Swow\SyncException;

$wg = new WaitGroup();
$wg->add(1);
try {
    $wg->wait(2000);
} catch (SyncException $e) {
    // 超时:记录并走降级流程,不假设任务已结束
}

常见误区

  • 超时单位记成秒:毫秒/秒混淆会导致等待时间差千倍;以文档核实为准。
  • 超时后立即清理任务引用:残留协程可能仍在使用共享资源。

追问

  • 超时异常类与码值?答:Swow\SyncException 体系;常量对照 Swow\Errno(待确认)。
  • 如何设置无限等待?答:是否允许 null/0 表示不超时待确认;业务上建议总是设置超时兜底。

06.5.7.5-010 忘记 done() 导致永久挂起的典型场景是什么?

一句话结论

任务协程在异常、提前 return 或分支遗漏路径中未调用 done,计数不归零,wait 协程挂起到超时;典型表现是接口长尾超时、汇总流程卡住,日志显示等待协程栈停在 wait 上。

概念解释

排查时先看 WaitGroup 计数与等待协程栈:挂起点在 wait(),逐个核对任务协程是否都走到 done。异常分支、提前退出、条件分支跳过、任务被 kill 都是漏 done 的位置。修复方式是 done 入 finally,并补充异常路径用例。

原理流程

  1. 汇总协程卡在 wait,快照显示 waiting 且栈为 WaitGroup::wait。
  2. 遍历任务协程,核对每个任务的退出路径。
  3. 找到未执行 done 的分支:异常、提前 return、循环 break。
  4. 调整为 finally 调用 done,补充对应测试用例。

代码或图示

<?php
// 错误示范(文档示例):异常路径漏 done
use Swow\Coroutine;
use Swow\Sync\WaitGroup;

$wg = new WaitGroup();
$wg->add(1);
Coroutine::run(static function () use ($wg): void {
    try {
        // 可能抛异常
    } catch (\Throwable $e) {
        // 此处漏调 $wg->done()
    }
    $wg->done(); // 异常时到不了这里
});

常见误区

  • 只在成功路径写 done:异常与提前返回路径必须覆盖。
  • 依赖框架自动补 done:WaitGroup 计数必须由业务代码显式维护。

追问

  • 如何在测试中复现?答:构造任务抛异常用例,观察 wait 是否超时;配合 getAll 快照确认残留协程。
  • 计数残留如何在线上发现?答:监控 wait 耗时与协程数增长,挂起协程快照定期采样。

06.5.7.5-011 add() 位置错误导致提前返回是什么问题?

一句话结论

先 run() 派生协程后 add(),调度器可能在 add 之前切到汇总协程,wait 看到计数为零直接返回,后续任务结果尚未产生;正确顺序是先登记计数再启动协程。

概念解释

这是竞态顺序问题:WaitGroup 计数是共享状态,add 与 run 的先后决定可见性。协程启动后可能立即让出(IO 等待),汇总协程得以运行;若 add 尚未执行,wait 误判任务已全部完成。批量任务推荐一次性 add(N) 再循环 run。

原理流程

  1. 错误顺序:run → 调度切换 → 汇总 wait(计数 0)→ 提前返回 → add 才执行。
  2. 正确顺序:add(N) → 循环 run → 任务结束 done → wait 归零唤醒。
  3. 动态新增任务时,先补 add 再 run 新协程。
  4. 代码评审检查 add 与 run 的相对位置。

代码或图示

<?php
// 文档示例:正确顺序
use Swow\Coroutine;
use Swow\Sync\WaitGroup;

$wg = new WaitGroup();
$tasks = [1, 2, 3];
$wg->add(count($tasks)); // 先登记
foreach ($tasks as $task) {
    Coroutine::run(static function () use ($wg, $task): void {
        // 任务
        $wg->done();
    });
}
$wg->wait(5000); // 后等待

常见误区

  • 在闭包内第一条语句 add:等于先启动后登记,窗口仍然存在。
  • 动态任务不更新计数:新增分支未 add,wait 提前结束。

追问

  • 如何测试顺序问题?答:任务体开头让出或 sleep,观察汇总协程是否提前返回。
  • WaitReference 有同类问题吗?答:它依赖引用关系,闭包 use 在创建协程时即绑定;仍需检查引用是否被意外释放。

06.5.7.5-012 计数变为负数或未 add 就 done 会发生什么?

一句话结论

done 次数超过 add 次数会使计数异常;具体是抛异常、钳位还是静默变负,以 WaitGroup 实现为准(待确认)。业务上必须保证 add/done 配对,不依赖兜底行为。

概念解释

计数不变量:每次 add 对应一次 done。违反不变量时,等待唤醒条件可能错误:计数本应归零却继续减少,或归零判定失准。安全做法是代码层面保证配对,异常路径用 finally 补 done;不要依赖扩展对负数的容错。上线前用并发用例验证计数平衡。

原理流程

  1. 梳理任务生命周期:登记、执行、完成三个阶段。
  2. 每个任务入口 add 一次,出口 finally done 一次。
  3. 评审与测试覆盖异常、重复退出、协程 kill 路径。
  4. 发现计数异常时先核对配对关系,再查扩展边界行为。

代码或图示

<?php
// 文档示例:配对检查骨架
$registered = 0;
$finished = 0;
// 启动前 $wg->add(1); $registered++;
// 结束 finally $wg->done(); $finished++;
// 排障时对比两者是否相等

常见误区

  • 一个任务内多处 return 各调一次 done:重复 done 破坏计数。
  • 复用 WaitGroup 实例跑多批任务:计数状态可能残留,按需新建实例。

追问

  • 如何查看当前计数?答:WaitGroup 是否暴露 count/ getter 待确认;以 API 文档为准。
  • 计数异常抛什么异常?答:Swow\SyncException 体系;具体触发条件待确认。

06.5.7.5-013 多任务结果汇总如何与 WaitGroup 配合?

一句话结论

WaitGroup 只通知完成,结果由任务协程写入结果结构或结果 Channel;wait 返回后汇总协程统一读取。共享结果数组的写入需按协程安全规则处理,推荐每个任务写独立下标或走 Channel。

概念解释

典型并发聚合:多个协程并行调用下游,汇总点等全部完成后合并结果。任务协程把结果放入预分配数组的专属下标,或 push 到结果 Channel;WaitGroup 保证时序,不负责数据归集。异常任务把错误存入结果结构,wait 返回后统一筛选成功/失败项。

原理流程

  1. 预分配结果容器(数组下标或结果通道)。
  2. 派生任务,add 登记;任务写自己的结果槽位/通道,finally done。
  3. wait 等待全部完成或超时。
  4. 汇总协程合并结果,区分成功项与失败项。

代码或图示

<?php
// 文档示例:并发结果汇总骨架
use Swow\Coroutine;
use Swow\Sync\WaitGroup;

$wg = new WaitGroup();
$results = [];
$items = ["a", "b", "c"];
$wg->add(count($items));
foreach ($items as $index => $tag) {
    Coroutine::run(static function () use ($wg, &$results, $index, $tag): void {
        $results[$index] = ["tag" => $tag, "value" => "ok"];
        $wg->done();
    });
}
$wg->wait(5000);

常见误区

  • 多个协程并发 append 同一数组:顺序与下标竞争,应使用专属下标或通道。
  • wait 返回后不检查失败项:异常任务的结果槽位可能为空,需要容错分支。

追问

  • 下游调用超时怎么隔离?答:每个任务内部设置客户端超时与 catch,不让单个异常中断其他任务。
  • 结果容量很大怎么办?答:考虑流式 Channel 分批汇总,避免大数组常驻内存。

06.5.7.5-014 WaitGroup 与 WaitReference 如何选型?

一句话结论

需要显式计数、任务动态增减、调试可读选 WaitGroup;闭包自然持有引用、任务结构简单、希望省略 done 选 WaitReference。两者都服务于“等待完成”,不承担数据传递。

概念解释

选型看计数来源:任务生命周期由代码显式控制(循环派生、动态加入)时,WaitGroup 的 add/done 直观可审计;任务闭包天然持有上下文对象时,WaitReference 减少样板代码。WaitReference 依赖引用计数语义,额外持有引用会破坏等待条件;复杂任务图优先 WaitGroup。

原理流程

  1. 盘点任务派生方式:静态批量或动态增减。
  2. 评估可读性:团队是否接受引用计数隐式计数。
  3. 检查额外引用:是否有全局/缓存持有 WaitReference 对象。
  4. 选定设施后统一项目内用法约定。

代码或图示

选型对照
WaitGroup:显式 add/done,计数可读,适合动态任务与审计
WaitReference:引用计数驱动,样板少,适合闭包绑定的简单任务
waitAll:脚本收尾,不进业务核心链路

常见误区

  • 在复杂任务图里用 WaitReference:引用关系分散后难以判断何时归零。
  • 两种设施混用等同一批任务:等待条件重复或遗漏。

追问

  • WaitReference 能取任务返回值吗?答:与其他协程一样,通过闭包写入的结果结构或 Channel 获取。
  • 项目内统一哪种?答:建议业务链路统一 WaitGroup,脚本工具可用 WaitReference/waitAll。

06.5.7.5-015 Promise/Future 式封装在 Swow 中如何对照实现?

一句话结论

Swow 不强制提供 Promise/Future 抽象;可用“Channel 单元素 + WaitGroup/WaitReference”组合实现 Future 语义:任务协程完成后向单元素通道写入结果或异常,等待方 pop 取回。

概念解释

Promise 模式把异步结果包装为可等待对象:内部保存状态、结果或异常,提供等待方法。在 Swow 中,Channel 承担结果交接,Sync 设施承担完成等待;封装类在其上记录状态与异常。业务也可直接用 Channel 收集结果,不必引入完整 Promise 链路。

原理流程

  1. 定义 Future 封装:持有结果 Channel 与状态。
  2. 任务协程执行,成功 push 结果,异常 push 错误对象。
  3. 等待方 pop 单元素通道,按类型还原成功/失败。
  4. 超时控制复用通道 pop 超时参数。

代码或图示

<?php
// 文档示例:Future 式封装骨架
use Swow\Channel;

final class Future
{
    public function __construct(public readonly Channel $channel = new Channel(1))
    {
    }

    public function resolve(mixed $value): void
    {
        $this->channel->push($value, 1000);
    }

    public function await(int $timeoutMs): mixed
    {
        return $this->channel->pop($timeoutMs);
    }
}

常见误区

  • 把 Future 当线程池句柄:封装只解决结果交接,不管理并发额度。
  • 通道容量设 0 做单结果:单结果用容量 1 即可,避免会合等待问题。

追问

  • 有官方 Promise 包吗?答:以 swow/swow 库与生态包清单为准(待确认);本批不假设存在。
  • 链式 then 如何实现?答:应用层在 Future 封装内串联回调;复杂度高时评估是否直接用 Channel 流程式代码。

06.5.7.5-016 等待期间调度器如何调度其他协程?

一句话结论

wait 挂起当前协程后,调度器从就绪队列选择其他协程执行;等待条件达成或超时后,当前协程回到就绪队列等待恢复。等待不占用 CPU 轮询,IO 与其他任务可继续推进。

概念解释

Sync 设施挂起时登记等待条件(计数归零、引用销毁),协程从运行态转 waiting。调度器转而执行其他就绪协程;条件满足时对应等待协程被唤醒入就绪队列。这与 Channel 挂起是同一套调度机制,只是等待条件不同。

原理流程

  1. 汇总协程调用 wait,条件未满足。
  2. 保存栈帧,登记等待条件,让出调度。
  3. 调度器运行其他就绪协程(任务、IO 回调、观测器)。
  4. 条件达成/超时,等待协程入就绪队列,后续恢复执行。

代码或图示

<?php
// 文档示例:等待期间其他协程继续运行
use Swow\Coroutine;
use Swow\Sync\WaitGroup;

$wg = new WaitGroup();
$wg->add(1);
Coroutine::run(static function () use ($wg): void {
    sleep(1);
    $wg->done();
});
$wg->wait(5000); // 挂起期间其他就绪协程被调度

常见误区

  • 以为 wait 会阻塞整个进程:只挂起当前协程,进程内其他协程继续。
  • 等待期间做重计算:汇总协程挂起后不占 CPU,重活应在任务协程内完成。

追问

  • 调度器实现细节在哪一页?答:06.5.7.7 调度器与 hook 机制。
  • 挂起协程如何观测?答:Coroutine::getAll() 查看 waiting 协程与栈帧。

06.5.7.5-017 超时后计数残留与任务继续运行如何处理?

一句话结论

wait 超时只解除等待方挂起,不自动终止任务协程;残留任务继续运行直至结束或被取消。处理策略:记录超时任务、设置取消标志、必要时 kill,并避免残留协程访问已释放的共享资源。

概念解释

超时是汇总方的决策点,不是任务的终止信号。任务可能因下游慢、死锁或泄漏仍在运行。若直接丢弃结果容器,残留任务写入时访问已释放结构会出问题;需要保留任务上下文到其结束,或通过取消标志让任务自行退出。长期残留需纳入泄漏治理。

原理流程

  1. wait 超时,进入降级分支。
  2. 记录超时任务标识与快照,评估残留协程。
  3. 需要取消时设置标志或向任务注入异常/kill。
  4. 保留共享资源直到残留任务结束,避免悬空访问。

代码或图示

<?php
// 文档示例:超时后记录残留任务
use Swow\Coroutine;
use Swow\Sync\WaitGroup;

$wg = new WaitGroup();
$wg->add(1);
$taskCo = Coroutine::run(static function () use ($wg): void {
    // 长任务
    $wg->done();
});
// 超时后:var_dump($taskCo->isAlive()); 按策略决定是否 kill

常见误区

  • 超时后立即销毁结果容器:残留任务回写导致错误。
  • 反复超时累积残留协程:协程数持续增长最终耗尽内存。

追问

  • 如何通知任务取消?答:共享取消标志、Channel 信号或 Coroutine::throw();任务体需响应取消点。
  • 残留协程如何定期清理?答:观测器遍历 getAll 识别超龄 waiting 协程,按策略终止并告警。

06.5.7.5-018 重复 wait 或在子协程 wait 的注意点是什么?

一句话结论

wait 应在明确的汇总协程中调用一次;重复 wait、在任务协程内等待同一组任务可能造成顺序混乱或死锁。设施等待者模型以 API 文档为准,使用前确认多等待者行为。

概念解释

同步设施的典型拓扑:一个汇总协程等待,多个任务协程更新计数。在任务协程内 wait 同一 WaitGroup 会形成自等待风险;重复 wait 依赖设施是否支持多等待者。设计时画出等待关系图,保证等待方与任务方分离,避免环依赖。

原理流程

  1. 识别汇总协程位置:请求入口或主控协程。
  2. wait 只在汇总协程调用,任务协程只做 add/done 或写引用。
  3. 如需多级汇总,分层使用独立 WaitGroup。
  4. 评审等待关系,确认无闭环。

代码或图示

<?php
// 文档示例:分层等待结构
use Swow\Coroutine;
use Swow\Sync\WaitGroup;

$wg = new WaitGroup();
$wg->add(1);
Coroutine::run(static function () use ($wg): void {
    // 子任务协程:只更新计数,不在内部 wait 本组
    $wg->done();
});
$wg->wait(5000); // 汇总协程等待

常见误区

  • 任务协程末尾 wait 自己所属的 WaitGroup:自等待死锁。
  • 多个协程同时 wait 同一设施却未确认支持行为:唤醒语义可能不符合预期。

追问

  • 多等待者是否支持?答:WaitGroup/WaitReference 多等待者行为待确认,以 API 文档与实现为准。
  • 分层汇总怎么拆?答:每组任务独立 WaitGroup,外层等待各组完成。

06.5.7.5-019 任务抛异常时如何避免 wait 永久阻塞?

一句话结论

任务协程必须在 finally 中 done,并把异常记录到结果结构;否则未捕获异常跳过 done 导致计数残留。wait 必须设置超时兜底,超时后按残留任务策略处理。

概念解释

异常路径是 WaitGroup 挂起的首要原因。防御写法:任务体 try/catch 记录异常,finally 统一 done;汇总 wait 带超时;结果结构中标注失败项。框架若提供协程异常钩子,可配合记录未捕获异常,但不能替代显式 done。

原理流程

  1. 任务体包裹 try/catch/finally。
  2. catch 记录异常到结果结构,finally 调 done。
  3. 汇总 wait 带超时,超时后检查失败与残留。
  4. 失败项按业务策略重试、降级或告警。

代码或图示

<?php
// 文档示例:异常安全的任务写法
use Swow\Coroutine;
use Swow\Sync\WaitGroup;

$wg = new WaitGroup();
$wg->add(1);
$errors = [];
Coroutine::run(static function () use ($wg, &$errors): void {
    try {
        // 可能失败的 IO
    } catch (\Throwable $e) {
        $errors[] = $e->getMessage();
    } finally {
        $wg->done();
    }
});
$wg->wait(5000);

常见误区

  • catch 后不 rethrow 也不记录:异常被静默吞掉,失败无感知。
  • finally 中 done 之前又抛异常:清理动作应自身容错,避免影响 done 执行。

追问

  • 未捕获异常如何上报?答:协程入口兜底 catch 记录日志与 CID;全局钩子机制见错误处理批次 06.5.7.10。
  • 异常任务占用的连接何时归还?答:finally/defer 中归还,与 done 同层保证。

06.5.7.5-020 挂起问题的定位手段有哪些?

一句话结论

定位挂起从等待设施类型入手:快照挂起协程及其栈帧,读取 WaitGroup 计数/状态与等待者,核对任务退出路径;配合超时告警、协程数监控与死锁处理器形成闭环。

概念解释

排障四步:谁在等(协程 ID 与栈)、等什么(WaitGroup/Channel/引用)、对端是否存活(任务协程状态)、计数是否配对。Coroutine::getAll() 配合栈回溯定位挂起点;结果结构与日志辅助判断任务失败点。死锁处理器在全无可运行协程时记录现场。

原理流程

  1. 监控发现 wait 超时或协程数上涨。
  2. getAll 遍历 waiting 协程,打印栈帧定位等待设施。
  3. 检查任务协程是否存活、是否走到 done/解除引用。
  4. 核对计数配对与结果错误记录,修复遗漏路径并补充用例。

代码或图示

<?php
// 文档示例:挂起现场快照
use Swow\Coroutine;

foreach (Coroutine::getAll() as $id => $co) {
    if ($co->getStateName() === "waiting") {
        echo "cid=", $id, PHP_EOL;
        echo $co->getTraceAsString(0, 8, 0), PHP_EOL;
    }
}

常见误区

  • 只看汇总协程栈,不追任务协程状态:根因常在任务异常退出。
  • 复现后不补充回归用例:同类漏 done 问题会再次出现。

追问

  • 调试观测专题在哪一批?答:06.5.7.13 调试观测与性能分析(规划中)。
  • 如何确认本机 Sync 方法签名?答:安装扩展后反射 Swow\Sync\WaitGroup 与 WaitReference;本批环境未安装,签名以官方 API 文档为准(待确认)。