MiguDelay 架构 10：Gateway 与 TaskHandle 兼容边界

MiguDelay（DDLive）项目架构系列文档：Gateway 与 TaskHandle 兼容边界。内容基于 2026-08-04 对指定重构分支的源码扫描结果整理。

发表于 2026/08/05

作者 李正博

2 分钟阅读

系列导航：系列总览 · 上一篇：MiguDelay 架构 09：TaskOrchestrator 编排 · 下一篇：MiguDelay 架构 11：收流、探测、解复用与解码

扫描基线

项目：MiguDelay（DDLive）

分支：refactor/video-frame-provider

HEAD：d28ec061406e4e3df93e3d1a92478d71a9ad4908

工作树：clean

扫描日期：2026-08-04

说明：内容以当前 HEAD 源码为准；仓库旧架构文档只作为检索线索。

1. 分工

TaskHandleGateway：typed 请求、ticket/UUID 关联、callback gate、线程切换。
LegacyTaskHandleAdapter：typed struct 与 legacy TaskInfo 转换，接收快照和 Output 激活。
TaskHandle：任务队列、worker、context map 和具体 Task。
TaskOrchestrator：决定业务下一步。

2. 六类请求

start/stop receive、start/stop record、start/stop push。activateReceive() 不创建 worker task，而是把已就绪 context 接入 Runtime dependencies 和 Preview callback。

3. 提交调用链

sequenceDiagram
    participant O as TaskOrchestrator
    participant G as TaskHandleGateway
    participant A as LegacyTaskHandleAdapter
    participant T as TaskHandle
    participant W as Legacy Task Worker

    O->>G: typed request
    G->>G: allocate nonzero ticket and UUID
    G->>A: submit variant and UUID
    A->>A: build legacy TaskInfo
    A->>T: addTask ownership transfer
    T->>W: execute
    W-->>T: TaskResultInfo
    T-->>A: raw callback
    A-->>G: RawGatewayResult
    G-->>O: typed TaskGatewayResult

4. Pending 关联

pending operation 记录 UUID、ticket、expected TaskType、task generation、resourceId、lifecycle epoch 和首结果标记。未知 UUID、类型不匹配、wrong payload、duplicate 和 late result 在边缘过滤。

5. 线程安全

raw callback 可能来自 TaskHandle worker。Gateway 先用共享 IngressState 检查 accepting 和关联，再 queued 到 QObject 线程；deliverResult() 再检查 lifecycle epoch 后 emit。

6. Adapter 字段映射

Receive：address、contextId、generation、current-generation token、hardware decoder、long delay、only live。
Record：recordId、paths、encoder/muxer、尺寸、帧率、GOP、bitrate、音轨信息。
Push：contextId、encoder params、muxer init、音轨映射和协议。

7. ReceiveReadySnapshot

Adapter 从 NetworkRecvContext 按值复制视频分辨率、帧率、bit depth、codec、color、pixel format、全部音轨和 long-time-delay。领域层不持有 legacy context。

8. activateReceive

TaskOrchestrator
  -> TaskStartEffects.activateReceive
  -> TaskHandleGateway.activateReceive
  -> LegacyTaskHandleAdapter.activateReceive
       -> get NetworkRecvContext
       -> inject OutputRuntimeDependencies
       -> register current/delay/indelay/Aux callbacks
       -> adaptPreviewFrame
       -> IPreviewFrameSink

主输入才注入 mode/aux source 和延时回调；备路只绑定独立 preview。

9. context 幂等停止

TaskHandle 的 recv、record、push map 均由 mutex 保护。take*Context() 在同一临界区取出并删除，保证并发 stop 只有一个执行者拥有真实资源。

10. 源码证据

src/code/module/playback/gateway/taskhandlegateway.*
src/code/module/playback/gateway/legacytaskhandleadapter.*
src/code/module/playback/gateway/taskgatewaybackend.*
src/code/module/taskhandle/TaskHandle.*
src/code/module/taskhandle/TaskDef.*