Table of Contents

AsyncOperation 契约与分层等待

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

4. AsyncOperation 契约(句柄层)

★ 通用后台操作原语(升级):AsyncOperation 从"同步桥专用"升级为全库后台操作句柄基座—— Storage 层 IReclaimOperation/ICompactOperation 两套同构句柄合一为 Contracts.IAsyncOperation / IAsyncOperation{TResult}(依赖方向:Contracts 定义接口、Core 实现;公开 API 返回接口, 运行时对象即 AsyncOperation 实例),Reclaim/Compact 后台操作统一 new AsyncOperation(...) + Report*, 不再手写 TCS/事件/时序包装。新增契约:事件(Progress/Failed + 成功钩子 OnSucceeded)、 取消(Cancel + CancellationToken,构造可链接外部取消——引擎 Dispose 自动取消在途操作)、 进度(ReportProgress)、结果(泛型变体 AsyncOperation{TResult})。 ★ 接口消费面 = 类消费面全集(补全):IAsyncOperation 含轮询 (Status/IsCompleted/Exception——AsyncOperationStatus 枚举位于 Contracts.Common)、 异步等(WaitAsync)、同步兜底等(Wait(int, ct))、终态取异常(ThrowIfFailed)——调用方只看接口, 无需查类 API。完成侧(Report*)不进接口(实现类成员)。

4.1 API

namespace KernLab.Tier.Core.Primitives;   // ★ 枚举 AsyncOperationStatus 在 KernLab.Tier.Contracts.Common

public enum AsyncOperationStatus
{
    Running,     // 已受理并在途(★ 发起线程返回前同步置位——可见性原则,见 §7)
    Succeeded,
    Failed,
    Canceled,
}

public abstract class AsyncOperationBase : IAsyncOperation   // 机制基座(事件/取消/进度/状态机)
{
    // === 状态查询(多消费者安全;全部 volatile / Interlocked 实现)===
    public AsyncOperationStatus Status { get; }
    public bool IsCompleted { get; }              // 终态短路(Succeeded/Failed/Canceled)
    public Exception? Exception { get; }          // Failed/Canceled 的异常(观察不重抛)

    // === 事件(后台操作通用契约)===
    public event EventHandler<double>? Progress;       // 进度(ReportProgress 触发,订阅者异常隔离)
    public event EventHandler<Exception>? Failed;     // 失败/取消终态(取消回滚完成 = Failed 语义)
    public void ReportProgress(double progress);

    // === 取消(后台操作通用契约)===
    public CancellationToken CancellationToken { get; }  // 操作取消令牌(worker 检查点响应)
    public void Cancel();                                // 触发取消(幂等;构造可链接外部取消)

    // === 完成侧(CAS 单次生效,后续 Report 为 no-op)===
    public virtual void ReportSucceeded();
    public void ReportFailed(Exception ex);
    public void ReportCanceled(OperationCanceledException oce);

    // === 消费侧:三种模式 ===
    // ① 异步等(一等公民——零分配,委托内嵌 AsyncManualResetEvent.WaitAsync)
    public ValueTask WaitAsync(CancellationToken ct = default);

    // ② 同步兜底等:分层等待(§5),全程有界
    //    完成(含失败)→ true / 抛失败异常;超时 → false;取消 → OCE
    public bool Wait(int timeoutMs, CancellationToken ct = default);

    // ③ 轮询方终态取异常(IsCompleted 后调;Failed/Canceled 重抛,Succeeded no-op)
    public void ThrowIfFailed();
}

// 无结果变体(原 AsyncOperation——API 全保留,SyncAsyncBridge 消费方零回归)
public sealed class AsyncOperation : AsyncOperationBase
{
    public AsyncOperation(string? name = null, ILogger? logger = null,
        CancellationToken externalCancellation = default);
}

// 有结果变体(仿 Task{T},如 CompactResult;实现 IAsyncOperation{TResult})
public sealed class AsyncOperation<TResult> : AsyncOperationBase
{
    public event EventHandler<TResult>? Completed;     // 成功事件(携带结果,先于 WaitAsync 唤醒)
    public void ReportSucceeded(TResult result);       // ★ 必须带结果(无参版 override 防御)
    public TResult Result { get; }                     // 终态后读(失败/取消重抛)
    public new ValueTask<TResult> WaitAsync(CancellationToken ct = default);   // 等完成拿结果
}

★ 事件时序契约:终态事件(Failed / 泛型 Completed) 在完成信号置位(AsyncManualResetEvent.Set)之前同步触发(订阅者异常隔离)——WaitAsync 等待者苏醒时事件必已投递;订阅竞态经 IsCompleted 兜底(先订阅后查,true = 完成早于订阅)。

★ 命名规范:Async 后缀只留给可 await 的方法(返回 Task/ValueTask); 启动后台操作并返回句柄的方法用 Start 动词(StartReclaim/StartCompact),等待走句柄的 WaitAsync。

4.2 状态机语义表

转移 执行者 时机 契约
→ Running 发起线程 句柄对外可见之前(同步) 可见性原则(§7):调用方拿到句柄时状态必为 Running,绝无"句柄已到手但状态未知"窗口
→ Succeeded/Failed/Canceled 完成侧(桥 worker / 手工) work 结束 CAS 单次:首个终态生效;后续 Report 幂等 no-op(防御重复完成)
终态 — — 不可逆。需要重试 = 新建操作,不改状态机(对齐 RecoveryBase"Failed 实例销毁重建"哲学)

4.3 实现要点

  • 内嵌一个 AsyncManualResetEvent(默认构造,Set 调用点不持锁 → 也可选内联模式)作完成信号; WaitAsync 直通 event.WaitAsync,Wait(timeout) 直通 event.Wait(timeout)——等待机制零新代码;
  • 状态用 int + Interlocked.CompareExchange(状态枚举压 int),Exception 槽 volatile 写;
  • 池化预留:对齐 PooledValueTaskSource 的归还协议设计,但首版用普通 sealed class(池化是 优化级改动,等基准证明需要再做——避免过早设计);
  • #if DEBUG:状态转移环形记录(最近 16 次:时间戳 + 线程 id + 转移方向 + 等待者计数), 超时 / 异常自动携带历史(对齐 SpinRWLock 值示波器)。

5. 分层等待策略(对"短周期自旋+让步"的修正)

5.1 为什么不是裸 Thread.Yield() 循环

提案原稿设想"必要时短周期自旋 + 让步(Thread.Yield)而不是直接 .Wait()"。方向对,形态要修正:

方案 问题
无界 while (!done) Thread.Yield(); ① 等待 >1ms 时纯烧 CPU(每次 Yield 一个完整调度周期);② Yield 不保证完成者获得 CPU——单核 / 超订 / 完成者需要池线程而池被同步等待者占满时,Yield 循环和 .Wait() 一样死锁,还多烧一个核;③ 无超时 = 无界楔死,违反有界规范
SpinWait.SpinOnce() 循环 ✅ 自带 CPU 自旋 → 自动升级 Yield → 偶发 Sleep(1) 的完整阶梯;NextSpinWillYield 给出明确的阶段切换点
park(Monitor.Wait 分片) ✅ 真正让出核;分片自醒兜底丢脉冲

结论:同步兜底等待 = SpinWait 自旋段(微秒级)→ park 分片(50ms 自醒 + 完成侧 Pulse)→ 全程超时上限。 这正是 AsyncManualResetEvent.Wait(int, CancellationToken)(Primitives/AsyncManualResetEvent.cs#Wait(int, CancellationToken)) 已实现并验收过的轨道——直接复用,不新写。

5.2 与 .Wait() / GetAwaiter().GetResult() 的本质区别

同步桥真正的死锁根源不是 Task.Wait() 这个调用形式,而是三个结构性条件(本设计逐一拆解):

死锁条件 本设计的拆法
(a) 等待者占公共池线程,完成者也需要公共池 → 池饿死互等 异步工作跑独立池(IsolatedTaskScheduler,continuation 回流私有线程),推进不依赖公共池(§6)
(b) UI/ASP.NET 同步上下文,continuation 要回流等待线程 等待者 park 在事件上(无 continuation);完成侧 Set 默认 runContinuationsAsynchronously: true,不内联
(c) 等待者持有完成者需要的锁 契约禁止(§8 硬性要求 3)+ 独立池让"锁的持有者"与"完成者"大概率不同线程池,冲突更早暴露为超时而非静默死锁

另有两点工程收益:事件等待不依赖 Task 调度器内部行为(无完成边缘内联续体的语义模糊); 多消费者可轮询(Task 是单消费者模型,IsCompleted 轮询 + 二次 Wait 会消耗结果)。