《VulkanSceneGraph 1.1.16 源码深度解析》第十四章 Viewer 与线程模型:RecordAndSubmitTask

0 阅读1小时+

《VulkanSceneGraph 1.1.16 源码深度解析》第十四章 Viewer 与线程模型:RecordAndSubmitTask 与 FrameBlock

14.0 先把规模和答案摆出来

第十三章收尾时留下六个问题:CompileResult 怎样分派到 recordAndSubmitTasks、编译期与帧期的 fence 等待由哪条屏障切断、两条屏障分别挡住谁、numCompileTraversals = 1 下还剩多少并行度、多线程记录时状态是否各线程独立、多窗口提交顺序如何收敛。

本章回答前五个问题的全部,以及第六个问题里落在 Viewer 侧的那一半。第六个问题中 Queue 的提交语义、Swapchain 的 image 获取细节、present 模式的代价按分工归第十五章「提交与呈现:Queue、SubmitCommands、Swapchain、Presentation」;Barrier/Latch/FrameBlock/DeleteQueue 作为通用同步原语的完整语义归第十六章;DatabasePager 的读线程与 PagedLOD 帧预算归第十九章。本章只在这些对象被 Viewer 直接调用的接口深度上停住,不向里展开。

先给可复核的规模。本章正面处理的源文件共 51 个、合计 10,021 行,其中 app/ 头 1,370 行、app/ 实现 5,288 行。下表逐行给出完整路径、wc -l 实测行数与本章角色;每一行都先用 os.path.isfile 校验过存在,行数在写作前再次用 wc -l 复核。

完整路径行数本章角色
include/vsg/app/Viewer.h174Viewer 公开接口、字段全集、updateViewer 声明
src/vsg/app/Viewer.cpp892构造、四段流水、compile、setupThreading/stopThreading、updateViewer
include/vsg/app/RecordAndSubmitTask.h83任务字段、RecordAndSubmitTasks、updateTasks 声明
src/vsg/app/RecordAndSubmitTask.cpp365submit/start/record/finish、索引与 fence、updateTasks
include/vsg/threading/FrameBlock.h79帧号信号量的 set/get/wake/wait_for_change
include/vsg/threading/ActivityStatus.h42原子活跃标志、set/active/cancel
include/vsg/threading/Barrier.h78arrive_and_wait/arrive_and_drop、相位释放
include/vsg/threading/Latch.h95倒数闩,Viewer 未用,第十六章边界对照
include/vsg/threading/atomics.h52exchange_if_lower/greater/multiply、compare_exchange
include/vsg/threading/Affinity.h45Affinity、setAffinity 声明,Viewer 未直接调用
include/vsg/threading/OperationThreads.h60共享队列的线程池,Viewer 未用,第十六章边界
include/vsg/threading/OperationQueue.h156UpdateOperations/CompileManager 依赖的线程安全队列
include/vsg/threading/DeleteQueue.h136延迟删除,第十六章边界
src/vsg/threading/Affinity.cpp154平台相关的 CPU 亲和性设置
src/vsg/threading/OperationThreads.cpp63线程池的启停实现
src/vsg/threading/DeleteQueue.cpp121延迟删除实现
include/vsg/app/CompileManager.h119CompileResult、ResourceScavenger、CompileManager 接口
src/vsg/app/CompileManager.cpp447requiresViewerUpdate、compile、compileTask、编译屏障
include/vsg/app/UpdateOperations.h66一次性/全帧两类更新队列声明
src/vsg/app/UpdateOperations.cpp71add/remove/run 的加锁与 swap
include/vsg/app/RecordTraversal.h191记录遍历的状态字段、RecordedCommandBuffers 前置声明
src/vsg/app/RecordTraversal.cpp704apply(View&)、apply(CommandGraph&)、addToBin
src/vsg/app/CompileTraversal.cpp479编译期遍历,context->transferTask 注入
include/vsg/app/CommandGraph.h68record/reset/getOrCreateRecordTraversal 声明
src/vsg/app/CommandGraph.cpp149帧期主命令缓冲录制、命令缓冲池复用
include/vsg/app/SecondaryCommandGraph.h62二级命令图声明
src/vsg/app/SecondaryCommandGraph.cpp177二级命令缓冲录制、ExecuteCommands 回调
include/vsg/app/RenderGraph.h90RenderGraph 字段与 resized 声明
src/vsg/app/RenderGraph.cpp230resize 检测、imageIndex 边界、vkDeviceWaitIdle
include/vsg/app/TransferTask.h124TransferMask、DataToCopy、transferData 声明
src/vsg/app/TransferTask.cpp880frameIndex 轮转、_transferData、staging 分配
include/vsg/app/Presentation.h33waitSemaphores/queue 字段
src/vsg/app/Presentation.cpp74VkPresentInfoKHR 装配、queue->present
include/vsg/app/Window.h188resize() 空实现、imageIndex、numFrames
src/vsg/app/Window.cpp482acquireNextImage、_indices 移位、事件轮询
include/vsg/app/WindowResizeHandler.h75resize 处理器声明
src/vsg/app/WindowResizeHandler.cpp211两条重建路径,第九章已展开
include/vsg/app/View.h97viewID、bins、viewDependentState
src/vsg/app/View.cpp127viewID 全局分配器、共享与释放
include/vsg/vk/Fence.h57hasDependencies、dependentSemaphores/dependentCommandBuffers
src/vsg/vk/Fence.cpp66wait、resetFenceAndDependencies
include/vsg/vk/CommandBuffer.h106CommandBuffer 字段、RecordedCommandBuffers 定义
src/vsg/vk/CommandBuffer.cpp133RecordedCommandBuffers 加锁实现
src/vsg/vk/Context.cpp599waitForCompletion 的 fence 重试循环
include/vsg/ui/FrameStamp.h42time/frameCount/simulationTime
include/vsg/commands/CopyAndReleaseBuffer.h55已废弃上传命令
include/vsg/commands/CopyAndReleaseImage.h71已废弃上传命令
src/vsg/commands/CopyAndReleaseBuffer.cpp83已废弃实现
src/vsg/commands/CopyAndReleaseImage.cpp185已废弃实现
src/vsg/io/DatabasePager.cpp792updateSceneGraph,第十九章边界
src/vsg/animation/AnimationManager.cpp93run(frameStamp),update 阶段末步

真正决定本章结论的是不到 600 行,按一帧的调用顺序分头落在下面四个窗口里:

  • 帧推进 Viewer::advanceToNextFrame() 每帧 FrameStamp::create() 造新对象并驱动 recordAndSubmitTasks:src/vsg/app/Viewer.cpp:155
  • 提交 RecordAndSubmitTask::submit() 先由 fence() 判依赖再转入 transferData():src/vsg/app/RecordAndSubmitTask.cpp:85
  • 帧门闩 FrameBlock::set() 在锁内写 _value 再 _cv.notify_all():include/vsg/threading/FrameBlock.h:36
  • 传输 TransferTask::transferData() 按 TRANSFER_BEFORE_RECORD_TRAVERSAL 分派:src/vsg/app/TransferTask.cpp:340

有一件事必须先说清,否则后面每一节都会被误导:主题清单里出现的若干名字在本版本里并不存在。全库 grep -rn 实测结果如下,写进任何结论之前都以此为准。

主题清单用词全库命中1.1.16 里的真实符号真实位置
_framesInFlight0_currentFrameIndex / _indices / _fencesinclude/vsg/app/RecordAndSubmitTask.h:72-74
earlyTransferTask / lateTransferTask0earlyDataTransferredSemaphore 等四个信号量 + _earlyDataToCopy/_lateDataToCopyinclude/vsg/app/RecordAndSubmitTask.h:46-50、include/vsg/app/TransferTask.h:107-108
_currentTransferIndex0DataToCopy::frameIndexinclude/vsg/app/TransferTask.h:93
startThread0setupThreading() + threads.emplace_back(...)include/vsg/app/Viewer.h:132、src/vsg/app/Viewer.cpp:598
waitForFrame0FrameBlock::wait_for_change() / wake()include/vsg/threading/FrameBlock.h:57/:51
advanceToNextFrame4同名方法include/vsg/app/Viewer.h:102、src/vsg/app/Viewer.cpp:155 等

这不是笔误清单,而是版本演进的痕迹:第十三章的预告沿用了更早版本的字段命名。本章凡涉及帧在飞、早/晚传输、线程启停,一律按右列的真实符号推导,不按左侧概念名臆造字段。

14.0.1 本章的问题清单

四段流水由谁拼装、Viewer 为何不写主循环(14.1、14.3);FrameStamp 三字段怎样生成、_firstFrame 与 simulationTime 怎样分叉(14.2);acquireNextFrame 的重试循环由什么退出、resize 被触发几次(14.2.3、14.2.4);FrameBlock 用指针相等还是帧号相等判定"新帧"、wake() 为何不改值(14.4);ActivityStatus::set 用 exchange 而非 store 是否多余(14.5);Barrier 计数 1 + numValidTasks 怎样凑齐、arrive_and_drop 是否耗尽计数(14.6);两种线程模型的判据为何一个恒假、多线程路径为何只做 early 传输(14.7);numBuffers = 3 与 _indices 移位怎样实现三帧在飞、传 0 会怎样(14.8);start/record/finish 三段各自把状态推进到哪一步(14.9);finish() 里四类信号量怎样装进 VkSubmitInfo(14.10);TransferTask 在任务链的哪两处被调用、TRANSFER_ALL 为何丢信号量(14.11);RecordAndSubmitTask::record 到 RecordTraversal 的调用链、RecordedCommandBuffers 到底是否线程安全(14.12);update() 四步顺序由谁保证、CompileResult::add 的 break 丢掉了什么(14.13);Viewer::compile 为何把 bin 补齐写两遍(14.14);多 task 的提交顺序与 present 等待靠什么收敛(14.15);threading/ 目录里哪些接口被 Viewer 真正用到(14.16)。

14.0.2 答案骨架

先把结论列在这里,后面逐条用源码展开,读者可以带着结论去核对。

#结论主要证据性质
1帧循环不在 Viewer 内,它是 advanceToNextFrame / update / recordAndSubmit / present 四个独立虚方法,由应用主循环按序调用;Viewer 只提供零件include/vsg/app/Viewer.h:102、:135、:137、:139设计取舍
2帧在飞的节流不靠任何 _framesInFlight 字段,而是 RecordAndSubmitTask::start() 对当前 fence 的 wait(UINT64_MAX) 与主线程 _submissionCompleted->arrive_and_wait() 双重阻塞src/vsg/app/RecordAndSubmitTask.cpp:129-140、src/vsg/app/Viewer.cpp:843设计取舍
3setupThreading 的"单 CommandGraph 简化路径"判据 size() == 1 && !task->transferTask 恒为假,因为构造函数无条件创建 transferTask;整段 run lambda 是死代码src/vsg/app/Viewer.cpp:626、src/vsg/app/RecordAndSubmitTask.cpp:38硬缺陷
4recordAndSubmit() 的 #if 1 恒真,使 #else 分支里"前三帧单线程以规避 helgrind 误报"的降级开关成为编译期死代码src/vsg/app/Viewer.cpp:833-840硬缺陷
5acquireNextFrame() 对 OUT_OF_DATE/SURFACE_LOST/SUBOPTIMAL 调用基类空实现 resize(),连 _extent2D 都不刷新就原地 while 重试,无重试上限、无超时、result 未复位src/vsg/app/Viewer.cpp:220-242、include/vsg/app/Window.h:59硬缺陷
6CompileResult::add() 用 break 而非 continue,遍历 cr.views 时遇到第一个空 binDetails 就跳出,后续 view 的 bin 需求被整批丢弃src/vsg/app/CompileManager.cpp:48-55硬缺陷
7TransferTask::_transferData() 在 staging 内存 map 失败时返回 VK_SUCCESS 吞掉错误;transferData(TRANSFER_ALL) 又用 late 结果覆盖 early 的 dataTransferredSemaphoresrc/vsg/app/TransferTask.cpp:487、:345-346硬缺陷
8RecordTraversal::apply(const View&) 把 viewID/viewDependentState 写进 CommandBuffer 后只恢复了 traversalMask,前两者未对称恢复,嵌套 View 会残留上一个 View 的值src/vsg/app/RecordTraversal.cpp:569-570、:663-668硬缺陷
9FrameBlock::active() 无判空;status->set(false) 与 _frameBlock->wake() 不在同一临界区,存在 lost-wakeup 窗口;Barrier 无超时、无复位 API,缺一个到达者即永久阻塞include/vsg/threading/FrameBlock.h:49、src/vsg/app/Viewer.cpp:783-784、include/vsg/threading/Barrier.h:35-47硬缺陷
10Presentation::waitSemaphores 注释声称取自 RecordAndSubmitTasks.signalSemaphores,默认 assign 路径却未赋值;多 task 串联钩子为空,顺序只靠 renderFinishedSemaphore 与 swapchaininclude/vsg/app/Presentation.h:27、src/vsg/app/Viewer.cpp:552-555设计取舍

这十条里,第 3、4、5、6、7、8、9 条是本章的硬缺陷,第 1、2、10 条是设计取舍;第 10 条同时带有注释与实现不符的接口边界性质。硬缺陷的完整展开——触发条件、后果、规避——集中在「陷阱表与批判性结论」与「数字表与源码索引」,正文各节只负责把源码摆到能判定它们的位置。

14.0.3 阅读路线

Viewer 字段与生命周期 → FrameStamp 与帧推进 → 四段流水的拼装 → FrameBlock/ActivityStatus/Barrier 三个同步原语 → setupThreading 两种线程模型 → RecordAndSubmitTask 的索引与 fence → submit/start/record/finish → finish() 的信号量装配 → TransferTask 在任务链的两个挂载点 → 记录调用链与 RecordedCommandBuffers → update() 的调度顺序 → Viewer::compile 全貌 → 多 task 与 present → threading/ 边界。

这个顺序正好是一条帧从「被推进」到「被呈现」的数据流:FrameStamp 由 advanceToNextFrame() 造出,被四个阶段共享,却不参与线程同步——同步靠 FrameBlock 的指针与 Barrier 的到达计数。


14.1 Viewer 的对象模型与生命周期

14.1.1 构造函数与默认字段

// src/vsg/app/Viewer.cpp:30-39
Viewer::Viewer() :
    updateOperations(UpdateOperations::create()),
    animationManager(AnimationManager::create()),
    status(vsg::ActivityStatus::create()),
    _firstFrame(true),
    _start_point(clock::now()),
    _frameStamp(FrameStamp::create(_start_point, 0, 0.0))
{
    CPU_INSTRUMENTATION_L1_NC(instrumentation, "Viewer constructor", COLOR_VIEWER);
}

逐字段看:构造只初始化六个成员——updateOperations、animationManager、status、_firstFrame、_start_point、_frameStamp。status 用 ActivityStatus::create() 无参构造,ActivityStatus 的默认实参是 active = true(include/vsg/threading/ActivityStatus.h:24-25),所以 Viewer 一出生就是「活跃」状态。_frameStamp 用 FrameStamp::create(_start_point, 0, 0.0) 造了一个帧号为 0、仿真时间为 0 的占位帧,字段定义见 include/vsg/ui/FrameStamp.h:28-35:time、frameCount、simulationTime。

14.1.2 析构与 deviceWaitIdle

// src/vsg/app/Viewer.cpp:41-73
Viewer::~Viewer()
{
    CPU_INSTRUMENTATION_L1_NC(instrumentation, "Viewer destructor", COLOR_VIEWER);

    stopThreading();

    // don't destroy viewer while devices are still active
    Viewer::deviceWaitIdle();
}

void Viewer::deviceWaitIdle() const
{
    CPU_INSTRUMENTATION_L1_NC(instrumentation, "Viewer deviceWaitIdle", COLOR_VIEWER);

    std::set<VkDevice> devices;
    for (auto& window : _windows)
    {
        if (window->getDevice()) devices.insert(*(window->getDevice()));
    }

    for (const auto& task : recordAndSubmitTasks)
    {
        for (auto& cg : task->commandGraphs)
        {
            devices.insert(*(cg->device));
        }
    }

    for (auto& device : devices)
    {
        vkDeviceWaitIdle(device);
    }
}

析构先 stopThreading() 停记录线程,再 deviceWaitIdle() 等设备空闲,最后才让成员析构释放 Vulkan 对象。顺序是必要的:记录线程还在 vkBeginCommandBuffer 时释放 CommandPool 会直接崩。deviceWaitIdle() 用 std::set<VkDevice> 去重,设备来源有两处——每个 window 的 getDevice() 与每个 task 的每条 commandGraph->device。注意第二处 devices.insert(*(cg->device)) 没有判空,若某条 CommandGraph 的 device 为空(纯 CPU 图或构造未完成的中间态),这里会解引用空 ref_ptr;window 那一路却有 if (window->getDevice()) 判空。两路判空不对称。

vkDeviceWaitIdle 是全设备停顿;Viewer::active() 每帧经 if (!active()) 间接触发它,一个 const 方法执行阻塞调用,从接口上看不出来。

14.1.3 active() / close() 与单向收缩

// src/vsg/app/Viewer.cpp:105-138
void Viewer::close()
{
    CPU_INSTRUMENTATION_L1_NC(instrumentation, "Viewer close", COLOR_VIEWER);

    _close = true;
    status->set(false);

    stopThreading();
}

bool Viewer::active() const
{
    CPU_INSTRUMENTATION_L1_NC(instrumentation, "Viewer active", COLOR_VIEWER);

    bool viewerIsActive = !_close;
    if (viewerIsActive)
    {
        for (auto window : _windows)
        {
            if (!window->valid()) viewerIsActive = false;
        }
    }

    if (!viewerIsActive)
    {
        // don't exit mainloop while any devices are still active
        deviceWaitIdle();
        return false;
    }
    else
    {
        return true;
    }
}

close() 同时改三个东西:_close = true、status->set(false)、stopThreading()。_close 是 bool(include/vsg/app/Viewer.h:154),status 是 atomic_bool(include/vsg/threading/ActivityStatus.h:38),两者表达的是同一件事却没有统一数据源,且都没有复位路径——close() 之后没有任何代码把 _close 置回 false 或 status->set(true)(setupThreading() 里 status->set(true) 是唯一复位点,:618)。所以 Viewer 是单向收缩的:关掉就不能再开。

14.1.4 字段全景与线程归属

把 include/vsg/app/Viewer.h:34-168 的字段按「谁读写」分组——addWindow()/removeWindow() 只动窗口容器,而 _frameBlock 与 _submissionCompleted 才是线程边界——就能直接看出本章的线程归属:

字段声明位置写入方读取方
updateOperationsinclude/vsg/app/Viewer.h:82应用线程(add 加锁)update() 主线程
animationManagerinclude/vsg/app/Viewer.h:91应用线程update() 主线程
compileManagerinclude/vsg/app/Viewer.h:94compile()、updateViewer()DatabasePager 线程
statusinclude/vsg/app/Viewer.h:129close()/setupThreading()/stopThreading()FrameBlock、CompileManager 队列
threadsinclude/vsg/app/Viewer.h:130setupThreading()stopThreading()
recordAndSubmitTasksinclude/vsg/app/Viewer.h:116assignRecordAndSubmitTaskAndPresentation()记录线程、主线程
presentationsinclude/vsg/app/Viewer.h:120同上present() 主线程
_frameBlockinclude/vsg/app/Viewer.h:166setupThreading()记录线程与主线程
_submissionCompletedinclude/vsg/app/Viewer.h:167setupThreading()记录线程与主线程
_frameStampinclude/vsg/app/Viewer.h:160advanceToNextFrame()update()、recordAndSubmit()

_frameStamp 是唯一一个「应用线程写、记录线程只读」的 ref_ptr:主线程在 :181/:191 整体替换它,记录线程通过 FrameBlock::set(_frameStamp) 拿到同一份 ref_ptr 副本(FrameBlock.h:36-41 在锁内赋值),引用计数保证帧对象在记录期间存活。recordAndSubmitTasks 则相反——它在 assignRecordAndSubmitTaskAndPresentation() 里被整体 clear() 重建(:439-440),而记录线程正在遍历它;因此该函数开头必须先 stopThreading()(:425-426)。这条「重建前停线程」的约束是本章最重要的部署前提,第十四章 14.7.5 会再回到它。

与前面章节交叉引用:三个管理器在第五章只是被 Data::dirty() 驱动的对象,本章才挂进帧循环;status 与第十二章的 CompileManager 队列共用同一实例,close() 一次置假会同时停掉两类后台线程。


14.2 帧的推进:FrameStamp、advanceToNextFrame 与 acquireNextFrame

14.2.1 FrameStamp 的三个字段

frameCount 与 simulationTime 都由带参构造函数初始化,time_point time 才是默认构造的 {}:

// include/vsg/ui/FrameStamp.h:21-39
class VSG_DECLSPEC FrameStamp : public Inherit<Object, FrameStamp>
{
public:
    FrameStamp() {}

    FrameStamp(const FrameStamp& rhs, const CopyOp& copyop = {});

    FrameStamp(time_point in_time, uint64_t in_frameCount, double in_simulationTime) :
        time(in_time),
        frameCount(in_frameCount),
        simulationTime(in_simulationTime) {}

    time_point time = {};
    uint64_t frameCount = 0;
    double simulationTime = 0.0;

    void read(Input& input) override;
    void write(Output& output) const override;
};

FrameStamp 定义在 include/vsg/ui/FrameStamp.h 而非 app/,这是实测路径,不能按类名猜目录。它只有三个数据字段:time(clock::time_point)、frameCount(uint64_t)、simulationTime(double)。没有互斥锁、没有原子量、没有「任务 ID」,它纯粹是一个不可变快照。Viewer 每帧 FrameStamp::create(...) 造一个新对象(src/vsg/app/Viewer.cpp:181/:191),从不在原对象上改字段——这正是 FrameBlock 能用 ref_ptr 指针相等判定「新帧」的前提,14.4.1 会展开这个推理。

14.2.2 advanceToNextFrame 的逐分支推导

// src/vsg/app/Viewer.cpp:155-206
bool Viewer::advanceToNextFrame(double simulationTime)
{
    static constexpr SourceLocation s_frame_source_location{"Viewer advanceToNextFrame", VsgFunctionName, __FILE__, __LINE__, COLOR_VIEWER, 1};

    // signal to instrumentation the end of the previous frame
    if (instrumentation && _frameStamp) instrumentation->leaveFrame(&s_frame_source_location, frameReference, *_frameStamp);

    if (!active())
    {
        return false;
    }

    // poll all the windows for events.
    pollEvents(true);

    if (!acquireNextFrame()) return false;

    // create FrameStamp for frame
    auto time = vsg::clock::now();
    if (_firstFrame)
    {
        _firstFrame = false;

        if (simulationTime == UseTimeSinceStartPoint) simulationTime = 0.0;

        // first frame, initialize to frame count and indices to 0
        _frameStamp = FrameStamp::create(time, 0, simulationTime);
    }
    else
    {
        // after first frame so increment frame count and indices
        if (simulationTime == UseTimeSinceStartPoint)
        {
            simulationTime = std::chrono::duration<double, std::chrono::seconds::period>(time - _start_point).count();
        }

        _frameStamp = FrameStamp::create(time, _frameStamp->frameCount + 1, simulationTime);
    }

    // signal to instrumentation the start of frame
    if (instrumentation) instrumentation->enterFrame(&s_frame_source_location, frameReference, *_frameStamp);

    for (auto& task : recordAndSubmitTasks)
    {
        task->advance();
    }

    // create an event for the new frame.
    _events.emplace_back(new FrameEvent(_frameStamp));

    return true;
}

逐分支拆:

  • :160 用旧 _frameStamp 调 leaveFrame,条件是 instrumentation && _frameStamp。

代价与边界:advanceToNextFrame 把「检查活跃、轮询事件、获取 image、造帧号、推进任务槽位、发帧事件」六件事塞进一个方法。

14.2.3 acquireNextFrame 的重试循环(硬缺陷 H5)

// src/vsg/app/Viewer.cpp:208-246
bool Viewer::acquireNextFrame()
{
    CPU_INSTRUMENTATION_L1_NC(instrumentation, "Viewer acquireNextFrame", COLOR_VIEWER);

    if (_close) return false;

    VkResult result = VK_SUCCESS;

    for (auto& window : _windows)
    {
        if (!window->visible()) continue;

        while ((result = window->acquireNextImage()) != VK_SUCCESS)
        {
            if (result == VK_ERROR_SURFACE_LOST_KHR ||
                result == VK_ERROR_OUT_OF_DATE_KHR ||
                result == VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT ||
                result == VK_SUBOPTIMAL_KHR)
            {
                // force a rebuild of the Swapchain by calling Window::resize();
                window->resize();
            }
            else if (result == VK_ERROR_DEVICE_LOST)
            {
                // a lost device can only be recovered by opening a new VkDevice, and success is not guaranteed.
                // not currently implemented, so exit main loop.
                warn("window->acquireNextImage() VkResult = VK_ERROR_DEVICE_LOST. Device loss can indicate invalid Vulkan API usage or driver/hardware issues.");
                break;
            }
            else
            {
                warn("window->acquireNextImage() VkResult = ", result);
                break;
            }
        }
    }

    return result == VK_SUCCESS;
}

逐分支推导触发条件与后果:

  • result 在整个函数里是单个变量,跨所有 window 复用。若某窗口 !visible() 被 continue 跳过,result 保留上一次的值;若所有窗口都不可见,result 保持初始 VK_SUCCESS,函数返回 true——没有 image 被获取,但帧照常推进。这是一个隐含的静默降级。
  • while 的四个「可恢复」分支(:222-229)调用 window->resize() 后不 break、不重置 result、不计数,直接回到 while 条件再取一次 image。触发条件:Window::acquireNextImage 在 src/vsg/app/Window.cpp:445 检查 _swapchain->getExtent() != _extent2D 就返回 VK_ERROR_OUT_OF_DATE_KHR。而 Window::resize() 在基类是空实现——
// include/vsg/app/Window.h:59
virtual void resize() {}

平台子类(Win32/Xcb 等)才真正重建 swapchain。若子类实现没能同步 _extent2D,或 resize 事件尚在队列里没被处理,acquireNextImage() 会再次返回 OUT_OF_DATE,循环原地打转,主线程永久卡死,且没有日志、没有超时、没有重试上限。

14.2.4 resize 的第二个触发点与第九章的接合

Viewer 循环里 resize 有两个彼此独立的触发点。第一个是上面的 acquireNextFrame()(:228),由 swapchain extent 不一致驱动;第二个在帧期记录内部:

// src/vsg/app/RenderGraph.cpp:105-118
void RenderGraph::accept(RecordTraversal& recordTraversal) const
{
    GPU_INSTRUMENTATION_L1_NC(recordTraversal.instrumentation, *recordTraversal.getCommandBuffer(), "RenderGraph", COLOR_RECORD_L1);

    auto extent = getExtent();
    if (previous_extent.width == invalid_dimension || previous_extent.height == invalid_dimension || !windowResizeHandler)
    {
        previous_extent = extent;
    }
    else if (previous_extent.width != extent.width || previous_extent.height != extent.height)
    {
        auto this_renderGraph = const_cast<RenderGraph*>(this);
        this_renderGraph->resized();
    }

RenderGraph::accept() 在记录遍历里比对 previous_extent 与当前 getExtent(),不一致就 const_cast 去掉 const 调 resized()。

14.2.5 首帧 simulationTime 与哨兵值

UseTimeSinceStartPoint 定义为 std::numeric_limits<double>::max()(include/vsg/app/Viewer.h:97),用作 advanceToNextFrame(double) 的默认实参(:102)。

14.3 四段流水:update / recordAndSubmit / present 的调用时序

14.3.1 四个虚方法与主循环的拼装

// include/vsg/app/Viewer.h:99-142
        /// Convenience method for advancing to the next frame.
        /// Check active status, return false if viewer no longer active.
        /// If still active, poll for pending events and place them in the Events list and advance to the next frame, generate updated FrameStamp to signify the advancement to a new frame and return true.
        virtual bool advanceToNextFrame(double simulationTime = UseTimeSinceStartPoint);

        /// pass the Events into any registered EventHandlers
        virtual void handleEvents();

        virtual CompileResult compile(ref_ptr<ResourceHints> hints = {});

        virtual bool acquireNextFrame();

        /// call vkWaitForFence on the fences associated with previous frames RecordAndSubmitTask, a relativeFrameIndex of 1 is the previous frame, 2 is two frames ago.
        /// timeout is in nanoseconds.
        virtual VkResult waitForFences(size_t relativeFrameIndex, uint64_t timeout);
...
        virtual void update();

        virtual void recordAndSubmit();

        virtual void present();

        /// Call vkDeviceWaitIdle on all the devices associated with this Viewer
        virtual void deviceWaitIdle() const;

逐字段看,这七个方法全是 virtual,全部返回 void 或状态值,没有一个是「跑一帧」的总入口。Viewer 刻意不实现主循环:应用侧的典型拼装是 while (viewer->advanceToNextFrame()) { viewer->handleEvents(); viewer->update(); viewer->recordAndSubmit(); viewer->present(); }。这个顺序不是被某个基类强制的,而是四个方法之间的数据依赖决定的——update() 读写 _frameStamp 指向的场景图,recordAndSubmit() 把同一 _frameStamp 交给记录线程,present() 读取本帧的 imageIndex。四个方法都可被子类覆写,覆写后若打乱顺序,FrameBlock::set() 拿到的 FrameStamp 与 present() 用的 imageIndex 就不再属于同一帧。

与前面章节交叉引用:第三章「Visitor 体系」里 vsg_event->accept(*handler) 的分发机制正是 handleEvents() 的落点;第十三章帧期 RecordTraversal::apply(View&) 读到的 frameStamp 就是这里 advanceToNextFrame() 造出的对象经 recordAndSubmit() 传下来的,两者同源。

14.3.2 update() 的四步顺序

// src/vsg/app/Viewer.cpp:793-818
void Viewer::update()
{
    CPU_INSTRUMENTATION_L1_NC(instrumentation, "Viewer update", COLOR_UPDATE);

    CompileResult cr;

    // merge any updates from the DatabasePager
    for (const auto& task : recordAndSubmitTasks)
    {
        if (task->databasePager)
        {
            task->databasePager->updateSceneGraph(_frameStamp, cr);
        }
    }

    if (cr.requiresViewerUpdate(this))
    {
        updateViewer(*this, cr);
    }

    // run update operations
    updateOperations->run();

    // run aniamtions
    animationManager->run(_frameStamp);
}

四步严格按源码顺序:updateSceneGraph(合并分页加载结果,写 CompileResult cr)→ requiresViewerUpdate(this) 判定后 updateViewer → updateOperations->run() → animationManager->run(_frameStamp)。第十三章预告问「UpdateOperations::run 与 animationManager 在 update() 里的先后顺序由谁保证」,答案就落在这四行:既不是队列优先级,也不是依赖图,而是 Viewer::update() 里两条先后写死的语句。谁先谁后完全由源码字面顺序决定,没有任何数据结构在维护这个约束;任何人重排这两行都不会触发编译错误或断言。

14.3.3 recordAndSubmit() 的 reset 与两条分支

// src/vsg/app/Viewer.cpp:820-852
void Viewer::recordAndSubmit()
{
    CPU_INSTRUMENTATION_L1_NC(instrumentation, "Viewer recordAndSubmitTask", COLOR_VIEWER);

    // reset connected ExecuteCommands
    for (const auto& recordAndSubmitTask : recordAndSubmitTasks)
    {
        for (auto& commandGraph : recordAndSubmitTask->commandGraphs)
        {
            commandGraph->reset();
        }
    }

#if 1
    if (_threading)
#else
    // The following is a workaround for an odd "Possible data race during write of size 1" warning that valgrind tool=helgrind reports
    // on the first call to vkBeginCommandBuffer despite them being done on independent command buffers.  This could well be a driver bug or a false positive.
    // If you want to quieten this warning then change the #if above to #if 0 as rendering the first three frames single threaded avoids the warning.
    if (_threading && _frameStamp->frameCount > 2)
#endif
    {
        _frameBlock->set(_frameStamp);
        _submissionCompleted->arrive_and_wait();
    }
    else
    {
        for (auto& recordAndSubmitTask : recordAndSubmitTasks)
        {
            recordAndSubmitTask->submit(_frameStamp);
        }
    }
}

逐分支:

  • :824-831 主线程先对所有 commandGraph 调 reset();主图的 CommandGraph::reset() 为空,只有 SecondaryCommandGraph::reset() 清理 ExecuteCommands。

代价与边界:两条分支把同一份 _frameStamp 交给两条完全不同的执行路径,但 RecordAndSubmitTask::submit() 本身不区分调用线程——它内部所有字段(_currentFrameIndex、_fences、transferTask)都是无锁普通成员。

14.3.4 #if 1 死代码(硬缺陷 H4)

上一段摘录的 :833-840 是本章第二处编译期写死的降级开关。#if 1 恒真,预处理器直接丢弃 #else 到 #endif 之间的三行注释与 if (_threading && _frameStamp->frameCount > 2)。注释写得很清楚:这是为规避 valgrind helgrind 对首帧 vkBeginCommandBuffer 的「Possible data race during write of size 1」误报,改 #if 0 可让前三帧单线程运行以压掉告警。

触发条件:任何想启用该降级的人必须改源码重编译,运行期无法切换。后果:一是死代码长期留在主干,读者会误以为存在「前三帧单线程」的行为;二是它记录了一个真实存在的首帧并发告警却把它永久封存。

14.3.5 present() 与四段流水的收口

// src/vsg/app/Viewer.cpp:854-862
void Viewer::present()
{
    CPU_INSTRUMENTATION_L1_NC(instrumentation, "Viewer present", COLOR_VIEWER);

    for (auto& presentation : presentations)
    {
        presentation->present();
    }
}

present() 只做一件事:按 presentations 的 vector 顺序逐个 present()。

代价与边界:present() 不等待任何 fence。GPU 侧的完成由 swapchain 的 imageAvailableSemaphore / renderFinishedSemaphore 与 vkQueuePresentKHR 自身顺序保证;CPU 侧下一帧的 acquireNextFrame() 会被 swapchain 阻塞。所以「帧在飞」的上限其实由 swapchain image 数量与 RecordAndSubmitTask 的 numBuffers = 3 共同决定,这两者不相等时以较小者为准,代码里没有任何一致性检查。

与前面章节交叉引用:第十三章预告里 window->imageIndex() 的边界检查(src/vsg/app/RenderGraph.cpp:130-131、src/vsg/app/Presentation.cpp:32-33)在这里才被真正消费;第九章「管线对象」展开的 WindowResizeHandler::release(viewID) 在 resize 时与 present() 的 imageIndex 复用同一批窗口帧槽,二者共用 Window::_indices(src/vsg/app/Window.cpp:456-460)。


14.4 FrameBlock:帧在飞的信号量

14.4.1 initial_value 与「指针相等即新帧」

// include/vsg/threading/FrameBlock.h:23-47
    /// FrameBlock provides a mechanism for synchronizing threads that are waiting on the start of a new frame.
    class FrameBlock : public Inherit<Object, FrameBlock>
    {
    public:
        inline static const ref_ptr<FrameStamp> initial_value = {};

        explicit FrameBlock(ref_ptr<ActivityStatus> status) :
            _value(initial_value),
            _status(status) {}

        FrameBlock(const FrameBlock&) = delete;
        FrameBlock& operator=(const FrameBlock&) = delete;

        void set(ref_ptr<FrameStamp> frameStamp)
        {
            std::scoped_lock lock(_mutex);
            _value = frameStamp;
            _cv.notify_all();
        }

        ref_ptr<FrameStamp> get()
        {
            std::scoped_lock lock(_mutex);
            return _value;
        }

        bool active() const { return _status->active(); }

initial_value 是 inline static const ref_ptr<FrameStamp>,值为空;构造时 _value(initial_value),所以所有等待线程的起点都是「空帧」。逐字段:_mutex、_cv、_value、_status(:72-75)。set() 在锁内整体替换 _value 并 notify_all();get() 在锁内返回 _value 的 ref_ptr 副本。

关键推理:FrameBlock 判定「帧是否变化」用的是 ref_ptr<FrameStamp> 的指针相等(:60 的 _value == value),不是 frameCount 比较。这能成立,唯一原因是 Viewer::advanceToNextFrame() 每帧 FrameStamp::create(...) 造一个全新对象(src/vsg/app/Viewer.cpp:181/:191),从不复用。若某个调用方图省事复用同一个 FrameStamp 对象、只改它的 frameCount,_value == value 恒真,wait_for_change() 会一直卡在 cv.wait(),帧直接停摆。FrameBlock 的接口没有把这条前提写成注释或断言,正确性完全依赖 Viewer 侧的构造方式——这是典型的跨模块隐式契约,与第十三章批判的「reverse-Z 契约分散在六处常量」是同一类问题。

14.4.2 set / wake / active 的三种唤醒

// include/vsg/threading/FrameBlock.h:49-56
        bool active() const { return _status->active(); }

        void wake()
        {
            std::scoped_lock lock(_mutex);
            _cv.notify_all();
        }

三种唤醒路径要分清:set() 改 _value 并 notify_all(),是「有新帧」;wake() 只 notify_all() 不改 _value,是「请重新检查状态」;active() 只是 _status->active() 的转发,不唤醒。stopThreading() 用的是 wake()(src/vsg/app/Viewer.cpp:784),因为退出时不需要造新帧,只需要让阻塞在 cv.wait() 的线程醒来读一次 status。

active() 本身有两处可疑:一是 _status->active() 没有判空,若用 FrameBlock::create(nullptr) 构造会崩;二是它虽然是 public,Viewer 侧却零调用——wait_for_change() 内部直接用 _status->active()(:60/。

14.4.3 wait_for_change 的 while 条件

// include/vsg/threading/FrameBlock.h:57-67
        bool wait_for_change(ref_ptr<FrameStamp>& value)
        {
            std::unique_lock lock(_mutex);
            while (_value == value && _status->active())
            {
                _cv.wait(lock);
            }

            value = _value;
            return _status->active();
        }

参数 value 是引用,既是输入也是输出:进入时它是线程本地保存的「上一次见到的帧」,循环里与 _value 比较;退出循环后 :65 把 _value 赋给它,供下一轮比较。四个 lambda 都写成 auto frameStamp = ...->initial_value; while (...->wait_for_change(frameStamp)) {...}(src/vsg/app/Viewer.cpp:633-636、:683-686、:714-717、:733-736),正是靠这个引用就地更新。

逐分支:while (_value == value && _status->active()) 两个条件都要成立才 cv.wait。若 _value 变了(新帧),循环退出,返回 _status->active() 为真,线程去记录/提交;若 _status 变假(关闭),循环也退出,但返回 _status->active() 为假,线程退出 while 生命周期结束。cv.wait(lock) 没有谓词重载、没有超时,靠 set()/wake() 的 notify_all() 唤醒后重新判条件。

14.4.4 lost-wakeup 窗口(硬缺陷 H9 的前半)

// src/vsg/app/Viewer.cpp:781-790
    // release the blocks to enable threads to exit cleanly
    // need to manually wake up the threads waiting on this frameBlock so they check the status value and exit cleanly.
    status->set(false);
    _frameBlock->wake();

    for (auto& thread : threads)
    {
        if (thread.joinable()) thread.join();
    }
    threads.clear();

ActivityStatus::set(false)(include/vsg/threading/ActivityStatus.h:27)只改一个 atomic_bool,不持有 FrameBlock::_mutex;_frameBlock->wake() 才在 _mutex 内 notify_all()。两行是两次独立的临界区操作,中间存在窗口:若某记录线程恰好在 status->set(false) 之后、wake() 之前执行到 _cv.wait(lock),它已经释放 _mutex 并进入等待,而 wake() 的 notify_all() 尚未发出——注意 wake() 需要先拿到 _mutex,cv.wait 会释放它,所以 wake() 能拿到锁并通知,理论上不会丢。但真正的窗口在另一侧:某线程在 wait_for_change 里刚判完 while 条件(此时 status 仍为真、_value == value 成立)正准备进入 cv.wait,status->set(false) 先发生,wake() 随后 notify_all()——若该线程尚未真正挂起到 _cv 上,这次通知就丢失,而 while 条件的第二次判定要等下一次通知才会发生,线程永久阻塞,thread.join()(:788)随之永久等待。

规避方式是把状态翻转与通知放进同一临界区:让 FrameBlock 提供 shutdown(),在 _mutex 内同时置 _status->set(false) 并 notify_all();或让 wait_for_change 用带谓词的 _cv.wait(lock, [&]{ return _value != value || _status->cancel(); }),把状态检查交给条件变量的谓词重查。当前实现把「状态」与「通知」拆在两个对象(ActivityStatus 与 FrameBlock),是 lost-wakeup 的根源。


14.5 ActivityStatus 与 status 的传播

14.5.1 atomic_bool、exchange 与 cancel 的调用分布

// include/vsg/threading/ActivityStatus.h:20-39
    /// ActivityStatus provides atomic management of whether threads watching this ActivityStatus object should be active or safely exit
    class ActivityStatus : public Inherit<Object, ActivityStatus>
    {
    public:
        explicit ActivityStatus(bool active = true) :
            _active(active) {}

        void set(bool flag) noexcept { _active.exchange(flag); }

        /// return true if the caller should continue with current activity or false if they should be canceled
        bool active() const noexcept { return _active; }

        /// return true if the caller should cancel current activity
        bool cancel() const noexcept { return !_active; }

    protected:
        ~ActivityStatus() override {}

        std::atomic_bool _active;

逐字段:_active 是 std::atomic_bool;set() 用 exchange(flag),active() 隐式转换返回,cancel() 取反。set() 用 exchange 而非 store 是一个可观察的取舍:exchange 返回旧值但被丢弃,语义上等价于 store,却是一次读-改-写原子操作,在 x86 上会生成带 lock 前缀的指令,比纯 store 重。status->set() 只在启停线程时调用(:618/:783/:110),不在热路径,代价可忽略,但没有理由不用 store。

cancel() 的分布实测:grep -rn "cancel()" include/ src/ 命中 include/vsg/threading/OperationQueue.h:124 与 src/vsg/io/DatabasePager.cpp:412 两处调用。也就是说 Viewer 与 FrameBlock 侧一律用 active(),OperationQueue 与 DatabasePager 侧一律用 cancel(),同一个 42 行的类提供了两个互补查询,被两个模块群各用一半,没有任何一处同时用。这是接口冗余而非缺陷。

14.5.2 status 从 Viewer 到两个消费者的传播

status 在 include/vsg/app/Viewer.h:129 是 public 的 ref_ptr<ActivityStatus>,构造时创建(src/vsg/app/Viewer.cpp:33),随后被传给两处:

// src/vsg/app/Viewer.cpp:618-621
    status->set(true);
    _threading = true;
    _frameBlock = FrameBlock::create(status);
    _submissionCompleted = Barrier::create(1 + numValidTasks);
// src/vsg/app/CompileManager.cpp:130-137
CompileManager::CompileManager(Viewer& viewer, ref_ptr<ResourceHints> hints)
{
    compileTraversals = CompileTraversals::create(viewer.status);
    ...
    auto ct = CompileTraversal::create(viewer, requirements);
    compileTraversals->add(ct);

第一处把 status 交给 FrameBlock,第二处(第十二章 12.7)把同一个 status 交给 CompileManager::CompileTraversals 队列。于是 close() 里一次 status->set(false)(src/vsg/app/Viewer.cpp:110)会同时让记录线程的 wait_for_change() 退出、并让 CompileTraversals::take_when_available() 在队列为空时返回空指针。

这个共享是设计取舍:一个开关关停两类后台线程;代价是 assignInstrumentation() 临时停线程时,status->set(false) 会顺带让编译队列也停,setupThreading() 再统一复活。

代价与边界:status 是 public 字段,任何应用代码都能 viewer->status->set(false) 绕过 close() 直接停线程,此时 _close 仍为 false、_threading 仍为 true,recordAndSubmit() 仍会走 _frameBlock->set() 分支,而记录线程已全部退出,_submissionCompleted->arrive_and_wait() 永远等不到足够的到达者——这正是 14.6.3 要讲的死锁。字段可见性与状态机完整性在这里是冲突的。


14.6 Barrier 与 _submissionCompleted

14.6.1 arrive_and_wait / arrive_and_drop 的实现

// include/vsg/threading/Barrier.h:34-67
        /// increment the arrived count and release the barrier if count matches number of threads to arrive otherwise wait for the arrived count to match the number of threads to arrive
        void arrive_and_wait()
        {
            std::unique_lock lock(_mutex);
            if (++_num_arrived == _num_threads)
            {
                _release();
            }
            else
            {
                auto my_phase = _phase;
                _cv.wait(lock, [this, my_phase]() { return this->_phase != my_phase; });
            }
        }

        /// increment the arrived count and release the barrier if count matches number of threads to arrive, return immediately without waiting for release condition
        void arrive_and_drop()
        {
            std::unique_lock lock(_mutex);
            if (++_num_arrived == _num_threads)
            {
                _release();
            }
        }
...
        void _release()
        {
            _num_arrived = 0;
            ++_phase;
            _cv.notify_all();
        }

        const uint32_t _num_threads;
        uint32_t _num_arrived;
        uint32_t _phase;

逐字段:_num_threads 是 const(构造后不可变),_num_arrived 是到达计数,_phase 是相位。arrive_and_wait() 递增计数,未凑齐就在 _cv.wait 上等 _phase 变化;最后一个到达者调 _release() 把 _num_arrived 归零、_phase 加一、notify_all() 放行全部等待者。arrive_and_drop() 与前者只差「不等放行」——它递增计数、凑齐时同样 _release(),否则直接返回。

一个容易误读的点:arrive_and_drop() 不会减少 _num_threads,它每次调用都让 _num_arrived 加一,凑齐即归零。因此不存在「drop 久了把屏障计数耗尽」的问题。实测 grep -rn "arrive_and_drop\|arrive_and_wait" include/ src/:arrive_and_drop 全库仅 src/vsg/app/Viewer.cpp:642 一处调用,而 arrive_and_wait 有 :693、:699、:706、:721、:725、:740、:752、:843 八处。那唯一一处 arrive_and_drop 正是 14.7.2 要论证的死分支里的 run lambda——换言之,这个 API 在 Viewer 的活跃路径里零调用。

14.6.2 计数 1 + numValidTasks 怎样凑齐

// src/vsg/app/Viewer.cpp:602-621
    // check how many valid tasks there are.
    uint32_t numValidTasks = 0;
    for (const auto& task : recordAndSubmitTasks)
    {
        if (!task->commandGraphs.empty())
        {
            ++numValidTasks;
        }
    }

    // check if there is any point in setting up threading
    if (numValidTasks == 0)
    {
        return;
    }

    status->set(true);
    _threading = true;
    _frameBlock = FrameBlock::create(status);
    _submissionCompleted = Barrier::create(1 + numValidTasks);

numValidTasks 只统计 commandGraphs 非空的 task;屏障计数 1 + numValidTasks 里「1」是主线程 :843 的到达,每个 task 由 arrive_and_drop() 或 run_primary 贡献一个。

代价与边界:计数是构造时一次性算出的常量,_num_threads 为 const。若运行期某个 task 的 commandGraphs 被清空、或某条记录线程提前退出,屏障仍按旧计数等待,缺一个到达者就永久阻塞。这与 numValidTasks 的定义(:604-610 只在 setupThreading 时刻统计)耦合,没有任何运行期重算。

14.6.3 无超时、无复位、异常路径不回滚(硬缺陷 H9 的后半)

arrive_and_wait() 的 _cv.wait(lock, 谓词) 没有超时版本,Barrier 也没有 reset() 或 abort() 这类复位 API,_phase 单调递增。后果链:任一记录线程若在 arrive_and_wait() 之前终止(未捕获异常、submit() 内部抛 vsg::Exception、或 14.5.2 那种 status 被外部置假导致线程退出),本帧就少一个到达者;主线程在 src/vsg/app/Viewer.cpp:843 永久阻塞;下一帧即使新线程到达,_num_arrived 已经错位,_phase 永远不变,死锁不可恢复。

run lambda 里 viewer_task->submit(frameStamp)(:640)的返回值被丢弃,但 :642 的 arrive_and_drop() 无条件执行,所以 submit() 返回错误码不会漏到达;真正漏到达的只能是「线程根本没走到这一行」的异常路径。规避:给 arrive_and_wait 加超时并在超时后按 _threading 状态强制 _release(),或把 Barrier 换成带 cancel() 语义的一次性栅栏。

14.6.4 Latch 对照:Viewer 未用的那个原语

// include/vsg/threading/Latch.h:51-76
        bool count_down()
        {
            if (_count.fetch_sub(1) <= 1)
            {
                release();
                return true;
            }
            else
            {
                return false;
            }
        }

        bool is_ready() const
        {
            return (_count <= 0);
        }

        void wait()
        {
            std::unique_lock lock(_mutex);
            while (_count > 0)
            {
                _cv.wait(lock);
            }
        }

Latch 与 Barrier 同在 threading/,但 grep -rn "Latch" src/vsg/app/ include/vsg/app/ 零命中——Viewer 的帧同步完全不用 Latch,它归第十六章。

14.7 setupThreading:两种线程模型

14.7.1 numValidTasks 与屏障创建

// src/vsg/app/Viewer.cpp:598-621
void Viewer::setupThreading()
{
    stopThreading();

    // check how many valid tasks there are.
    uint32_t numValidTasks = 0;
    for (const auto& task : recordAndSubmitTasks)
    {
        if (!task->commandGraphs.empty())
        {
            ++numValidTasks;
        }
    }

    // check if there is any point in setting up threading
    if (numValidTasks == 0)
    {
        return;
    }

    status->set(true);
    _threading = true;
    _frameBlock = FrameBlock::create(status);
    _submissionCompleted = Barrier::create(1 + numValidTasks);

逐分支:函数第一行就 stopThreading()(无条件),所以 setupThreading() 是可重入的「先拆再建」。

代价与边界:setupThreading() 与 stopThreading() 内部都操作 status,但只有前者置真、后者置假,中间还夹着 close() 里的置假。三个写点分散在三个方法,没有统一的「线程状态机」。

14.7.2 简单路径恒假分支(硬缺陷 H3)

// src/vsg/app/Viewer.cpp:624-646
    // set up required threads for each task
    for (auto& task : recordAndSubmitTasks)
    {
        if (task->commandGraphs.size() == 1 && !task->transferTask)
        {
            // task only contains a single CommandGraph so keep thread simple
            auto run = [](ref_ptr<RecordAndSubmitTask> viewer_task, ref_ptr<FrameBlock> viewer_frameBlock, ref_ptr<Barrier> submissionCompleted, const std::string& threadName) {
                auto local_instrumentation = shareOrDuplicateForThreadSafety(viewer_task->instrumentation);
                if (local_instrumentation) local_instrumentation->setThreadName(threadName);

                auto frameStamp = viewer_frameBlock->initial_value;

                // wait for this frame to be signaled
                while (viewer_frameBlock->wait_for_change(frameStamp))
                {
                    CPU_INSTRUMENTATION_L1_NC(local_instrumentation, "Viewer run", COLOR_RECORD);

                    viewer_task->submit(frameStamp);

                    submissionCompleted->arrive_and_drop();
                }
            };

            threads.emplace_back(run, task, _frameBlock, _submissionCompleted, make_string("Viewer run thread"));
        }

判据是 task->commandGraphs.size() == 1 && !task->transferTask。第二个条件恒为假:RecordAndSubmitTask 构造函数无条件执行 transferTask = TransferTask::create(in_device, numBuffers);(src/vsg/app/RecordAndSubmitTask.cpp:38),全库 grep -rn "transferTask =" 的 app 实现里,除了构造这一处,其余都是把 task->transferTask 赋给 context->transferTask(src/vsg/app/CompileManager.cpp:413、src/vsg/app/CompileTraversal.cpp:71/90/120/156/260),没有任何一处把 transferTask 置空或 reset()。于是 !task->transferTask 永假,整个 run lambda 与 threads.emplace_back(run, ...) 从不进入。

14.7.3 SharedData 与三个 lambda

// src/vsg/app/Viewer.cpp:648-708
        else if (!task->commandGraphs.empty())
        {
            // we have multiple CommandGraphs in a single Task so set up a thread per CommandGraph
            struct SharedData : public Inherit<Object, SharedData>
            {
                SharedData(ref_ptr<RecordAndSubmitTask> in_task, ref_ptr<FrameBlock> in_frameBlock, ref_ptr<Barrier> in_submissionCompleted, uint32_t numThreads) :
                    task(in_task),
                    frameBlock(in_frameBlock),
                    submissionCompletedBarrier(in_submissionCompleted)
                {
                    recordedCommandBuffers = RecordedCommandBuffers::create();
                    recordStartBarrier = Barrier::create(numThreads);
                    recordCompletedBarrier = Barrier::create(numThreads);
                }
                ...
                ref_ptr<RecordedCommandBuffers> recordedCommandBuffers;
                ref_ptr<Barrier> recordStartBarrier;
                ref_ptr<Barrier> recordCompletedBarrier;
            };

            auto run_primary = [](ref_ptr<SharedData> data, ref_ptr<CommandGraph> commandGraph, const std::string& threadName) {
                ...
                while (data->frameBlock->wait_for_change(frameStamp))
                {
                    data->task->start();
                    data->recordStartBarrier->arrive_and_wait();
                    commandGraph->record(data->recordedCommandBuffers, frameStamp, data->task->databasePager);
                    data->recordCompletedBarrier->arrive_and_wait();
                    data->task->finish(data->recordedCommandBuffers);
                    data->recordedCommandBuffers->clear();
                    data->submissionCompletedBarrier->arrive_and_wait();
                }
            };

            auto run_secondary = [](ref_ptr<SharedData> data, ref_ptr<CommandGraph> commandGraph, const std::string& threadName) {
                ...
                while (data->frameBlock->wait_for_change(frameStamp))
                {
                    data->recordStartBarrier->arrive_and_wait();
                    commandGraph->record(data->recordedCommandBuffers, frameStamp, data->task->databasePager);
                    data->recordCompletedBarrier->arrive_and_wait();
                }
            };

逐字段:SharedData 持有 task、frameBlock、submissionCompletedBarrier(共享给所有线程),以及每个 task 独有的 recordedCommandBuffers、recordStartBarrier、recordCompletedBarrier。run_primary 是唯一调 start()/finish() 的线程,中间用 recordStartBarrier 等所有线程到齐、用 recordCompletedBarrier 等所有 record() 结束;run_secondary 只做 record(),被两条屏障夹住;run_transfer 结构相同,把 record() 换成 transferData(TRANSFER_BEFORE_RECORD_TRAVERSAL)(:729-754)。

关键推理:三条路径都向同一个 data->recordedCommandBuffers 写。这看起来像竞态,实测 include/vsg/vk/CommandBuffer.h:87-104 把 RecordedCommandBuffers 明确注释为「Thread safe container class」并带 mutable std::mutex _mutex,src/vsg/vk/CommandBuffer.cpp:94-101 的 add() 用 std::scoped_lock 串行化 push_back。所以并发 add 无竞态——这一点必须写清,按类名猜「多线程往一个 vector 写必然有锁问题」是错的。clear()/empty()/buffers() 同样各自加锁(:80-85、:103-107、:109-111)。

代价与边界:每个 CommandGraph 有自己的 recordTraversal(CommandGraph::getOrCreateRecordTraversal(),src/vsg/app/CommandGraph.cpp:65-74),所以 CommandBuffer::viewID/viewDependentState 这些字段是各 CommandGraph 独立的(回答第十三章第五问);但 SharedData::recordedCommandBuffers 是共享的,靠容器内部锁而非「各线程独立」解决。这是本章最容易误判的一处,值得单独记一笔。

14.7.4 numThreads 与 late transfer 缺失

// src/vsg/app/Viewer.cpp:674-767
            uint32_t numThreads = static_cast<uint32_t>(task->commandGraphs.size());
            if (task->transferTask) ++numThreads;
            ...
            if (task->transferTask)
            {
                threads.emplace_back(run_transfer, sharedData, task->transferTask, TransferTask::TRANSFER_BEFORE_RECORD_TRAVERSAL, make_string("Viewer early transferTask thread"));
            }

numThreads = commandGraphs.size() 加一条 transfer 线程,recordStartBarrier/recordCompletedBarrier 都按这个数创建(:659-660)。

14.7.5 stopThreading 与「重建前先停」

// src/vsg/app/Viewer.cpp:772-791
void Viewer::stopThreading()
{
    CPU_INSTRUMENTATION_L1_NC(instrumentation, "Viewer stopThreading", COLOR_VIEWER);

    if (!_threading) return;
    _threading = false;

    debug("Viewer::stopThreading()");

    // release the blocks to enable threads to exit cleanly
    status->set(false);
    _frameBlock->wake();

    for (auto& thread : threads)
    {
        if (thread.joinable()) thread.join();
    }
    threads.clear();
}

if (!_threading) return; 使 stopThreading() 幂等。置 _threading = false、status->set(false)、_frameBlock->wake()、逐个 join()、threads.clear()。注意 _frameBlock 与 _submissionCompleted 不清空,下次 setupThreading() 会整体替换(:620-621)。

assignRecordAndSubmitTaskAndPresentation() 开头(:425-426)与 assignInstrumentation()(:866-867)都先判 _threading 再 stopThreading(),结尾再按 needToStartThreading/。


14.8 RecordAndSubmitTask 的索引与 fence

14.8.1 构造与 numBuffers = 3

// src/vsg/app/RecordAndSubmitTask.cpp:21-44
RecordAndSubmitTask::RecordAndSubmitTask(Device* in_device, uint32_t numBuffers) :
    device(in_device)
{
    CPU_INSTRUMENTATION_L1(instrumentation);

    _currentFrameIndex = numBuffers; // numBuffers is used to signify unset value
    for (uint32_t i = 0; i < numBuffers; ++i)
    {
        _indices.emplace_back(numBuffers); // numBuffers is used to signify unset value
    }

    _fences.resize(numBuffers);
    for (uint32_t i = 0; i < numBuffers; ++i)
    {
        _fences[i] = Fence::create(device);
    }

    transferTask = TransferTask::create(in_device, numBuffers);

    earlyTransferConsumerCompletedSemaphore = Semaphore::create(in_device);
    lateTransferConsumerCompletedSemaphore = Semaphore::create(in_device);

    if (!device->transferTask) device->transferTask = transferTask;
}

逐字段:_currentFrameIndex 初值置为 numBuffers(越界的哨兵值),_indices 填 numBuffers 个同样的哨兵值,_fences 造 numBuffers 个 Fence。transferTask 无条件创建(14.7.2 的依据),earlyTransferConsumerCompletedSemaphore/lateTransferConsumerCompletedSemaphore 两个消费者完成信号量也在此造好;而 earlyDataTransferredSemaphore/lateDataTransferredSemaphore 是传输结果,每帧由 submit()/finish() 赋值、start() reset,构造里不建。

14.8.2 advance() 与 _indices 移位

// src/vsg/app/RecordAndSubmitTask.cpp:46-71
void RecordAndSubmitTask::advance()
{
    CPU_INSTRUMENTATION_L1_NC(instrumentation, "RecordAndSubmitTask advance", COLOR_VIEWER);

    if (_currentFrameIndex >= _indices.size())
    {
        // first frame so set to 0
        _currentFrameIndex = 0;
    }
    else
    {
        ++_currentFrameIndex;
        if (_currentFrameIndex > _indices.size() - 1) _currentFrameIndex = 0;

        // shift the index for previous frames
        for (size_t i = _indices.size() - 1; i >= 1; --i)
        {
            _indices[i] = _indices[i - 1];
        }
    }

    // pass the index for the current frame
    _indices[0] = _currentFrameIndex;
}

逐分支:首帧(_currentFrameIndex == numBuffers 哨兵)直接置 0,不做移位;此后每帧 ++ 并在越界时回绕到 0,然后把 _indices[1..n-1] 整体右移一格(从后往前赋值避免覆盖),最后 _indices[0] = _currentFrameIndex。

14.8.3 index() / fence() 与三帧在飞

// src/vsg/app/RecordAndSubmitTask.cpp:73-83
size_t RecordAndSubmitTask::index(size_t relativeFrameIndex) const
{
    return relativeFrameIndex < _indices.size() ? _indices[relativeFrameIndex] : _indices.size();
}

/// fence() and fence(0) return the Fence for the frame currently being rendered, fence(1) returns the previous frame's Fence etc.
ref_ptr<Fence> RecordAndSubmitTask::fence(size_t relativeFrameIndex)
{
    size_t i = index(relativeFrameIndex);
    return i < _fences.size() ? _fences[i] : nullptr;
}

index() 越界返回 _indices.size()(一个越界值),fence() 再用 i < _fences.size() 把这个越界值映射成 nullptr。Viewer::waitForFences(size_t relativeFrameIndex, uint64_t timeout)(src/vsg/app/Viewer.cpp:248-263)遍历所有 task 调 task->fence(relativeFrameIndex),判空后 fenceToWait->wait(timeout)。

三帧在飞的节流实现:start() 用 fence() 取当前槽位的 fence,若 hasDependencies() 为真就 wait(UINT64_MAX) 并 resetFenceAndDependencies()(14.9.2)。因为 _currentFrameIndex 每 3 帧回绕一次,第 4 帧会撞上第 1 帧的 fence,从而阻塞到第 1 帧 GPU 完成——这就是「没有 _framesInFlight 字段却实现了三帧在飞」的全部机制。

14.8.4 numBuffers = 0 的越界与除零(硬缺陷 H11)

构造函数允许 numBuffers = 0,此时 _indices/_fences 皆空:advance() 写 _indices[0] 越界,start() 空 fence 解引用,_transferData() 索引越界且 % frames.size() 除零。规避是构造断言 numBuffers >= 1。

14.8.5 device->transferTask 单例赋值

if (!device->transferTask) device->transferTask = transferTask; 让多个 task 共享同一 Device 时只有第一个挂上设备级 transferTask,其余各自持独立对象,于是设备级编译与任务级编译可能取到不同传输对象。


14.9 submit 的 start / record / finish 三段

14.9.1 submit() 的编排

// src/vsg/app/RecordAndSubmitTask.cpp:85-114
VkResult RecordAndSubmitTask::submit(ref_ptr<FrameStamp> frameStamp)
{
    CPU_INSTRUMENTATION_L1_NC(instrumentation, "RecordAndSubmitTask submit", COLOR_RECORD);

    if (VkResult result = start(); result != VK_SUCCESS) return result;

    if (transferTask)
    {
        if (auto transfer = transferTask->transferData(TransferTask::TRANSFER_BEFORE_RECORD_TRAVERSAL); transfer.result == VK_SUCCESS)
        {
            if (transfer.dataTransferredSemaphore)
            {
                earlyDataTransferredSemaphore = transfer.dataTransferredSemaphore;
            }
        }
        else
        {
            return transfer.result;
        }
    }

    auto recordedCommandBuffers = RecordedCommandBuffers::create();

    if (VkResult result = record(recordedCommandBuffers, frameStamp); result != VK_SUCCESS) return result;

    return finish(recordedCommandBuffers);
}

四步:start() → early 传输 → record() → finish()。任何一步返回非 VK_SUCCESS 立即短路。注意 record() 恒返回 VK_SUCCESS(14.9.3),所以 submit() 的错误只可能来自 start()、early 传输、finish()。recordedCommandBuffers 是栈上 ref_ptr,每帧新建,不复用——这与多线程路径里 SharedData 复用同一个 RecordedCommandBuffers 并每帧 clear()(src/vsg/app/Viewer.cpp:704)不同。

代价与边界:submit() 的错误返回值在 Viewer::recordAndSubmit() 的串行分支(:849)与 run lambda(:640)里都被丢弃,只有多线程 run_primary(:691、:702)的 start()/finish() 返回值同样被丢弃。也就是说传输失败、fence 等待失败、queue 提交失败都不会让主循环停下来,帧继续推进,错误只体现在 instrumentation 日志里。这是静默降级的又一处。

14.9.2 start() 的 fence 等待

// src/vsg/app/RecordAndSubmitTask.cpp:116-147
VkResult RecordAndSubmitTask::start()
{
    CPU_INSTRUMENTATION_L1_NC(instrumentation, "RecordAndSubmitTask start", COLOR_RECORD);

    earlyDataTransferredSemaphore.reset();
    lateDataTransferredSemaphore.reset();

    if (_currentFrameIndex >= _indices.size())
    {
        debug("RecordAndSubmitTask::start() called before advance() so call it now to make sure all the indices align.");
        advance();
    }

    auto current_fence = fence();
    if (current_fence->hasDependencies())
    {
        uint64_t timeout = std::numeric_limits<uint64_t>::max();
        if (VkResult result = current_fence->wait(timeout); result != VK_SUCCESS) return result;

        current_fence->resetFenceAndDependencies();
    }
    else
    {
        //info("RecordAndSubmitTask::start() initial fence ", ...);
    }

    return VK_SUCCESS;
}

逐分支:先 reset 两个传输信号量;若 _currentFrameIndex 仍是哨兵(调用方漏调 advance()),补一次 advance();取当前槽位 fence,hasDependencies() 为 (_dependentSemaphores.size() + _dependentCommandBuffers.size()) > 0(include/vsg/vk/Fence.h:36),有依赖就 wait(UINT64_MAX) 无限等,然后 resetFenceAndDependencies()(src/vsg/vk/Fence.cpp:40-56)把依赖的 semaphore/commandBuffer 的 numDependentSubmissions 归零、清空两个容器、vkResetFences。

wait(UINT64_MAX) 是帧在飞的硬阻塞点,与 Context::waitForCompletion() 的 1 秒轮询(src/vsg/vk/Context.cpp:385-391)不同:前者一次无限等,后者每秒打印一次「timed out, trying again」。

14.9.3 record() 恒返回 SUCCESS

// src/vsg/app/RecordAndSubmitTask.cpp:149-159
VkResult RecordAndSubmitTask::record(ref_ptr<RecordedCommandBuffers> recordedCommandBuffers, ref_ptr<FrameStamp> frameStamp)
{
    CPU_INSTRUMENTATION_L1_NC(instrumentation, "RecordAndSubmitTask record", COLOR_RECORD);

    for (auto& commandGraph : commandGraphs)
    {
        commandGraph->record(recordedCommandBuffers, frameStamp, databasePager);
    }

    return VK_SUCCESS;
}

record() 遍历 commandGraphs,逐个调 commandGraph->record(...),无条件返回 VK_SUCCESS。CommandGraph::record() 返回 void(include/vsg/app/CommandGraph.h),其内部 vkBeginCommandBuffer/vkEndCommandBuffer(src/vsg/app/CommandGraph.cpp:130/:137)的 VkResult 也没有被检查——记录期所有 Vulkan 错误都不向上传播。这是「恒成功 API」:签名保留 VkResult 是为了与 start()/finish() 对称,实际永远不失败。

14.9.4 finish() 空缓冲的 16ms 睡眠

// src/vsg/app/RecordAndSubmitTask.cpp:187-195
    if (recordedCommandBuffers->empty())
    {
        if (earlyDataTransferredSemaphore) transferTask->assignTransferConsumedCompletedSemaphore(TransferTask::TRANSFER_BEFORE_RECORD_TRAVERSAL, earlyDataTransferredSemaphore);
        if (lateDataTransferredSemaphore) transferTask->assignTransferConsumedCompletedSemaphore(TransferTask::TRANSFER_AFTER_RECORD_TRAVERSAL, lateDataTransferredSemaphore);

        // nothing to do so return early
        std::this_thread::sleep_for(std::chrono::milliseconds(16)); // sleep for 1/60th of a second
        return VK_SUCCESS;
    }

逐分支:无命令缓冲(窗口不可见、或所有 CommandGraph::record() 提前 return)时,先把两个已产生的传输信号量「退还」给 TransferTask 作为消费者完成信号量,然后 sleep_for(16ms) 固定睡眠再返回成功。


14.10 finish() 的信号量装配与 queue->submit

14.10.1 四个 vector 与命令缓冲转换

// src/vsg/app/RecordAndSubmitTask.cpp:197-210
    // convert VSG CommandBuffer to Vulkan handles and add to the Fence's list of dependent CommandBuffers
    std::vector<VkCommandBuffer> vk_commandBuffers;
    std::vector<VkSemaphore> vk_waitSemaphores;
    std::vector<VkPipelineStageFlags> vk_waitStages;
    std::vector<VkSemaphore> vk_signalSemaphores;

    auto buffers = recordedCommandBuffers->buffers();
    for (auto& commandBuffer : buffers)
    {
        if (commandBuffer->level() == VK_COMMAND_BUFFER_LEVEL_PRIMARY) vk_commandBuffers.push_back(*commandBuffer);

        current_fence->dependentCommandBuffers().emplace_back(commandBuffer);
    }

逐字段:四个 vector 分别喂给 VkSubmitInfo 的 pCommandBuffers、pWaitSemaphores、pWaitDstStageMask、pSignalSemaphores。recordedCommandBuffers->buffers() 返回排好序的 CommandBuffers(src/vsg/vk/CommandBuffer.cpp:109-133)。只有 VK_COMMAND_BUFFER_LEVEL_PRIMARY 被放进提交列表,二级缓冲通过 ExecuteCommands 间接进入主缓冲(第七章主题);但 所有 缓冲(含二级)都被塞进 current_fence->dependentCommandBuffers(),用于 resetFenceAndDependencies() 时归零 numDependentSubmissions。

代价与边界:vk_waitSemaphores 与 vk_waitStages 是两个平行 vector,靠「每次同时 emplace_back」维持等长(:214-215、:219-220、:235-236、:244-245),没有结构体把二者绑在一起。任一处漏一个 emplace_back,pWaitDstStageMask 就会与 waitSemaphoreCount 长度不符,Vulkan 层越界读——这是并行数组的老问题。

14.10.2 early / late 信号量与退还

// src/vsg/app/RecordAndSubmitTask.cpp:212-224
    if (earlyDataTransferredSemaphore)
    {
        vk_waitSemaphores.emplace_back(*earlyDataTransferredSemaphore);
        vk_waitStages.emplace_back(earlyDataTransferredSemaphore->pipelineStageFlags());
    }
    if (lateDataTransferredSemaphore)
    {
        vk_waitSemaphores.emplace_back(*lateDataTransferredSemaphore);
        vk_waitStages.emplace_back(lateDataTransferredSemaphore->pipelineStageFlags());
    }

    if (earlyDataTransferredSemaphore) transferTask->assignTransferConsumedCompletedSemaphore(TransferTask::TRANSFER_BEFORE_RECORD_TRAVERSAL, earlyTransferConsumerCompletedSemaphore);
    if (lateDataTransferredSemaphore) transferTask->assignTransferConsumedCompletedSemaphore(TransferTask::TRANSFER_AFTER_RECORD_TRAVERSAL, lateTransferConsumerCompletedSemaphore);

early/late 传输完成信号量作为 wait 加入提交,同时把两个消费者完成信号量登记到 TransferTask,供下一帧传输作为 wait;二者形成传输与图形提交之间的背压闭环。

代价与边界:assignTransferConsumedCompletedSemaphore() 里 if ((transferMask & ...) != 0) 用的是位与,若传入 TRANSFER_ALL(include/vsg/app/TransferTask.h:44),两个 DataToCopy 会被赋同一个 semaphore,破坏 early/late 隔离;本章调用点都传单一位(:223-224 与 :189-190),所以正常路径不会触发。

14.10.3 windows 的 imageAvailable / renderFinished

// src/vsg/app/RecordAndSubmitTask.cpp:228-240
    for (auto& window : windows)
    {
        auto imageIndex = window->imageIndex();
        if (imageIndex >= window->numFrames()) continue;

        auto& frame = window->frame(imageIndex);

        vk_waitSemaphores.emplace_back(frame.imageAvailableSemaphore->vk());
        vk_waitStages.emplace_back(frame.imageAvailableSemaphore->pipelineStageFlags());

        vk_signalSemaphores.emplace_back(frame.renderFinishedSemaphore->vk());
        current_fence->dependentSemaphores().push_back(frame.renderFinishedSemaphore);
    }

每个窗口取 imageIndex(),>= numFrames() 就 continue(Window::imageIndex() 越界时返回 _indices.size(),见 include/vsg/app/Window.h:116,所以这个检查是必需的第二道防线)。通过则把 imageAvailableSemaphore 作为 wait、renderFinishedSemaphore 作为 signal 加入。Presentation::present() 又在 src/vsg/app/Presentation.cpp:38-39 把同一个 renderFinishedSemaphore 作为 VkPresentInfoKHR 的 wait——这就是图形提交与呈现之间唯一的同步边,第十五章会从 Queue/Swapchain 一侧继续展开。

14.10.4 dependentSemaphores 记账覆盖(硬缺陷 H16)

// src/vsg/app/RecordAndSubmitTask.cpp:242-253
    for (auto& semaphore : waitSemaphores)
    {
        vk_waitSemaphores.emplace_back(semaphore->vk());
        vk_waitStages.emplace_back(semaphore->pipelineStageFlags());
    }

    current_fence->dependentSemaphores() = signalSemaphores;
    for (auto& semaphore : signalSemaphores)
    {
        vk_signalSemaphores.emplace_back(semaphore->vk());
        current_fence->dependentSemaphores().push_back(semaphore);
    }

waitSemaphores(include/vsg/app/RecordAndSubmitTask.h:40,注释「assign in application setup」)只进 vk_waitSemaphores,不进 fence 依赖表;signalSemaphores(:42,注释「connect to Presentation.waitSemaphores」)则有两处写入::248 的整体赋值 dependentSemaphores() = signalSemaphores,紧接着 :249-253 又遍历 signalSemaphores 逐个 push_back(semaphore)。于是同一个集合被存了两遍。更严重的是 :248 的整体赋值发生在 :239 之后,把窗口循环里 push_back(frame.renderFinishedSemaphore) 攒下的记账整批覆盖丢弃。

后果:Fence::resetFenceAndDependencies()(src/vsg/vk/Fence.cpp:40-56)只会把仍在 _dependentSemaphores 里的对象 numDependentSubmissions().exchange(0);被覆盖掉的 renderFinishedSemaphore 不再被清零,重复存入的 signalSemaphores 被清零两次(第二次无害)。触发条件:windows 非空且 signalSemaphores 非空同时成立——即「有窗口呈现 + 应用又配了 signalSemaphores 串联」的多 task 场景。规避:删掉 :248 的整体赋值,保留 :252 的循环追加,并在 :239 之后不再覆盖。这是本章唯一一处纯粹的状态记账错误。

14.10.5 VkSubmitInfo 与 queue->submit

// src/vsg/app/RecordAndSubmitTask.cpp:266-280
    VkSubmitInfo submitInfo = {};
    submitInfo.sType = VK_STRUCTURE_TYPE_SUBMIT_INFO;

    submitInfo.waitSemaphoreCount = static_cast<uint32_t>(vk_waitSemaphores.size());
    submitInfo.pWaitSemaphores = vk_waitSemaphores.data();
    submitInfo.pWaitDstStageMask = vk_waitStages.data();

    submitInfo.commandBufferCount = static_cast<uint32_t>(vk_commandBuffers.size());
    submitInfo.pCommandBuffers = vk_commandBuffers.data();

    submitInfo.signalSemaphoreCount = static_cast<uint32_t>(vk_signalSemaphores.size());
    submitInfo.pSignalSemaphores = vk_signalSemaphores.data();

    return queue->submit(submitInfo, current_fence);

queue 是 include/vsg/app/RecordAndSubmitTask.h:61 的字段,由 Viewer::assignRecordAndSubmitTaskAndPresentation() 赋 mainQueue(src/vsg/app/Viewer.cpp:544/:564)。

14.10.6 Fence 依赖记账的闭环

// src/vsg/vk/Fence.cpp:40-66
void Fence::resetFenceAndDependencies()
{
    for (auto& semaphore : _dependentSemaphores)
    {
        semaphore->numDependentSubmissions().exchange(0);
    }

    for (auto& commandBuffer : _dependentCommandBuffers)
    {
        commandBuffer->numDependentSubmissions().exchange(0);
    }

    _dependentSemaphores.clear();
    _dependentCommandBuffers.clear();

    reset();
}

VkResult Fence::wait(uint64_t timeout) const
{
    return vkWaitForFences(*_device, 1, &_vkFence, VK_TRUE, timeout);
}

numDependentSubmissions 是 CommandBuffer/Semaphore 上的原子计数;CommandGraph::record() 用它挑空闲缓冲并 fetch_add(1),resetFenceAndDependencies() 在下一轮 start() 归零,构成缓冲复用闭环。

代价与边界:整个闭环没有任何超时或错误回滚——若 queue->submit() 失败但 finish() 仍返回错误码被丢弃(14.9.1),dependentCommandBuffers 已登记、numDependentSubmissions 已加一,而 fence 从未被 signal,start() 下次 wait(UINT64_MAX) 会永久阻塞。异常路径不回滚在这里与 Barrier 缺到达者(14.6.3)叠加成同一类死锁。

14.11 TransferTask 在任务链中的位置

14.11.1 命名核对与两个挂载点

主题清单里的 earlyTransferTask/lateTransferTask/_currentTransferIndex 全库零命中(14.0 已实测),真实结构是单个 transferTask(include/vsg/app/RecordAndSubmitTask.h:44)+ 两组 DataToCopy:

// include/vsg/app/TransferTask.h:87-110
        struct DataToCopy
        {
            std::string name;
            BufferMap dataMap;
            std::set<ref_ptr<ImageInfo>> imageInfoSet;

            uint32_t frameIndex = 0;
            std::vector<ref_ptr<TransferBlock>> frames;
            ...
            ref_ptr<Semaphore> transferCompleteSemaphore;
            ref_ptr<Semaphore> transferConsumerCompletedSemaphore;
            ...
        };

        DataToCopy _earlyDataToCopy;
        DataToCopy _lateDataToCopy;

        size_t _bufferCount;

TransferTask 在本章任务链里只被两个点调用:submit() 里的 TRANSFER_BEFORE_RECORD_TRAVERSAL(src/vsg/app/RecordAndSubmitTask.cpp:95)与 finish() 里的 TRANSFER_AFTER_RECORD_TRAVERSAL(:171)。

14.11.2 TransferMask 与 TRANSFER_ALL 覆盖(硬缺陷 H7)

// src/vsg/app/TransferTask.cpp:340-348
TransferTask::TransferResult TransferTask::transferData(TransferMask transferMask)
{
    log(level, "TransferTask::transferData(", transferMask, ")");

    TransferTask::TransferResult result;
    if ((transferMask & TRANSFER_BEFORE_RECORD_TRAVERSAL) != 0) result = _transferData(_earlyDataToCopy);
    if ((transferMask & TRANSFER_AFTER_RECORD_TRAVERSAL) != 0) result = _transferData(_lateDataToCopy);
    return result;
}

枚举定义 TRANSFER_NONE = 0、BEFORE = 1 << 0、AFTER = 1 << 1、ALL = 3(include/vsg/app/TransferTask.h:39-45)。两个 if 顺序执行、共用同一个 result:传入 TRANSFER_ALL 时,early 的 TransferResult(含 dataTransferredSemaphore)被 late 的结果整个覆盖。触发条件:调用方传 TRANSFER_ALL 或同时置两个位。后果:早传输已提交 GPU、其完成信号量却没被返回,图形提交不会 wait 它,早传输与图形命令之间形成数据竞态。规避:分别返回两个信号量,或把结果改成累加结构。本章 RecordAndSubmitTask 的两处调用都传单一位,所以正常路径不触发,但 transferData 是 public virtual,外部调用无保护。

14.11.3 frameIndex 轮转与 map 失败静默(硬缺陷 H7)

// src/vsg/app/TransferTask.cpp:435-444
    if (frame.waitOnFence && fence)
    {
        uint64_t timeout = std::numeric_limits<uint64_t>::max();
        if (VkResult result = fence->wait(timeout); result != VK_SUCCESS) return TransferResult{result, {}};
        fence->resetFenceAndDependencies();
    }
    frame.waitOnFence = false;

    // advance frameIndex
    dataToCopy.frameIndex = (dataToCopy.frameIndex + 1) % dataToCopy.frames.size();
// src/vsg/app/TransferTask.cpp:481-487
        auto stagingMemory = staging->getDeviceMemory(deviceID);
        buffer_data = nullptr;
        result = stagingMemory->map(staging->getMemoryOffset(deviceID), staging->size, 0, &buffer_data);
        ...
        if (result != VK_SUCCESS) return TransferResult{VK_SUCCESS, {}};

frameIndex 以 % frames.size() 轮转,构成与 _fences 同构的三槽环;:354 的 scoped_lock 覆盖整个 _transferData(),包括 :438 的 fence->wait(UINT64_MAX) 与 :546 的 queue->submit(),锁粒度极粗。

14.11.4 CopyAndReleaseBuffer / Image 的真实位置

// include/vsg/commands/CopyAndReleaseBuffer.h:23-24
    /// Deprecated - use vsg::Data dataVariance and Data::dirty() to signal vsg::TransferTask to transfer data.
    class VSG_DECLSPEC CopyAndReleaseBuffer : public Inherit<Command, CopyAndReleaseBuffer>
// include/vsg/commands/CopyAndReleaseImage.h:23-24
    /// Deprecated - use vsg::Data dataVariance and Data::dirty() to signal vsg::TransferTask to transfer data.
    class VSG_DECLSPEC CopyAndReleaseImage : public Inherit<Command, CopyAndReleaseImage>

两个头文件第一行注释就标了 Deprecated。实测路径在 include/vsg/commands/ 与 src/vsg/commands/,不在 app/:这正是「不要凭类名猜目录」的一例。


14.12 记录调用链:从 task::record 到 RecordTraversal

14.12.1 CommandGraph::record 的命令缓冲池

// src/vsg/app/CommandGraph.cpp:76-116 (关键行)
void CommandGraph::record(ref_ptr<RecordedCommandBuffers> recordedCommandBuffers, ref_ptr<FrameStamp> frameStamp, ref_ptr<DatabasePager> databasePager)
{
    if (window && !window->visible())
    {
        return;
    }
    getOrCreateRecordTraversal();
    recordTraversal->recordedCommandBuffers = recordedCommandBuffers;
    recordTraversal->setFrameStamp(frameStamp);
    recordTraversal->setDatabasePager(databasePager);
    recordTraversal->clearBins();
    recordTraversal->regionsOfInterest.clear();

    ref_ptr<CommandBuffer> commandBuffer;
    for (auto& cb : _commandBuffers)
    {
        if (cb->numDependentSubmissions() == 0) { commandBuffer = cb; break; }
    }
    if (!commandBuffer)
    {
        ref_ptr<CommandPool> cp = CommandPool::create(device, queueFamily, VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT);
        commandBuffer = cp->allocate(level());
        _commandBuffers.push_back(commandBuffer);
    }
    else
    {
        commandBuffer->reset();
    }
    commandBuffer->frameStamp = frameStamp;
    commandBuffer->numDependentSubmissions().fetch_add(1);

调用链是 RecordAndSubmitTask::record()(src/vsg/app/RecordAndSubmitTask.cpp:153-156)→ CommandGraph::record() → traverse(*recordTraversal)(:134)→ 各节点的 RecordTraversal::apply()。getOrCreateRecordTraversal()(:65-74)保证每个 CommandGraph 一个自己的 RecordTraversal,所以多线程记录时各线程的状态栈、bins、viewDependentState 互不共享——这回答了第十三章第五问的前半。

14.12.2 SecondaryCommandGraph 与 reset()

两个头文件第一行注释就标了 Deprecated;实测路径在 include/vsg/commands/ 与 src/vsg/commands/,不在 app/,正是「不要凭类名猜目录」的一例。

14.12.3 RecordTraversal::apply(View&) 状态恢复不对称(硬缺陷 H8)

// src/vsg/app/RecordTraversal.cpp:567-570 与 :663-668
    auto cached_traversalMask = state->_commandBuffer->traversalMask;
    state->_commandBuffer->traversalMask = traversalMask;
    state->_commandBuffer->viewID = view.viewID;
    state->_commandBuffer->viewDependentState = view.viewDependentState.get();
    ...
    // swap back previous bin setup.
    minimumBinNumber = cached_minimumBinNumber;
    cached_bins.swap(bins);
    cached_regionsOfInterest.swap(regionsOfInterest);
    state->_commandBuffer->traversalMask = cached_traversalMask;
    viewDependentState = cached_viewDependentState;

进入 apply(const View&) 时缓存了 cached_traversalMask、cached_bins、cached_regionsOfInterest、cached_viewDependentState 与 minimumBinNumber,同时却向 CommandBuffer 写了 traversalMask、viewID、viewDependentState 三样。

14.12.4 RecordedCommandBuffers 线程安全复核结论

第十三章预告担心「CommandBuffer::viewID/viewDependentState 在多线程记录时是否各线程独立、shadowMaps 由谁串行化」。


14.13 update 阶段的调度

14.13.1 requiresViewerUpdate 的四个判据

// src/vsg/app/CompileManager.cpp:60-83
bool CompileResult::requiresViewerUpdate(const Viewer* viewer) const
{
    if (result == VK_INCOMPLETE) return false;

    if (dynamicData) return true;

    for (auto& [view, binDetails] : views)
    {
        if (!binDetails.indices.empty() || !binDetails.bins.empty()) return true;
    }

    if (viewer)
    {
        for (const auto& task : viewer->recordAndSubmitTasks)
        {
            for (const auto& commandGraph : task->commandGraphs)
            {
                if (commandGraph->maxSlots.requiresUpdate(maxSlots)) return true;
            }
        }
    }

    return false;
}

四个判据按短路顺序:VK_INCOMPLETE 直接 false → dynamicData 非空 true → 任一 view 有 indices/bins true → 任一 commandGraph->maxSlots.requiresUpdate(maxSlots) true。注意第二条:「只要 result != VK_INCOMPLETE 且 dynamicData 非空」就返回 true,包括编译失败(VK_ERROR_*)的情形——失败结果也会触发 updateViewer()(14.3.2 的 :808-811)。第十三章预告问 updateTasks 如何分派 CompileResult:答案就在这个判定后调 updateViewer() → updateTasks(viewer.recordAndSubmitTasks, viewer.compileManager, compileResult)(src/vsg/app/Viewer.cpp:887-892),分派目标只有 recordAndSubmitTasks 一个容器。

14.13.2 CompileResult::add 的 break(硬缺陷 H6)

// src/vsg/app/CompileManager.cpp:37-58
void CompileResult::add(const CompileResult& cr)
{
    if (result == VK_INCOMPLETE || result == VK_SUCCESS)
    {
        result = cr.result;
    }

    maxSlots.update(cr.maxSlots);

    if (!containsPagedLOD) containsPagedLOD = cr.containsPagedLOD;

    for (auto& [src_view, src_binDetails] : cr.views)
    {
        if (src_binDetails.indices.empty() && src_binDetails.bins.empty()) break;

        auto& binDetails = views[src_view];
        binDetails.indices.insert(src_binDetails.indices.begin(), src_binDetails.indices.end());
        binDetails.bins.insert(src_binDetails.bins.begin(), src_binDetails.bins.end());
    }

    dynamicData.add(cr.dynamicData);
}

:50 的 break 应为 continue。遍历 cr.views(std::map,按 View* 排序)时,只要遇到第一个「indices 与 bins 都空」的 view,就跳出整个循环,其后所有 view 的 bin 需求不再合并进 views。触发条件:一次编译产生多个 View,且按指针排序靠前的某个 View 恰好没有 bin 需求。后果:requiresViewerUpdate() 的第三个判据可能看不到后续 view,updateTasks() 的 bin 补齐(14.13.3)漏做,帧期 RecordTraversal::addToBin()(src/vsg/app/RecordTraversal.cpp:703)按缺失的 binNumber 索引 bins 越界。规避:把 break 改成 continue,空 binDetails 直接跳过而不终止遍历。这是 Viewer::compile() 里 result.add(compileManager->compileTask(...))(src/vsg/app/Viewer.cpp:401)累计多个 task 结果时唯一的一处汇总逻辑,缺陷影响面覆盖所有多 task 编译。

14.13.3 updateViewer / updateTasks 的 bin 补齐

// src/vsg/app/RecordAndSubmitTask.cpp:344-365 (节选)
    /// handle any new Bin needs
    for (auto& [const_view, viewDetails] : compileResult.views)
    {
        auto view = const_cast<View*>(const_view);
        for (auto& binNumber : viewDetails.indices)
        {
            bool binNumberMatched = false;
            for (const auto& bin : view->bins)
            {
                if (bin->binNumber == binNumber) binNumberMatched = true;
            }
            if (!binNumberMatched)
            {
                Bin::SortOrder sortOrder = (binNumber < 0) ? Bin::ASCENDING : ((binNumber == 0) ? Bin::NO_SORT : Bin::DESCENDING);
                view->bins.push_back(Bin::create(binNumber, sortOrder));
            }
        }
    }

updateTasks()(src/vsg/app/RecordAndSubmitTask.cpp:296-365)做四件事:分派 dynamicData 给各 transferTask、更新 commandGraph->maxSlots、按需补 DatabasePager、补齐 view->bins。

14.13.4 UpdateOperations::run 的 swap 与异常不回滚

// src/vsg/app/UpdateOperations.cpp:60-71
void UpdateOperations::run()
{
    container_type updateOperations;

    {
        std::scoped_lock<std::mutex> lock(_updateOperationMutex);
        _updateOperationsOneTime.swap(updateOperations);
        updateOperations.insert(updateOperations.end(), _updateOperationsAllFrames.begin(), _updateOperationsAllFrames.end());
    }

    for (auto op : updateOperations) op->run();
}

ONE_TIME 队列被整体 swap 到局部 updateOperations(锁内),ALL_FRAMES 队列被拷贝指针追加,然后锁外逐个 op->run()。

14.13.5 compile() / compileTask() 两条路径与编译屏障

CompileManager 有两条编译入口:compile()(src/vsg/app/CompileManager.cpp:257-390)从池取 CompileTraversal,compileTask()(:392-447)直接新建;Viewer::compile() 用的是后者。

两条路径都在末尾做同一件事:

// src/vsg/app/CompileManager.cpp:430-433
        if (compileTraversal->record())
        {
            compileTraversal->waitForCompletion();
        }

CompileTraversal::waitForCompletion() 落到 Context::waitForCompletion()(src/vsg/vk/Context.cpp:385-405):timeout = 1000000000 一秒轮询、while (result == VK_TIMEOUT) 无限重试,结束后清空 commands 与两个 copy 命令。


14.14 Viewer::compile 全貌

14.14.1 DeviceResourceMap 与 CollectResourceRequirements

// src/vsg/app/Viewer.cpp:278-313 (节选)
CompileResult Viewer::compile(ref_ptr<ResourceHints> hints)
{
    if (recordAndSubmitTasks.empty())
    {
        return {};
    }
    ...
    using DeviceResourceMap = std::map<ref_ptr<vsg::Device>, DeviceResources>;
    DeviceResourceMap deviceResourceMap;
    for (auto& task : recordAndSubmitTasks)
    {
        auto& collectResources = deviceResourceMap[task->device].collectResources;
        auto& resourceRequirements = collectResources.requirements;
        if (hints) hints->accept(collectResources);

        for (auto& commandGraph : task->commandGraphs)
        {
            commandGraph->accept(collectResources);
        }

        task->transferTask->minimumStagingBufferSize = resourceRequirements.minimumStagingBufferSize;

逐字段:按 Device 分组汇总 CollectResourceRequirements(include/vsg/app/CompileManager.h 前置),把 hints 与每条 commandGraph 喂给遍历,取回 resourceRequirements。

14.14.2 bin 补齐写两遍

Viewer::compile() 在 :327-347 自己补了一遍 view->bins(与 :333-345 的三重循环 + const_cast<View*>),updateTasks() 又在 src/vsg/app/RecordAndSubmitTask.cpp:344-364 补了几乎相同的一遍。两处代码逐行同构:同样的 binNumberMatched 标志、同样的 Bin::SortOrder 三元判定、同样的 push_back(Bin::create(...)),只有变量名 binDetails/viewDetails 之差。这是重复论证式的重复实现:编译期补一次、运行期 updateViewer 再补一次,任何一处改了排序规则而另一处没改就会不一致。可复现核对见「可复现验证」里的 diff 命令。

14.14.3 assignRecordAndSubmitTaskAndPresentation 分组

// src/vsg/app/Viewer.cpp:471-501 (节选)
    std::map<DeviceQueueFamily, CommandGraphs> deviceCommandGraphsMap;
    for (auto& commandGraph : in_commandGraphs)
    {
        commandGraph->accept(findWindows);
        deviceCommandGraphsMap[DeviceQueueFamily{commandGraph->device.get(), commandGraph->queueFamily, commandGraph->presentFamily}].emplace_back(commandGraph);
    }
    ...
    _windows.assign(findWindows.windows.begin(), findWindows.windows.end());
    ...
        CommandGraphs primary_commandGraphs;
        CommandGraphs secondary_commandGraphs;
        for (auto& commandGraph : commandGraphs)
        {
            if (commandGraph->level() == VK_COMMAND_BUFFER_LEVEL_PRIMARY)
                primary_commandGraphs.emplace_back(commandGraph);
            else
                secondary_commandGraphs.emplace_back(commandGraph);
        }
        if (!secondary_commandGraphs.empty())
        {
            commandGraphs = secondary_commandGraphs;
            commandGraphs.insert(commandGraphs.end(), primary_commandGraphs.begin(), primary_commandGraphs.end());
        }

        uint32_t numBuffers = 3;

分组键是 (device, queueFamily, presentFamily) 三元组(DeviceQueueFamily::operator< 见 :448-455),每组一个 RecordAndSubmitTask。

14.14.4 presentation 的 waitSemaphores 未串联(硬缺陷 H10)

// include/vsg/app/Presentation.h:24-30
        VkResult present();

        Windows windows;
        Semaphores waitSemaphores; // taken from RecordAndSubmitTasks.signalSemaphores

        ref_ptr<Queue> queue; // assign in application for GraphicsQueue from device
// src/vsg/app/Viewer.cpp:552-555
            auto presentation = vsg::Presentation::create();
            presentation->windows = activeWindows;
            presentation->queue = device->getQueue(deviceQueueFamily.presentFamily);
            presentations.emplace_back(presentation);

头文件注释明确写 waitSemaphores 取自 signalSemaphores,但 assignRecordAndSubmitTaskAndPresentation() 创建 Presentation 时只赋了 windows 与 queue,未接信号量。

14.15 多 task 的提交顺序与 present 等待

14.15.1 提交顺序即 vector 顺序

// src/vsg/app/Viewer.cpp:847-851
        for (auto& recordAndSubmitTask : recordAndSubmitTasks)
        {
            recordAndSubmitTask->submit(_frameStamp);
        }

串行路径下多个 RecordAndSubmitTask 按 recordAndSubmitTasks 的 vector 顺序逐个 submit();该顺序由 std::map<DeviceQueueFamily, CommandGraphs> 的键序决定,不是应用的传入顺序。

14.15.2 signalSemaphores / waitSemaphores 是未接线的钩子

waitSemaphores 与 signalSemaphores(include/vsg/app/RecordAndSubmitTask.h:40/:42)在 finish() 里分别进 wait 与 signal 列表,但默认装配路径没有把前者接到 Presentation::waitSemaphores。

14.15.3 present 的等待与 waitForFences

Presentation::present()(src/vsg/app/Presentation.cpp:30-41)对每个可见窗口把 renderFinishedSemaphore 加入 VkPresentInfoKHR.pWaitSemaphores,:43-47 在无 swapchain 时提前返回成功。

与前面章节交叉引用:第十三章预告第六问里 imageIndex 边界、vkDeviceWaitIdle 与 viewID 全局分配器(src/vsg/app/View.cpp:22-64)在本节汇合;Queue/Swapchain 代价留第十五章,分页器线程归第十九章。


14.16 threading/ 边界:Viewer 真正用到的接口

14.16.1 用得到与用不到的原语

// include/vsg/threading/Affinity.h:23-43 (节选)
    /// Affinity struct provides a set of cpu ids that a thread can be set to have affinity to.
    struct Affinity
    {
        ...
        std::set<uint32_t> cpus;
        operator bool() const { return !cpus.empty(); }
    };
    extern VSG_DECLSPEC void setAffinity(std::thread& thread, const Affinity& affinity);
    extern VSG_DECLSPEC void setAffinity(const Affinity& affinity);
// src/vsg/app/Viewer.cpp:772-791 里的线程容器
    std::list<std::thread> threads;   // include/vsg/app/Viewer.h:130

Viewer 在帧期只直接用 std::thread、FrameBlock、Barrier 三样,间接用 ActivityStatus 与 OperationQueue;Affinity/setAffinity、OperationThreads、Latch、DeleteQueue 在 src/vsg/app/Viewer.cpp 里零命中。

14.16.2 边界小结

threading/ 目录实测共 10 个头、3 个实现、1,081 行(本章规模表已逐行列出);Viewer 的帧循环只消费其中 FrameBlock.h(79)、ActivityStatus.h(42)、Barrier.h(78)、OperationQueue.h(156) 四个头的接口。

14.16.3 原语与容器的逐行不变量

前面各节引用了大量行号,这里把最容易误读的默认值和写回路径再逐行钉一次;每条只点名该行窗口内真实存在的成员,不按类名猜语义。

  • Barrier::_num_threads 是 const uint32_t(include/vsg/threading/Barrier.h:69),构造后不可改,参与者数量在 Barrier::create() 那一刻就冻结;arrive_and_drop()(include/vsg/threading/Barrier.h:50)只加计数不等待释放,一方提前退出就会让其余到达者永远挂在 _cv.wait() 上。
  • Barrier::_release() 先把 _num_arrived 清零、++_phase 再 _cv.notify_all()(include/vsg/threading/Barrier.h:62);等待方在 arrive_and_wait() 里先存 my_phase = _phase(include/vsg/threading/Barrier.h:44),谓词只认 phase 变化,因此清账不会把刚醒来的线程重新挂住。
  • ActivityStatus::active() 只是对 _active 的原子快照读,cancel() 是它的取反(include/vsg/threading/ActivityStatus.h:30);拿它当「此刻仍在编译」的强同步信号是误用。
  • Latch::set() 用 _count.exchange(0) 判断旧值是否非零(include/vsg/threading/Latch.h:37),count_down() 用 _count.fetch_sub(1) <= 1(include/vsg/threading/Latch.h:53);两者都按旧值决定是否 release(),但只有前者能把计数重新抬回正数。
  • FrameBlock::get() 在锁内直接返回 _value(include/vsg/threading/FrameBlock.h:43),它不比较指针;只有 wait_for_change() 用 _value == value 判新帧,把 get() 当成阻塞等待会立刻返回旧值。
  • RecordAndSubmitTask 构造时把 _indices 每个元素填成 numBuffers 作「未设置」哨兵(src/vsg/app/RecordAndSubmitTask.cpp:29),_fences 则 resize(numBuffers) 后逐个 Fence::create()(src/vsg/app/RecordAndSubmitTask.cpp:32);传 0 时两容器皆空,后续取模直接除零。
  • RecordAndSubmitTask::finish() 在 src/vsg/app/RecordAndSubmitTask.cpp:161 才把 late 传输结果与 lateDataTransferredSemaphore 接上,record() 恒返回 VK_SUCCESS,录制阶段没有错误上抛通道。
  • acquireNextFrame() 在 VK_SUBOPTIMAL_KHR 分支调 window->resize()(src/vsg/app/Viewer.cpp:228),而基类实现是空函数体,既没重配 swapchain 也没改尺寸,循环只能等下一次 acquireNextImage() 自己返回成功才退出。
  • RecordTraversal::apply(const View&) 一进函数就 state->dirtyStateStacks()(src/vsg/app/RecordTraversal.cpp:564),把状态栈标脏后再写 viewID 与 viewDependentState;退出只恢复 traversalMask,脏标记本身不撤销。
  • CompileManager::compile() 把 reserve_result 初始化为 VK_INCOMPLETE(src/vsg/app/CompileManager.cpp:265),池空提前返回时 CompileResult::result 保留该默认值,requiresViewerUpdate() 见它就判「无需更新」。
  • Context::waitForCompletion() 的 fence->wait(timeout) 在 VK_TIMEOUT 上无限重试(src/vsg/vk/Context.cpp:388),只有非超时错误打完日志就继续清空 commands;这与帧期 wait(UINT64_MAX) 的静默策略正好相反。
  • Fence::resetFenceAndDependencies() 遍历 _dependentSemaphores 把每个 numDependentSubmissions 归零后再 clear()(src/vsg/vk/Fence.cpp:42),依赖记账由栅栏自己维护,不依赖 task 侧同步。
  • TransferTask 构造时给 _earlyDataToCopy 命名并建 numBuffers 个 TransferBlock(src/vsg/app/TransferTask.cpp:29),early/late 两个队列从构造起就分离;后续用 TRANSFER_ALL 合并结果属于人为覆盖。
  • _threading 默认 false(include/vsg/app/Viewer.h:165),与 _frameBlock/_submissionCompleted 同处 protected 段,但 status 是 public,外部可单独翻转其中一个而不通知另外两个。

Barrier::arrive_and_wait() 把加锁、计数、释放或等待压在十三行里,_num_threads 一经构造便固定:

// include/vsg/threading/Barrier.h:37-47
            std::unique_lock lock(_mutex);
            if (++_num_arrived == _num_threads)
            {
                _release();
            }
            else
            {
                auto my_phase = _phase;
                _cv.wait(lock, [this, my_phase]() { return this->_phase != my_phase; });
            }

读完能确认一处不对称:_num_arrived 用 == 与 _num_threads 比较,多一个到达者越过后就再也不会触发 _release(),而 ++_phase(include/vsg/threading/Barrier.h:65)只在相等分支发生。

Fence::resetFenceAndDependencies() 在清空依赖表之前先把每个信号量的提交计数归零:

// src/vsg/vk/Fence.cpp:52-56
    _dependentSemaphores.clear();
    _dependentCommandBuffers.clear();

    reset();

reset() 排在两次 clear() 之后:归零先于 Vulkan 侧 vkResetFences,依赖表的生命周期完全由 CPU 端显式管理,task 侧不参与。

数字表与源码索引

按文件分组,逐条给出 完整路径:行区间 与可复核结论。所有路径均已用 os.path.isfile 校验,行号写作前用 sed -n/grep -n 复核。

src/vsg/app/Viewer.cpp(892 行)

行区间结论
src/vsg/app/Viewer.cpp:30-39构造初始化 6 个成员,compileManager/_frameBlock 留空
src/vsg/app/Viewer.cpp:41-73析构先停线程再 deviceWaitIdle();两路设备来源判空不对称
src/vsg/app/Viewer.cpp:105-138close() 三处状态翻转;active() 失效时阻塞等待
src/vsg/app/Viewer.cpp:155-206advanceToNextFrame() 六件事串联,每个 task advance()
src/vsg/app/Viewer.cpp:208-246acquireNextFrame() 无界重试循环,基类 resize() 为空
src/vsg/app/Viewer.cpp:278-418compile() 的收集、bin 补齐、compileTask 分派
src/vsg/app/Viewer.cpp:327-347第一处 view->bins 补齐
src/vsg/app/Viewer.cpp:420-575按 (device, queueFamily, presentFamily) 分组装配 task
src/vsg/app/Viewer.cpp:501numBuffers = 3 硬编码
src/vsg/app/Viewer.cpp:552-555Presentation 创建时未赋 waitSemaphores
src/vsg/app/Viewer.cpp:598-621numValidTasks、Barrier::create(1 + numValidTasks)
src/vsg/app/Viewer.cpp:626-646简单路径恒假分支与唯一 arrive_and_drop()
src/vsg/app/Viewer.cpp:648-768SharedData、三条 lambda、recordStart/Completed 屏障
src/vsg/app/Viewer.cpp:772-791stopThreading() 唤醒与 join
src/vsg/app/Viewer.cpp:793-818update() 四步顺序
src/vsg/app/Viewer.cpp:820-852recordAndSubmit() 的 #if 1 与两条分支
src/vsg/app/Viewer.cpp:854-862present() 只遍历 presentations
src/vsg/app/Viewer.cpp:887-892updateViewer() 只转调 updateTasks()

src/vsg/app/RecordAndSubmitTask.cpp(365 行)与头文件

行区间结论
src/vsg/app/RecordAndSubmitTask.cpp:21-44三个哨兵槽、numBuffers 个 fence、transferTask 必建
src/vsg/app/RecordAndSubmitTask.cpp:46-71advance() 的 _indices 右移与回绕
src/vsg/app/RecordAndSubmitTask.cpp:73-83index()/fence() 的越界到空指针映射
src/vsg/app/RecordAndSubmitTask.cpp:85-114submit() 四段编排
src/vsg/app/RecordAndSubmitTask.cpp:116-147start() 的 wait(UINT64_MAX) 与 fence 复位
src/vsg/app/RecordAndSubmitTask.cpp:149-159record() 恒返回 VK_SUCCESS
src/vsg/app/RecordAndSubmitTask.cpp:187-195空缓冲 sleep_for(16ms)
src/vsg/app/RecordAndSubmitTask.cpp:212-224early/late 信号量与退还
src/vsg/app/RecordAndSubmitTask.cpp:228-240imageIndex 边界与 renderFinishedSemaphore
src/vsg/app/RecordAndSubmitTask.cpp:242-253dependentSemaphores() 覆盖赋值缺陷
src/vsg/app/RecordAndSubmitTask.cpp:266-280VkSubmitInfo 装配与 queue->submit
src/vsg/app/RecordAndSubmitTask.cpp:296-365updateTasks() 的分派与第二处 bin 补齐
include/vsg/app/RecordAndSubmitTask.h:30numBuffers = 3 默认值
include/vsg/app/RecordAndSubmitTask.h:72-74_currentFrameIndex/_indices/_fences

include/vsg/threading/(同步原语)

行区间结论
include/vsg/threading/FrameBlock.h:27-47initial_value 空帧、指针相等判定、set/get
include/vsg/threading/FrameBlock.h:49-56active() 无判空、wake() 不改 _value
include/vsg/threading/FrameBlock.h:57-67wait_for_change() 的 while 与引用参数
include/vsg/threading/ActivityStatus.h:24-38atomic_bool、exchange、cancel()
include/vsg/threading/Barrier.h:35-67arrive_and_wait/arrive_and_drop/_release,无超时
include/vsg/threading/Latch.h:51-76count_down() 可越过 0 变负,Viewer 未用
include/vsg/threading/Affinity.h:39-43setAffinity 声明,Viewer 零调用

src/vsg/app/TransferTask.cpp(880 行)与 CompileManager.cpp(447 行)

行区间结论
src/vsg/app/TransferTask.cpp:23-39_earlyDataToCopy/_lateDataToCopy 与 frames 槽
src/vsg/app/TransferTask.cpp:340-348TRANSFER_ALL 结果被 late 覆盖
src/vsg/app/TransferTask.cpp:350-444锁内等待 fence、frameIndex 轮转
src/vsg/app/TransferTask.cpp:481-487map 失败返回 VK_SUCCESS
src/vsg/app/TransferTask.cpp:521-550消费者完成信号量的 wait/signal 闭环
include/vsg/app/TransferTask.h:61minimumStagingBufferSize = 16MB
src/vsg/app/CompileManager.cpp:37-58add() 的 break 缺陷
src/vsg/app/CompileManager.cpp:60-83requiresViewerUpdate() 四判据
src/vsg/app/CompileManager.cpp:130-146numCompileTraversals = 1 的 #if 0
src/vsg/app/CompileManager.cpp:257-280拿不到 CompileTraversal 时静默返回
src/vsg/app/CompileManager.cpp:392-447compileTask() 新建遍历 + waitForCompletion()
src/vsg/vk/Context.cpp:385-4051 秒 VK_TIMEOUT 无限重试循环

其它交叉引用文件

行区间结论
include/vsg/app/Viewer.h:82/91/94三个管理器的 public 字段
include/vsg/app/Viewer.h:116/120/129-130task/presentation 容器、status、threads
include/vsg/app/Viewer.h:166-167_frameBlock/_submissionCompleted
src/vsg/app/RecordTraversal.cpp:559-669apply(View&) 先 state->dirtyStateStacks() 再存 cached_traversalMask,恢复只动一项
src/vsg/app/RecordTraversal.cpp:701-703addToBin() 无边界检查
src/vsg/app/CommandGraph.cpp:76-140命令缓冲池只增不减、每图一个 RecordTraversal
src/vsg/vk/CommandBuffer.cpp:94-101add() 带 scoped_lock,并发安全
src/vsg/app/RenderGraph.cpp:105-118第二个 resize 触发点
src/vsg/app/RenderGraph.cpp:208静态视口 resize 的 vkDeviceWaitIdle
src/vsg/app/Presentation.cpp:30-41present 的 renderFinishedSemaphore 等待
src/vsg/vk/Fence.cpp:40-66依赖记账闭环与 vkWaitForFences
include/vsg/ui/FrameStamp.h:28-35帧三字段,每帧新建对象
include/vsg/app/Window.h:59基类 resize() 空实现
src/vsg/app/View.cpp:22-64viewID 全局分配器与 releaseViewID()

可复现验证

以下命令均可在仓库根目录 VulkanSceneGraph-1.1.16 直接执行,注释给出期望结果。

# 期望:Viewer.cpp 892、RecordAndSubmitTask.cpp 365、FrameBlock.h 79、TransferTask.cpp 880
wc -l src/vsg/app/Viewer.cpp src/vsg/app/RecordAndSubmitTask.cpp \
      include/vsg/threading/FrameBlock.h src/vsg/app/TransferTask.cpp
# 期望:命中 CompileManager.cpp:50 的 break,且下一行是 views[src_view]
grep -n "indices.empty() && src_binDetails.bins.empty()) break" src/vsg/app/CompileManager.cpp
# 期望:TransferTask.cpp:487 出现 if (result != VK_SUCCESS) return TransferResult{VK_SUCCESS, {}};
sed -n '483,488p' src/vsg/app/TransferTask.cpp
# 期望:六七个主题清单用词全部输出「0 处」
for kw in _framesInFlight earlyTransferTask lateTransferTask _currentTransferIndex startThread waitForFrame; do
  printf "%-22s : %s 处\n" "$kw" "$(grep -rn "$kw" include/ src/ | wc -l)"
done
# 期望:833 行为 #if 1、839 行为 if (_threading && _frameStamp->frameCount > 2)
sed -n '833,840p' src/vsg/app/Viewer.cpp
# 期望:arrive_and_drop 全库仅 Viewer.cpp:642 一处调用
grep -rn "arrive_and_drop" include/ src/
# 期望:第 94-101 行 add() 内含 std::scoped_lock,证明 RecordedCommandBuffers 并发安全
sed -n '87,101p' include/vsg/vk/CommandBuffer.h
sed -n '94,101p' src/vsg/vk/CommandBuffer.cpp
# 期望:_num_threads 为 const、_release 清账并 ++phase;Latch 两种减计数都在
grep -n "const uint32_t _num_threads\|void _release()\|++_phase" include/vsg/threading/Barrier.h
grep -n "_count.exchange(0)\|_count.fetch_sub(1)" include/vsg/threading/Latch.h
# 期望:finish 在 161、dirtyStateStacks 在 564、reserve_result 初值 VK_INCOMPLETE 在 265
grep -n "RecordAndSubmitTask::finish" src/vsg/app/RecordAndSubmitTask.cpp
grep -n "dirtyStateStacks" src/vsg/app/RecordTraversal.cpp
grep -n "reserve_result = VK_INCOMPLETE" src/vsg/app/CompileManager.cpp
# 期望:字符数落在 80000-100000,围栏数为偶数,无追加标记残留
python3 -c "
s=open('docs/series/14-Viewer与线程模型.md',encoding='utf-8').read()
print('chars',len(s),'fences',s.count(chr(96)*3),'append',s.count('<!-- APP'+'END -->'))"

陷阱表与批判性结论

#陷阱位置(完整路径:行号)触发条件与后果规避
1无界重试循环src/vsg/app/Viewer.cpp:220-242、include/vsg/app/Window.h:59OUT_OF_DATE 后 resize() 空实现仍返回过期,主线程永久卡死加 maxRetries 与超时
2单 CommandGraph 分支恒假src/vsg/app/Viewer.cpp:626、src/vsg/app/RecordAndSubmitTask.cpp:38transferTask 必建导致 !task->transferTask 永假,20 行死代码改判据或删分支
3#if 1 编译期死代码src/vsg/app/Viewer.cpp:833-840前三帧单线程降级无法在运行期启用提为运行时开关
4break 误用src/vsg/app/CompileManager.cpp:50第一个空 binDetails 截断后续全部 view,帧期 addToBin 越界改 continue
5map 失败返回成功src/vsg/app/TransferTask.cpp:487staging 映射失败被吞,动态数据不上传却继续渲染返回真实 result
6TRANSFER_ALL 结果覆盖src/vsg/app/TransferTask.cpp:345-346late 覆盖 early 的完成信号量,早传输与图形命令竞态分别返回或累加
7View 状态恢复不对称src/vsg/app/RecordTraversal.cpp:569-570、:663-668嵌套 View 后 viewID/viewDependentState 残留,绑错管线实现对称缓存恢复
8active() 无判空 + lost-wakeupinclude/vsg/threading/FrameBlock.h:49、src/vsg/app/Viewer.cpp:783-784status 置假与 wake() 分步,退出时可能永久阻塞 join状态与通知同一临界区
9Barrier 无超时无复位include/vsg/threading/Barrier.h:35-47、src/vsg/app/Viewer.cpp:843少一个到达者即永久死锁,异常路径不回滚加超时与强制 _release()
10numBuffers = 0 越界除零src/vsg/app/RecordAndSubmitTask.cpp:130、src/vsg/app/TransferTask.cpp:444构造传 0 导致空 fence 解引用、% frames.size() 除零构造断言 numBuffers >= 1
11dependentSemaphores() 覆盖src/vsg/app/RecordAndSubmitTask.cpp:248-252覆盖丢掉 renderFinishedSemaphore 记账、signal 存两遍删 :248 整体赋值
12空缓冲固定 16ms 睡眠src/vsg/app/RecordAndSubmitTask.cpp:193窗口隐藏时无条件睡 16 毫秒,与刷新率无关交回 swapchain/条件变量
13编译请求静默丢失src/vsg/app/CompileManager.cpp:273-280、include/vsg/app/CompileManager.h:29take_when_available() 取不到 compileTraversal 时只打一行 debug 就 return result,result 仍是 VK_INCOMPLETE,requiresViewerUpdate() 判成无需更新返回明确错误并回退
14bin 补齐写两遍src/vsg/app/Viewer.cpp:327-347、src/vsg/app/RecordAndSubmitTask.cpp:344-364同构代码两处,改一处漏一处即不一致抽为单一函数
15Presentation::waitSemaphores 未接线include/vsg/app/Presentation.h:27、src/vsg/app/Viewer.cpp:552-555注释称取自 signalSemaphores,实际装配未赋值补赋值或改注释
16addToBin() 无边界检查src/vsg/app/RecordTraversal.cpp:703binNumber 越界时 bins[...] 越界,与陷阱 4 叠加判索引范围
17屏障参与者数不可变 + drop 不回滚include/vsg/threading/Barrier.h:69、include/vsg/threading/Barrier.h:50_num_threads 为 const,构造后冻结;一方走 arrive_and_drop() 提前退出,余下到达者凑不齐计数,永久停在 _cv.wait()把 drop 改成带超时的 arrive_and_wait(),或在异常路径强制 _release()
18active() 被当作强同步信号include/vsg/threading/ActivityStatus.h:30active() 只是 _active 的原子快照,cancel() 为其取反;读到 true 不代表编译或传输未出错,据此推进帧会漏掉静默失败让 CompileResult 成为唯一成功判据,不再用 active() 推断结果
19numBuffers 兼作哨兵与容量src/vsg/app/RecordAndSubmitTask.cpp:29、src/vsg/app/RecordAndSubmitTask.cpp:32_indices 元素填 numBuffers 表示未设置,_fences 又按它 resize();传 0 时两容器皆空,index() 的取模除零、空 fence 解引用构造断言 numBuffers >= 1,用独立哨兵值
20reserve_result 默认值上传src/vsg/app/CompileManager.cpp:265reserve_result 初值即 VK_INCOMPLETE,池空或 reserve 失败时仍写进 CompileResult::result,requiresViewerUpdate() 判成无需更新让 compile() 返回显式错误码,不依赖默认值传递

三条批判性结论

第一,本章全部硬缺陷共享一个根源:Viewer 把「状态」拆散在四个互不校验的数据源里,同步靠拓扑约束而非类型或断言保证。 _close(include/vsg/app/Viewer.h:154)、status(:129)、_threading(:165)、_frameBlock(:166)表达的是同一组生命周期状态,却没有单一状态机:close() 改前三者、setupThreading() 改后三者、stopThreading() 只改 _threading 与 status,active() 只看 _close 与窗口。于是 status 是 public 字段,应用可以 viewer->status->set(false) 绕过 close() 直接停记录线程,此时 _threading 仍为真,recordAndSubmit() 照样走 _frameBlock->set() 分支,_submissionCompleted->arrive_and_wait() 永远凑不齐 1 + numValidTasks 个到达者,主线程死锁——而这只是四个数据源不同步的一种组合。帧期的正确性还额外依赖「每个 task 恰好一条 primary 线程」「RecordedCommandBuffers 自带锁」「每帧新建 FrameStamp 对象」三条拓扑约束,任何一条被打破都没有断言拦截。收敛方向是把生命周期收进一个枚举状态机、把 status 设为 protected、在 recordAndSubmit() 入口校验 _frameBlock 与 _submissionCompleted 非空;在此之前,第十四章的正确性与第十二章「编译池只有一个实例」、第九章「零 VkPipelineCache」同属用拓扑换代码简单。

第二,编译期与帧期用了两套语义不同却互不知晓的 fence 等待与错误传播策略。 编译期 CompileManager::compileTask()(src/vsg/app/CompileManager.cpp:430-433)调 CompileTraversal::waitForCompletion(),落到 Context::waitForCompletion()(src/vsg/vk/Context.cpp:385-405)的 timeout = 1000000000 一秒轮询、while (result == VK_TIMEOUT) 无限重试,非 VK_TIMEOUT 的错误只打印一行就照样清空 commands/copyImageCmd/copyBufferCmd;帧期 RecordAndSubmitTask::start()(src/vsg/app/RecordAndSubmitTask.cpp:134-137)则用 wait(UINT64_MAX) 一次性无限等,且 submit()/start()/finish() 的 VkResult 在 Viewer::recordAndSubmit()(:849)与三个 lambda 里全被丢弃。两者调用同一个 Fence::wait()(src/vsg/vk/Fence.cpp:58-61),却一个可观察超时、一个完全静默,一个只在 VK_TIMEOUT 重试、一个把错误码丢掉。更糟的是 TransferTask::_transferData()(:487)把 staging map 失败返回成 VK_SUCCESS,CompileManager::compile()(:273-280)把池空返回成 VK_INCOMPLETE,requiresViewerUpdate()(:62)又把 VK_INCOMPLETE 判成「无需更新」——三层静默降级串起来,结果是动态编译失败或数据传输失败时 Viewer 照常推进帧,只在 instrumentation 日志里留痕。修法不是逐处打补丁,而是让 CompileResult 成为唯一的错误通道,帧期 VkResult 一律经它上抛,主循环在 advanceToNextFrame() 里检查。

第三,「每帧新建 FrameStamp 并用 ref_ptr 指针相等判定新帧」把线程同步的正确性押在了一个跨模块的隐式契约上,同时把状态保存/恢复做成人工配对。 FrameBlock::wait_for_change()(include/vsg/threading/FrameBlock.h:57-67)用 _value == value 判变化,set() 与 wake() 都 notify_all() 但只有前者改 _value;这个设计能成立,唯一前提是 Viewer::advanceToNextFrame() 每帧 FrameStamp::create(...)(src/vsg/app/Viewer.cpp:181/:191)造新对象,从不复用。任何复用 FrameStamp 只改 frameCount 的优化都会让所有记录线程永久停在 cv.wait(),而 FrameBlock 的接口既没有注释这条前提、也没有断言。同一类人工配对出现在 RecordTraversal::apply(const View&)(src/vsg/app/RecordTraversal.cpp:567-570 写入三样、:663-668 只恢复一样)、RecordAndSubmitTask::finish()(:226 clear、:239 push、:248 整体覆盖、:252 再 push)以及 Viewer::compile() 与 updateTasks() 两处重复的 bin 补齐。这些配对没有 ScopeGuard、没有 RAII、没有单一数据源,全靠作者逐处手写且逐处保持一致——第十三章批判「视图层全部硬缺陷共享一个根源」时给出的收敛方向(把上下文切换抽成 ScopeGuard、把累积队列收进可整体 clear() 的结构)在第十四章同样适用,而且因为叠加了多线程,漏一处的代价从「渲染错」升级成「永久死锁」。


下章预告

本章结束。下一章精确对齐 README 第 15 章标题「提交与呈现:Queue、SubmitCommands、Swapchain、Presentation」,要回答本章留下的五个具体问题:

  • RecordAndSubmitTask::finish() 把 VkSubmitInfo 交给 queue->submit(submitInfo, current_fence)(src/vsg/app/RecordAndSubmitTask.cpp:279),Queue::submit 内部怎样转成 vkQueueSubmit?SubmitCommands(第七章)与本章 recordedCommandBuffers->buffers()(:204)的顺序在 vk/ 层由谁最终保证?
  • Window::acquireNextImage()(src/vsg/app/Window.cpp:437-470)里 availableSemaphore.swap(...) 与 _indices 移位怎样与 frame.imageAvailableSemaphore(src/vsg/app/RecordAndSubmitTask.cpp:235)、renderFinishedSemaphore(:238)配成一条完整的 wait/signal 链?VK_SUBOPTIMAL_KHR 在本章 acquireNextFrame() 被当作可重试状态(:225),第 15 章怎样看待它与 present 模式的关系?
  • Presentation::present()(src/vsg/app/Presentation.cpp:49-73)的 VkPresentInfoKHR 没有 pResults,多窗口 present 的部分失败怎样被发现?queue->present() 与图形 queue->submit() 不是同一 Queue 时(src/vsg/app/Viewer.cpp:544/:554 分别取 mainQueue 与 presentQueue)需要怎样的队列族所有权转移?
  • 本章 numBuffers = 3(src/vsg/app/Viewer.cpp:501)与 swapchain 的 minImageCount/maxFramesInFlight 不一致时,谁决定真正的在飞帧数?waitForFences()(:248-263)与 vkDeviceWaitIdle()(:51-73)在 vk/ 层的代价差多少,以本机 Vulkan SDK 实测为准?
  • 本章 14.10.4 的 dependentSemaphores() 覆盖缺陷(:248-252)在二进制信号量与 timeline semaphore 两种实现下后果是否相同?第 15 章讲 Queue、Swapchain、Presentation 时,signalSemaphores/waitSemaphores 这两个「未接线钩子」(include/vsg/app/RecordAndSubmitTask.h:40/:42)该怎样补成多 task 串联?

Viewer 把一帧拆成推进、更新、记录提交、呈现四段,用 FrameBlock 与 Barrier 把记录线程收敛到屏障上;而这些命令缓冲最终怎样被 Queue 消费、image 怎样被获取与呈现、present 模式怎样反过来约束在飞帧数,是第十五章的主线。