MiguDelay 架构 08：TaskSession 状态机

系列导航：系列总览 · 上一篇：MiguDelay 架构 07：任务准入与公开垫片门 · 下一篇：MiguDelay 架构 09：TaskOrchestrator 编排

扫描基线

• 项目：MiguDelay（DDLive）
• 分支：refactor/video-frame-provider
• HEAD：d28ec061406e4e3df93e3d1a92478d71a9ad4908
• 工作树：clean
• 扫描日期：2026-08-04
• 说明：内容以当前 HEAD 源码为准；仓库旧架构文档只作为检索线索。

1. 定位

TaskSession 是无 QObject、无 I/O 的纯状态机，是任务 phase、identity、generation、restart intent 和 stop barrier 的唯一真值。

2. 状态机

stateDiagram-v2
    [*] --> Idle
    Idle --> Starting: start
    Starting --> Running: markRunning
    Starting --> Restarting: beginRestart
    Running --> Restarting: beginRestart
    Starting --> Stopping: beginStop
    Running --> Stopping: beginStop
    Restarting --> Stopping: explicitStop
    Failed --> Stopping: cleanup
    Stopping --> Idle: stopBarrierSuccess
    Stopping --> Failed: stopBarrierFailure
    Restarting --> Starting: restartBarrierSuccess
    Starting --> Failed: startFailure
    Running --> Failed: runtimeFailure

3. generation

• start() 从 Idle 分配非零 generation。
• beginRestart() 立即分配新 generation，使旧结果失效。
• 0 永远表示 invalid。
• generation 校验优先于 ticket/phase，旧结果不能消耗当前 barrier。

4. Stop Barrier

Barrier 保存具体 ticket 集，而非简单计数：

requiredTickets
completedTickets
failureSeen
submissionFailureSeen
purpose = Stop or Restart

flowchart TD
    B["Arm barrier with real tickets"] --> R["Receive async result"]
    R --> G{"Generation current"}
    G -->|no| STALE["Return stale"]
    G -->|yes| T{"Ticket required"}
    T -->|no| UNKNOWN["Unknown ticket"]
    T -->|yes| D{"Already completed"}
    D -->|yes| DUP["Duplicate"]
    D -->|no| ADD["Mark completed and aggregate failure"]
    ADD --> ALL{"All required tickets complete"}
    ALL -->|no| WAIT["Pending"]
    ALL -->|yes| END["Choose terminal state"]

5. 返回状态

• Applied
• Pending
• Completed
• Rejected
• Stale
• Duplicate
• UnknownTicket

Orchestrator 根据状态决定下一步，不能把所有 false 当成同一种失败。

6. 关键规则

• Failed 不能直接 start，必须先清理。
• Stopping 中重复 stop 不重装 barrier。
• ticket 0 不入 required set，由 submission failure 标记。
• restart barrier 成功后 pending identity 提升为 current。
• restart barrier 失败不启动 pending task。

7. 类调用

TaskOrchestrator
  -> TaskSession.start
  -> TaskSession.markRunning
  -> TaskSession.beginRestart
  -> TaskSession.beginStop
  -> TaskSession.armStopBarrier
  -> TaskSession.completeStop
  -> TaskSession.fail
  -> TaskSession.state

8. 源码证据

• src/code/module/playback/session/tasksession.*
• tests/task_session/task_session_test.cpp

---

系列导航：系列总览 · 上一篇：MiguDelay 架构 07：任务准入与公开垫片门 · 下一篇：MiguDelay 架构 09：TaskOrchestrator 编排