同步-异步桥接(AsyncOperation / SyncAsyncBridge / 分层等待策略)
状态:P0/P1/P2 已交付(本仓库 Core 层)——P3(生命周期链,需 Contracts 变更)与 Runtime 层接入 留待下一阶段统一实施(决策:先只改 Core 层)。 定位:Core 级公共协调组件——把"同步线程原地阻塞等异步操作"统一改造为 「异步信号 + 可轮询状态句柄 + 分层等待 + 独立执行池」的通用基建。 关联:
async-primitives.md(AsyncManualResetEvent 等底座)|dedicated-task-scheduler.md(独立池)|lifecycle.md(生命周期链)|io.md(网络文件系统同步 API)。
0. 一句话结论
要做,但不是三件全新的事,而是"一件新抽象 + 两处复用":
- 新抽象:
AsyncOperation——发起即返回的状态句柄(可轮询 / 可异步等 / 可同步兜底等),把散落各处的Task+.Wait()/GetAwaiter().GetResult()收敛成一个有状态机契约、有诊断、有超时规范的类型; - 复用一:同步等待策略 =
AsyncManualResetEvent.Wait(timeout)已实现的「自旋 → park 分片」分层等待(不是裸Thread.Yield()循环,见 §5 的修正理由); - 复用二:独立池 =
IsolatedTaskScheduler(桥默认持有一个进程级 well-known 实例),不重造线程池。
1. 背景:现状的三条 sync-over-async 链
调研(src/ 全量)结论——真正的同步等待热点集中在三条链:
| 链 | 热点(文件:行) | 现状 |
|---|---|---|
| ① IO 同步 API 桥 | IO/Remote/ObjectStoreExtensions.cs(7 个同步便捷包装)、IO/Remote/RemoteFileHandle.cs 同步族(Write/Read/Seek/SetLength/Flush/WriteVector——同步 IFileHandle over 异步 staging)、RemoteFileHandle.cs#FlushMultipartAsync(multipart——已真异步化,全 await)、IO/Remote/RemoteFileSystem.cs 桥接点与 fencing 三处(TryAcquireOrTakeover/Heartbeat/ReleaseLease;Thread.Sleep(15) 尽力型退避保留) |
调用线程(可能是公共池线程)原地阻塞等异步对象存储操作 |
| ② Runtime 屏障 | LogBase.Write.cs 同步 Flush 等待点(FlushPage/DrainInFlightSync 等 _inFlightFlush)、Snapshot/SnapshotBase.WriteSession.cs#同步终刷(原 BlobBase 已更名归位)、Storage/Compact/DefaultCompactor.cs#压缩轨同步等待(_inFlight.Wait)、EntryLog.cs#WaitForCommitAsync(名义异步实为锁内 Monitor.Wait(10)) |
同步 flush/compact 轨阻塞等异步页落盘 |
| ③ 生命周期链 | Lifecycle/LifecycleBase.cs#WaitForReady(→ _recoverTask.Wait())、#初始化重试守卫(prior.Wait())、#Dispose 收尾(等 recover task);Storage/StorageEngineBuilder.cs#WaitForReady 兜底(原 StorageEngineFactory/BlobBase 载体已撤并);结构层现 5 处 _engine.WaitForReady()(StorageEngineBuilder/WholeMirrorPersistence×2/MetadataMetaTransport×2/BlittableRing) |
同步等待后台恢复 task |
(本提案的直接动因):引擎恢复实质同步、Task.Factory.StartNew(LongRunning) 调度延迟,
导致 Initialize 已返回而 RecoveryState 停在 NotStarted——WaitGuardPreCheck
(LifecycleBase.cs#WaitGuardPreCheck)抛"恢复任务尚未启动"。根因归类为
「状态转移依赖了被调度」:发起线程返回时,连'已受理'这个事实都观测不到。
2. 目标 / 非目标
目标:
- 提供通用操作句柄
AsyncOperation:发起 → 立即返回句柄;三种消费模式(轮询 / 异步等 / 同步兜底等); - 同步等待一律走分层策略(自旋 → park 分片),全程有界(强制超时);
- "写路径必须同步转异步"的场景(IO 同步 API 桥)由桥专用独立池承载,异步工作的推进不依赖公共池可用性;
- 状态机可见性原则:发起线程在返回前同步完成"受理"状态转移(消灭 NotStarted 窗口);
- 全链路诊断:等待计数、等待时长、超时现场(对齐 SpinRWLock 值示波器哲学)。
非目标(明确不做):
- ❌ 不重造线程池 / 信号量 / MRES——复用
IsolatedTaskScheduler+AsyncManualResetEvent; - ❌ 不改造内存序屏障类等待(SpinRWLock / epoch drain / freeze / 段表双尾水位,见 §9 不改清单);
- ❌ 不消灭 Dispose 终局 join——Dispose 需要确定性结束,只加超时与诊断;
- ❌ 不做"任务编排框架"(DAG / 重试 / 级联取消)——那是 RecoveryBase / worker-loop 的领地。
3. 总体设计(三层)
┌────────────────────────────────────────────────────────────┐
│ 消费层(调用方) │
│ 轮询 op.Status / IsCompleted —— 多消费者安全 │
│ await op.WaitAsync(ct) —— 异步一等公民 │
│ op.Wait(timeoutMs) —— 同步兜底(有界) │
├────────────────────────────────────────────────────────────┤
│ 句柄层 AsyncOperation(Core.Primitives,新) │
│ 状态机: Running → Succeeded | Failed | Canceled(CAS 单次)│
│ 内嵌 AsyncManualResetEvent(复用)作完成信号 │
│ 异常槽 + 诊断环形缓冲(#if DEBUG) │
├────────────────────────────────────────────────────────────┤
│ 桥接层 SyncAsyncBridge(Core.Shared,新) │
│ Start(work) → 独立池执行 work → 完成/异常/取消 → ReportX │
│ 独立池 = IsolatedTaskScheduler(进程级 well-known 实例) │
│ 再入防护(AsyncLocal 深度计数)+ 强制有界默认超时 │
└────────────────────────────────────────────────────────────┘
三层职责一句话:桥负责"去哪跑",句柄负责"怎么样了",等待策略负责"怎么等"。
8. 硬性要求(踩过的坑——禁止重蹈)
- ❌ 同步等待必须有界——所有
Wait(timeout)强制超时;发现无界.Wait()/GetAwaiter().GetResult()新增点 = review 阻断项。超时不是失败,是诊断入口(带现场 WARN)。 - ❌ 禁止在持锁期间同步等桥操作——等待者持锁 + 完成者需要该锁 = 必死。桥不做锁检测(成本高), 靠契约 + 违例时快速超时暴露。
- ❌ 桥 work 内禁止同步阻塞 / 再入同桥——work 是协作式异步契约;再入防护自动抛(§6.3),
但"work 内
Thread.Sleep/ 同步重 IO"只能靠 review 与 watchdog 慢任务告警。 - ❌ 禁止把屏障等待改造成桥——内存序屏障(SpinRWLock / epoch / freeze / 段表水位)等待的是 微秒级内存不变量,完成者就在本进程临界区生态里;跨线程桥接 = 正确性灾难 + 延迟数量级恶化。 它们的自旋/yield 现状就是正解。
- ✅ 先消除、再桥接——高频热点(如
S3ObjectStore.cs每请求签名/凭据路径的同步等待点)的正解是消除同步等待(凭据缓存 / 改真异步签名),不是给坏结构加桥。 - ✅ 发起即受理——新写的"启动后台操作"API,返回前必须同步置 Running(§7); 状态查询多消费者安全,控制流只认终态(对齐 lifecycle.md §4)。
- ✅ 测试与源 1:1 + 契约测试(见 §10)——本组件属 Core 并发原语,无契约测试不许合入。
关联文档
- 异步原语底座:
async-primitives.md - 独立池使用与陷阱:
dedicated-task-scheduler.md - 生命周期编排:
lifecycle.md| 网络文件系统同步 API:io.md - 覆盖矩阵:
unit-test-coverage.md
分册导航:sync-async-bridge.md | [sync-async-bridge-asyncoperation.md](AsyncOperation 契约) | sync-async-bridge-internals.md | AsyncOperation 契约与分层等待 | 桥接层实现与落地映射