Table of Contents

同步-异步桥接(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. 一句话结论

要做,但不是三件全新的事,而是"一件新抽象 + 两处复用":

  1. 新抽象:AsyncOperation——发起即返回的状态句柄(可轮询 / 可异步等 / 可同步兜底等),把散落各处的 Task + .Wait() / GetAwaiter().GetResult() 收敛成一个有状态机契约、有诊断、有超时规范的类型;
  2. 复用一:同步等待策略 = AsyncManualResetEvent.Wait(timeout) 已实现的「自旋 → park 分片」分层等待(不是裸 Thread.Yield() 循环,见 §5 的修正理由);
  3. 复用二:独立池 = 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. 目标 / 非目标

目标:

  1. 提供通用操作句柄 AsyncOperation:发起 → 立即返回句柄;三种消费模式(轮询 / 异步等 / 同步兜底等);
  2. 同步等待一律走分层策略(自旋 → park 分片),全程有界(强制超时);
  3. "写路径必须同步转异步"的场景(IO 同步 API 桥)由桥专用独立池承载,异步工作的推进不依赖公共池可用性;
  4. 状态机可见性原则:发起线程在返回前同步完成"受理"状态转移(消灭 NotStarted 窗口);
  5. 全链路诊断:等待计数、等待时长、超时现场(对齐 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. 硬性要求(踩过的坑——禁止重蹈)

  1. ❌ 同步等待必须有界——所有 Wait(timeout) 强制超时;发现无界 .Wait() / GetAwaiter().GetResult() 新增点 = review 阻断项。超时不是失败,是诊断入口(带现场 WARN)。
  2. ❌ 禁止在持锁期间同步等桥操作——等待者持锁 + 完成者需要该锁 = 必死。桥不做锁检测(成本高), 靠契约 + 违例时快速超时暴露。
  3. ❌ 桥 work 内禁止同步阻塞 / 再入同桥——work 是协作式异步契约;再入防护自动抛(§6.3), 但"work 内 Thread.Sleep / 同步重 IO"只能靠 review 与 watchdog 慢任务告警。
  4. ❌ 禁止把屏障等待改造成桥——内存序屏障(SpinRWLock / epoch / freeze / 段表水位)等待的是 微秒级内存不变量,完成者就在本进程临界区生态里;跨线程桥接 = 正确性灾难 + 延迟数量级恶化。 它们的自旋/yield 现状就是正解。
  5. ✅ 先消除、再桥接——高频热点(如 S3ObjectStore.cs 每请求签名/凭据路径的同步等待点)的正解是消除同步等待(凭据缓存 / 改真异步签名),不是给坏结构加桥。
  6. ✅ 发起即受理——新写的"启动后台操作"API,返回前必须同步置 Running(§7); 状态查询多消费者安全,控制流只认终态(对齐 lifecycle.md §4)。
  7. ✅ 测试与源 1:1 + 契约测试(见 §10)——本组件属 Core 并发原语,无契约测试不许合入。

关联文档


分册导航:sync-async-bridge.md | [sync-async-bridge-asyncoperation.md](AsyncOperation 契约) | sync-async-bridge-internals.md | AsyncOperation 契约与分层等待 | 桥接层实现与落地映射