Table of Contents

桥接层实现与落地映射

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

6. SyncAsyncBridge(桥接层)

6.1 API 与执行模型

namespace KernLab.Tier.Core.Execution;

public static class SyncAsyncBridge
{
    /// <summary>在桥独立池上发起异步工作,立即返回状态句柄。
    /// ★ 句柄返回时状态已同步置 Running(可见性原则)。</summary>
    public static AsyncOperation Start(
        Func<CancellationToken, ValueTask> work,
        SyncBridgeOptions? options = null,
        CancellationToken ct = default);
}

public sealed record SyncBridgeOptions(含 `Logger` 成员——超时 WARN/泄漏绊线透传)
{
    public string Name { get; init; } = "sync-bridge";  // 诊断名(对齐调度器命名规范)
    public TaskScheduler? Scheduler { get; init; }      // null = 默认桥池;可注入 own 实例
    public int TimeoutMs { get; init; } = SyncAsyncBridge.DefaultTimeoutMs; // 同步 Wait 默认上限(15s——强制有界)
}

执行模型(时序):

同步调用线程                          桥独立池线程(IsolatedTaskScheduler)
────────────                         ──────────────────────────────
op = new AsyncOperation()            (Start 内)
op → Running(同步 CAS)
StartNew(Wrapper, scheduler)   ───►  await work(ct)   ←—— continuation 回流池私有线程
return op     ←—— 立即              │ 成功 → op.ReportSucceeded() → event.Set()
                                     │ OCE   → op.ReportCanceled(oce)
                                     │ 异常  → op.ReportFailed(ex)
...调用方继续干别的(轮询/其他逻辑)...
op.Wait(timeout)   ←—— 最后时刻才等(park,事件唤醒)

关键点:work 是协作式异步契约(await 让出、不阻塞)。work 内部禁止同步阻塞——独立池的 M 很小(§6.2),阻塞任务直接饿死同池操作(对齐 dedicated-task-scheduler.md §7.2)。 真正无法异步化的同步重 IO,由调用方注入 own 单线程实例(Scheduler = IsolatedTaskScheduler.Create(ThreadCount=1, ...))。

6.2 默认桥池选型

决策 值 理由
池类型 IsolatedTaskScheduler.Create(...),进程级 well-known 单例(SyncAsyncBridge.DefaultScheduler,惰性创建,不 Dispose——进程意图资源,对齐 Shared) 桥是"写必须同步转异步"的统一出口,值得一个专属分区;不占用 Shared(那是高频关键 worker 的)
M(线程数) Clamp(ProcessorCount, 2, 4) work 是协作式异步,少量线程即可高并发;对齐 Shared 默认
Watchdog 开(TaskTimeout 下调至 5s) 桥操作应有界;慢任务告警是超时诊断的先导信号
防扩散 桥自身 1 个实例 + 调用方注入受 Create 现有护栏(>4 实例 WARN)管控 不新增护栏机制

6.3 再入防护(自死锁防御)

死锁场景:work(跑在桥池的 M 个线程之一)内部又调了同步 API → 该同步 API 再走桥 → Start 把新 work 入队 → 新 work 需要空闲桥池线程 → M 个线程全在 park 等待嵌套 work → 池自锁。

防护:AsyncLocal<int> _bridgeDepth——Wrapper 执行 work 前置 1(随 await 流动),Start 时检测:

_bridgeDepth > 0 且 Scheduler == 同一池(默认池或同实例)
  → throw InvalidOperationException("桥工作体内禁止再经同一桥同步等待——注入独立 Scheduler 或改异步")

显式注入不同的 Scheduler(分池)即豁免——这是嵌套场景的正解(对齐"compact 同步 worker 与异步建段分池")。

6.4 诊断

  • 指标(挂 Hub 才发,默认零开销——对齐调度器哲学):bridge.op.started / bridge.op.completed / bridge.wait.parked(同步等待进入 park 的次数)/ bridge.wait.timeout / bridge.op.duration_us;
  • 日志:超时 WARN(含 op 名、年龄、状态、当前等待者数 + DEBUG 环形历史);
  • 泄漏绊线:终态为 Failed/Canceled 且从未被任何消费模式观察的操作,finalizer 告警 (对齐 LifecycleBase 终结器泄漏探测)。

7. 状态机可见性原则

发起线程在把句柄/对象交给调用方之前,必须同步完成"受理"状态转移;完成状态归完成侧线程。

这是 NotStarted 问题(§1)的根因修法,也是 AsyncOperation → Running 同步置位的依据。同样适用 于生命周期链(P3 落地项):

现状:LifecycleBase.Initialize(Lifecycle/LifecycleBase.cs#Initialize)调度后台 task 后立即返回, NotStarted → Recovering 的转移发生在后台 task 真正开跑 OnRecoveryStart 时——调度延迟期间 调用方观测到 NotStarted,WaitGuardPreCheck 只能靠抛异常防御(:179-188)。

修法(需 Contracts 小扩展):IRecovery 增加 MarkScheduled()(或等价入口), Initialize 在 Task.Factory.StartNew 之前在调用线程同步调用(RecoveryBase 实现为 CAS NotStarted → Recovering)。效果:Initialize 返回时状态必为 Recovering 或更晚, "恢复任务尚未启动"窗口从根上消灭;WaitGuardPreCheck 保留为防御性绊线(不变量验证)。


9. 落地映射(分批,一点一点来)

硬性要求:每阶段独立 commit + 全绿再进下一阶段;行为变更项(P2/P3)须带回归测试。

阶段 范围 改造 模式 状态
P0 新增 Primitives/AsyncOperation.cs + Execution/SyncAsyncBridge.cs + 契约测试(§10) 新基建 — ✅(另增 Run/Run&lt;T&gt; 便捷入口——Start+有界 Wait+失败重抛,同步包装改造的一行式形态)
P1 IO/Remote/ObjectStoreExtensions.cs 8 个同步包装(自 IObjectStore 接口文件迁出) 内部改走桥(静态共享 SyncBridgeOptions 免每调分配),对外签名与行为不变 桥接 ✅(Copy 族 60s 预算)
P2 RemoteFileHandle 同步族(Write/Read/PunchHole/CopyRange 快路径/Flush)+ RemoteFileSystem 同步族(Open/Exists/Delete/Move/Enumerate)+ fencing 三处(TryAcquireOrTakeover/Heartbeat/ReleaseLease) 逐调用桥接;FlushAsync 真异步化(lock→SemaphoreSlim 异步门、multipart 全 await——异步调用方不再被伪异步阻塞,此为超出原稿的必要改造:桥 work 契约禁止内部阻塞);fencing 锁不变量:桥完成者(对象层 IO)绝不触碰 _lockGate(Thread.Sleep(15) 重试退避保留——受调用方 deadline 有界) 桥接 + 状态句柄 ✅(Flush 600s / Copy 60s 预算;验证:Core 1209 + Runtime 501 + S3 契约 30 全绿)
P3 生命周期链:LifecycleBase.WaitForReady / priorTask.Wait()(WaitForReady/重试守卫)内部改 tiered 等待;IRecovery.MarkScheduled() + Initialize 状态同步置位(§7);EntryLog.WaitForCommitAsync 名义异步问题(WaitForCommitAsync)单独评审 状态可见性修法 状态句柄 ⏳ 待下一阶段(需 Contracts 变更,与 Runtime 接入同期)
不改 内存序屏障(SpinRWLock/epoch/freeze/段表);Dispose 终局 join(只补超时诊断);S3ObjectStore 凭据热点(走"消除"路线:凭据缓存) — 见 §8.4/8.5 —

交付备注:

  • 桥级指标(§6.4 bridge.* 系列)首版未实施——依赖 ObservabilityHub 接线,属后续增强; watchdog 慢任务告警(TaskTimeout=5s)已随默认池生效。

10. 测试与验收(契约测试矩阵)

硬性要求:测试与源 1:1(src/X/Y.cs ↔ tests/X/YTests.cs);并发原语必须有契约测试,禁止 SKIP。

tests/KernLab.Tier.Core.Tests/Primitives/AsyncOperationTests.cs

类别 用例要点
计数/状态语义 终态 CAS 单次生效;重复 Report 幂等 no-op;异常槽观察不重抛;ThrowIfFailed 三分支
唤醒协议 N waiter 广播全醒;完成先于等待零丢失;取消传播(等待中 ct 触发 → OCE);超时边界(deadline 前完成 → true)
配对绊线 Failed/Canceled 且无观察 → finalizer 告警(泄漏可见)

tests/KernLab.Tier.Core.Tests/Execution/SyncAsyncBridgeTests.cs

类别 用例要点
基本功能 成功/失败/取消三轨;Start 返回时 Status == Running(★ 可见性原则的机器验证)
再入防护 work 内嵌套 Start+Wait(同池)→ 必抛 InvalidOperationException;注入独立 Scheduler → 通过
池饿死回归 专项:打满公共池(N 个 Task.Run(() => block))后桥操作仍在超时内完成——独立池价值的验收测试
超时规范 全部同步等待有界;超时返回 false + WARN 现场含 op 名/年龄/状态
并发压测 M 线程 × K 操作并发 Start/Wait,无丢失唤醒、无状态机错乱(计数器校验)

性能基线(benchmarks/KernLab.Tier.Core.Benchmarks/,对齐既有基准文化): 桥派发税目标——完成即等(无 park)路径 ≤ 2µs(IsolatedTaskScheduler 派发 0.5-1µs + 句柄开销); WaitAsync 已完成快路径 ≤ 100ns。超基线回写 perf 文档。


11. 备选方案与否决理由

备选 否决理由
全部改 Task + WaitAsync,不做句柄 轮询(多消费者状态查询)与"Start 早、Wait 晚"的延迟等待模式无法用单消费者 Task 表达;且裸 Task 无状态机契约与诊断规范
裸 Thread.Yield() 循环替代 .Wait() 见 §5.1——无界、不保证完成者获 CPU、无超时;是"看起来异步友好"的反模式
桥等待用 Task.Wait(timeout)(等 Task 而非事件) 保留对公共池 continuation 的依赖(work 的 await 后续仍可能排公共池——除非 work 全程 ConfigureAwait(false) 且 IO 真异步);事件等待 + 独立池执行把依赖面收到最小
每调用方自建独立池 违反防扩散护栏;well-known 桥池 + 显式注入是受控中间态
状态机加 Pending 态 发起即受理(§7)后 Pending 不可观测——不可观测的状态是复杂度,砍