桥接层实现与落地映射
分册导航: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<T> 便捷入口——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 不可观测——不可观测的状态是复杂度,砍 |