MiguDelay 架构 20：运行中流重配置

系列导航：系列总览 · 上一篇：MiguDelay 架构 19：监看音频 · 下一篇：MiguDelay 架构 21：主备绑定、心跳与业务复制

扫描基线

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

1. 当前 HEAD 的真实合同

当前 StreamReconfigurationService：

• 每个 target 有独立 operation generation。
• 同 target 新请求先 cancel 旧请求。
• 每 target 使用独立 std::mutex，旧 operation 未退出时新 operation 串行等待。
• 不同 target 可并行。
• worker 只使用 frozen request。
• completion 同时校验 task generation 与 operation generation。
• shutdown() cancel 全部并 waitForFinished() 全部 watcher。
• 不存在独立 cancelAndDrain() Port。

2. 对象分工

对象	职责
LegacyStreamReconfigurationBinding	监听配置/错误并冻结 request
StreamReconfigurationService	generation、cancel、watcher、currentness
operation port	worker 最小接口
StreamReconfigurationOperation	stop/start retry
session factory	创建 legacy receive session
cancellation source/token	唤醒重试等待

3. 请求链

sequenceDiagram
    participant B as Legacy Binding
    participant S as Reconfiguration Service
    participant M as Target Mutex
    participant W as QtConcurrent Worker
    participant O as Operation Port

    B->>S: requestReceive frozen values
    S->>S: cancel same target
    S->>S: allocate operation generation
    S->>W: schedule request and token
    W->>M: lock target mutex
    W->>W: verify cancellation
    W->>O: reconfigureReceive
    O-->>W: result
    W-->>S: watcher finished
    S->>S: verify task and operation generation
    S-->>B: operationFinished only if current

4. Receive operation

默认 stopMaxAttempts=3，startMaxAttempts=0 表示无限，retryInterval=5000ms。

flowchart TD
    V["Validate request and policy"] --> C["Create legacy session"]
    C --> STOP["stopOnce up to three attempts"]
    STOP --> OK{"Stopped"}
    OK -->|no| SE["StopExhausted"]
    OK -->|yes| PREP["prepareStart"]
    PREP --> START["startOnce"]
    START --> SUC{"Started"}
    SUC -->|yes| FIN["finish true and Succeeded"]
    SUC -->|no| WAIT["Cancellation aware wait"]
    WAIT --> START

所有取消出口调用 session.finish(false)。

5. 当前取消窗口

requestCurrentTaskRestart() 执行 cancelAll() 后立即调用 restartCurrent()；旧 worker 可能仍处于不可中断 legacy call。generation 会过滤结果，同 target mutex 会串行后继局部请求，但整体 restart 与旧 operation 的资源交叉仍需压力测试。

6. Delay 与 Push

Delay request 冻结 delay/inDelay 和当前 .venc/.dxt/.pcm 路径；同 DelayReaders target 串行。成功只表示 operation 完成，返回 Delay 还需匹配版本化 delayed video。

push 地址变化不走该 QtConcurrent operation，而调用 TaskOrchestrator::restartPush()。

7. Task state 与 shutdown

只有 Starting/Running 接受局部重配置。phase 失活或 generation 变化会 cancel in-flight token。shutdown 先关 gate、cancel all、wait watcher、清 in-flight，再由 Runtime 开始 task drain。

8. 源码证据

• src/code/module/playback/reconfiguration/streamreconfigurationservice.*
• src/code/module/playback/reconfiguration/streamreconfigurationoperation.*
• src/code/module/playback/reconfiguration/streamcancellation.*
• src/code/module/playback/reconfiguration/legacystreamreconfigurationbinding.*
• tests/stream_reconfiguration_service/*

---

系列导航：系列总览 · 上一篇：MiguDelay 架构 19：监看音频 · 下一篇：MiguDelay 架构 21：主备绑定、心跳与业务复制