# 流程会话停止、故障与最终回收

目标设计与 API 草案，尚未实施。总体边界和推进状态见设计概述。

本文负责采集、队列、节点、观察、显示与 SDK 的结束屏障；取消不等于实际结束，任务完成不等于真实归还。

停止协议由会话/采集集成层执行，图像基建提供独立引用、访问协调和 ReturnCompleted；ImageDisplay 不负责停止相机或整个工具流。

Running
  → Quiescing：停止接受新工作，退出采集回调，保持归还泵可用
  → Draining / Cancelling：按策略消费或丢弃待处理项，等待正在运行的实际工作
  → Releasing：关闭输入/输出/缓存/预览/显示的自有引用
  → Returning：等待 SDK 归还回调与清理队列
  → Stopped：没有该会话拥有的在途工作或外借资源

可靠结束可选择排空队列；立即中止则取消节点并关闭未消费项。取消不是强制终止线程：正在运行的节点、native 调用和 pin 只有在实际访问结束后才能退出。SDK 若要求先归还全部帧才能 Stop/Close，应把其停止采集命令拆成“停止产生新帧”和“销毁池/设备”，按其协议安排，不能把上述逻辑顺序机械翻译为单次 SDK.Stop 调用。

# 结束条件与外部保留

会话记录导入成功的外借资源及归还终态，停止成功要同时满足：没有新回调、队列为空、节点工作已结束、会话拥有的图像及访问已关闭、SDK 归还已完成。关闭最后一个 buffer/image 后再等待归还，不能边持有最后引用边等自己的 ReturnCompleted。

显示和记录也是消费者。会话拥有它们时需排空并解除其图像引用；若宿主明确把图像导出给会话外的窗口/历史缓存，会话停止不再控制该引用。要立即销毁 SDK，应先把这些长期内容复制到独立存储并关闭原图；否则停止只能报告“仍有外部保留”，不能假称设备资源已归还。

# 超时与故障处置

停止等待可以有调用方超时，但底层安全清理继续运行。超时返回未排空/故障结果，并报告 BufferId、活动访问、pin、等待者、归还队列及持有时长；不能强行回收仍被 native 使用的地址。若节点违反契约遗失访问对象，任务返回也不能证明资源安全，故障需要显式处理而不是自动重用缓冲。

ReturnFailed、相机断线、节点异常、队列消费者退出和解码失败都要进入可观察故障路径。归还失败不自动再次 Release，也不把全部后续资源卡在同一未观察的异常后面；清理泵继续处理其他可归还项，最终停止结果汇总失败。仅当归还条件满足且设备协议允许时销毁 SDK 线程、池和设备上下文。