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\ 根命名空间。
原理流程
- 确定同步目标:等一组任务完成、等对象销毁、等全部协程退出。
- 选择对应设施:WaitGroup / WaitReference / waitAll。
- 任务协程内更新计数或解除引用。
- 等待协程在设施上挂起,条件达成后唤醒继续。
代码或图示
<?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 或结果结构。
原理流程
- 创建 WaitGroup,在启动任务前
add($delta)。 - 派生任务协程,任务结束调用
done()。 - 汇总协程调用
wait($timeout),计数未归零则挂起。 - 最后一个任务 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)行为按实现与文档确认。
原理流程
- 确定任务数量 N,一次性
add(N)或循环内逐个add(1)。 - 登记完成后再
run()派生任务协程。 - 每个任务结束路径保证
done()被调用。 - 汇总协程 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 可覆盖正常返回与异常两条路径。
原理流程
- 任务协程执行业务与 IO。
- 正常结束或进入 catch 后,finally 中调用
done()。 - 计数器减一,若归零则唤醒 wait 等待者。
- 等待协程恢复后检查任务结果与异常状态。
代码或图示
<?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 超时机制保持一致风格。
原理流程
- 汇总协程调用
$wg->wait($timeoutMs)。 - 计数为零:直接返回;非零:挂起并登记等待。
- 计数归零:唤醒继续执行。
- 超时到期:抛超时异常,调用方决定降级或终止残留任务。
代码或图示
<?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 简洁,但计数隐式依赖引用关系,调试不如图文计数直观。
原理流程
- 创建 WaitReference 对象。
- 派生协程闭包
use ($wr)引用对象。 - 协程运行期间计数大于零;闭包退出引用释放,计数递减。
- 计数归零对象析构,
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 设施一致,单位以文档为准。
原理流程
- 创建
$wr = new WaitReference()。 - 任务闭包 use
$wr。 - 等待方调用
WaitReference::wait($wr, $timeout)。 - 对象销毁后 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 不区分任务归属,等全部已启动协程收敛。优点是写法简单;缺点是无法区分哪些任务完成、无法收集部分失败、与常驻服务模型冲突。命令行脚本验证逻辑时可用;服务请求链路必须用精确同步设施,避免把无关协程纳入等待。
原理流程
- 脚本内启动若干协程。
- 主流程调用
waitAll($timeout)等待全部退出。 - 所有协程结束后继续脚本后续逻辑。
- 常驻服务不要用 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 或任务取消标志处理。异常码区分超时与其他同步错误。
原理流程
- wait 调用传入超时毫秒数。
- 条件在超时内达成:正常返回。
- 超时未达成:抛超时异常,等待方走降级分支。
- 评估残留任务:忽略、通知取消或强制终止。
代码或图示
<?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,并补充异常路径用例。
原理流程
- 汇总协程卡在 wait,快照显示 waiting 且栈为 WaitGroup::wait。
- 遍历任务协程,核对每个任务的退出路径。
- 找到未执行 done 的分支:异常、提前 return、循环 break。
- 调整为 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。
原理流程
- 错误顺序:run → 调度切换 → 汇总 wait(计数 0)→ 提前返回 → add 才执行。
- 正确顺序:add(N) → 循环 run → 任务结束 done → wait 归零唤醒。
- 动态新增任务时,先补 add 再 run 新协程。
- 代码评审检查 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;不要依赖扩展对负数的容错。上线前用并发用例验证计数平衡。
原理流程
- 梳理任务生命周期:登记、执行、完成三个阶段。
- 每个任务入口 add 一次,出口 finally done 一次。
- 评审与测试覆盖异常、重复退出、协程 kill 路径。
- 发现计数异常时先核对配对关系,再查扩展边界行为。
代码或图示
<?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 返回后统一筛选成功/失败项。
原理流程
- 预分配结果容器(数组下标或结果通道)。
- 派生任务,add 登记;任务写自己的结果槽位/通道,finally done。
- wait 等待全部完成或超时。
- 汇总协程合并结果,区分成功项与失败项。
代码或图示
<?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。
原理流程
- 盘点任务派生方式:静态批量或动态增减。
- 评估可读性:团队是否接受引用计数隐式计数。
- 检查额外引用:是否有全局/缓存持有 WaitReference 对象。
- 选定设施后统一项目内用法约定。
代码或图示
选型对照
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 链路。
原理流程
- 定义 Future 封装:持有结果 Channel 与状态。
- 任务协程执行,成功 push 结果,异常 push 错误对象。
- 等待方 pop 单元素通道,按类型还原成功/失败。
- 超时控制复用通道 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 挂起是同一套调度机制,只是等待条件不同。
原理流程
- 汇总协程调用 wait,条件未满足。
- 保存栈帧,登记等待条件,让出调度。
- 调度器运行其他就绪协程(任务、IO 回调、观测器)。
- 条件达成/超时,等待协程入就绪队列,后续恢复执行。
代码或图示
<?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,并避免残留协程访问已释放的共享资源。
概念解释
超时是汇总方的决策点,不是任务的终止信号。任务可能因下游慢、死锁或泄漏仍在运行。若直接丢弃结果容器,残留任务写入时访问已释放结构会出问题;需要保留任务上下文到其结束,或通过取消标志让任务自行退出。长期残留需纳入泄漏治理。
原理流程
- wait 超时,进入降级分支。
- 记录超时任务标识与快照,评估残留协程。
- 需要取消时设置标志或向任务注入异常/kill。
- 保留共享资源直到残留任务结束,避免悬空访问。
代码或图示
<?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 依赖设施是否支持多等待者。设计时画出等待关系图,保证等待方与任务方分离,避免环依赖。
原理流程
- 识别汇总协程位置:请求入口或主控协程。
- wait 只在汇总协程调用,任务协程只做 add/done 或写引用。
- 如需多级汇总,分层使用独立 WaitGroup。
- 评审等待关系,确认无闭环。
代码或图示
<?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。
原理流程
- 任务体包裹 try/catch/finally。
- catch 记录异常到结果结构,finally 调 done。
- 汇总 wait 带超时,超时后检查失败与残留。
- 失败项按业务策略重试、降级或告警。
代码或图示
<?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() 配合栈回溯定位挂起点;结果结构与日志辅助判断任务失败点。死锁处理器在全无可运行协程时记录现场。
原理流程
- 监控发现 wait 超时或协程数上涨。
- getAll 遍历 waiting 协程,打印栈帧定位等待设施。
- 检查任务协程是否存活、是否走到 done/解除引用。
- 核对计数配对与结果错误记录,修复遗漏路径并补充用例。
代码或图示
<?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 文档为准(待确认)。