《VulkanSceneGraph 1.1.16 源码深度解析》第十六章 同步原语与延迟删除:Barrier、Latch、FrameBlock

0 阅读1小时+

《VulkanSceneGraph 1.1.16 源码深度解析》第十六章 同步原语与延迟删除:Barrier、Latch、FrameBlock、DeleteQueue

16.0 先把规模和答案摆出来

第十五章收尾留下六个问题,全部指向帧期阻塞、唤醒、放行、销毁由谁实现。本章逐行回答,依据全部是本机的 wc -l、grep -n、sed -n 实测值。

先把六行预告与本章的落点对齐,读者可以带着这个对照表往下核对:

  • 预告第一问:FrameBlock::wait_for_change()(include/vsg/threading/FrameBlock.h:57-67)用 _value == value 指针相等判变化,为什么前提是每帧 FrameStamp::create(...)(src/vsg/app/Viewer.cpp:181/191)造新对象?16.7.3 答案:循环里没有帧号比较,比的是 ref_ptr 裸指针;复用 FrameStamp 只改 frameCount 会让四个记录线程(src/vsg/app/Viewer.cpp:636/686/717/736)永久停在 :62 的 _cv.wait(lock),主线程 :843 随后一并卡死。
  • 预告第二问:Barrier 的 1 + numValidTasks(src/vsg/app/Viewer.cpp:621)为何必须与主线程 :843 配对?16.4.3 答案:每个 task 每帧贡献一次到达(:642 或 :706),主线程补最后一次;少一次到达则 _num_arrived 凑不齐 const uint32_t _num_threads(include/vsg/threading/Barrier.h:69),_phase 不递增,全体永久阻塞。
  • 预告第三问:Latch::count_down() 与 FrameBlock::wake() 都用 notify_all(),stopThreading()(src/vsg/app/Viewer.cpp:772-791)如何保证退出?16.7.4–16.7.5 答案:靠「同一把 _mutex + ActivityStatus 原子位 + while 每轮重读状态」,wake() 取 :53 的锁发通知,set(false)(:783)让 :60 的第二项为假,与 set 和 wake 的先后无关。
  • 预告第四问:retainForFrameCount = 3(include/vsg/threading/DeleteQueue.h:39)与 numBuffers = 3(src/vsg/app/Viewer.cpp:501)、imageCount = 3(include/vsg/vk/Swapchain.h:37)谁保证不早于 GPU 用完?16.9 答案:没有任何一处;retainForFrameCount 全库零处外部赋值,DeleteQueue::frameCount 只由 src/vsg/io/DatabasePager.cpp:665 从 _frameStamp 灌入,与 fence 无数据通路。
  • 预告第五问:Fence::resetFenceAndDependencies()(src/vsg/vk/Fence.cpp:40-56)按 exchange(0) 归零依赖与 DeleteQueue 按帧数保留如何统一?16.17 答案:两套判据无共享变量;src/vsg/app/RecordAndSubmitTask.cpp:248 的整体赋值冲掉 :239 的 renderFinishedSemaphore 后冲突只能在 unref() 的先后次序里临时裁决。
  • 预告第六问:CommandGraph::_commandBuffers、SwapchainImage、Surface::release() 三类「谁负责删」与 DeleteQueue 如何叠加?16.10 答案:ObjectToDelete 持 ref_ptr<Object>(include/vsg/threading/DeleteQueue.h:33),clear() 触发的 unref() 走 src/vsg/core/Object.cpp:84-94 与 :241-244 的 Allocator;GPU 句柄销毁不经过 DeleteQueue。

先给可复核的规模。include/vsg/threading/ 有 9 个头文件、743 行,src/vsg/threading/ 有 3 个实现文件、338 行,合计 12 个文件、1,081 行(实测 wc -l include/vsg/threading/*.h src/vsg/threading/*.cpp | tail -1 输出 1081 total)。本章正面处理的 20 个文件共 5,075 行,逐行如下,路径全部用 os.path.isfile 复核过:

文件完整路径wc -l本章角色
include/vsg/threading/ActivityStatus.h4216.2 逐字段推导 _active.exchange 与 active() 的原子读,判定它是全库唯一退出开关
include/vsg/threading/Affinity.h4516.15 展开 Affinity::cpus 与两个 setAffinity 声明,核对四平台实现分支
include/vsg/threading/Barrier.h7816.3 逐分支推导 arrive_and_wait / arrive_and_drop / _release,定位无超时与无复位
include/vsg/threading/DeleteQueue.h13616.8 展开四个 add/prune 入口、ObjectToDelete 与三个公开计数器
include/vsg/threading/FrameBlock.h7916.7 推导 set/get/active/wake/wait_for_change 五个方法与指针相等契约
include/vsg/threading/Latch.h9516.5 推导 count_down 的 <= 1 判据、set 双分支与 wait 的检查-等待协议
include/vsg/threading/OperationQueue.h15616.16 作为对照组的 take_when_available() 100 ms 超时与 take_all() 交换语义
include/vsg/threading/OperationThreads.h6016.16 核对 stop() 与析构的叠加调用
include/vsg/threading/atomics.h5216.13.4 清点四个模板函数,判定其中两个零调用
src/vsg/threading/Affinity.cpp15416.15 逐平台读取,定位返回值丢弃与 Android/CYGWIN/OHOS 空实现
src/vsg/threading/DeleteQueue.cpp12116.8.4–16.8.7 展开 advance / wait_then_clear / clear / 析构四条路径
src/vsg/threading/OperationThreads.cpp6316.16 推导 runThread 循环与 stop() 二次 join() 的后果
include/vsg/app/Viewer.h17416.4 核对 status、threads、_frameBlock、_submissionCompleted 四个成员的声明位置
src/vsg/app/Viewer.cpp89216.4 / 16.11 逐帧排演 setupThreading、三个 run_* lambda、recordAndSubmit 与 stopThreading
include/vsg/io/DatabasePager.h18016.12 核对 deleteQueue、frameCount、numActiveRequests 的公开成员布局
src/vsg/io/DatabasePager.cpp79216.12 定位 DeleteQueue 的四个真实装配/使用点(:498、:623、:665、:791)
src/vsg/app/RecordAndSubmitTask.cpp36516.11 / 16.17 核对 advance()、fence() 与 :248 的整体赋值
src/vsg/vk/Fence.cpp6616.17 展开 resetFenceAndDependencies() 的两轮 exchange(0)
src/vsg/commands/ExecuteCommands.cpp8316.6 推导 reset() / completed() / record() 三拍里的 Latch 计数
src/vsg/io/read.cpp22316.6 推导 ReadOperation::run() 的异常路径与 latch->wait() 的配对

16.0.1 本章的问题清单

指针相等为何能当帧判据、复用 FrameStamp 停在哪行(16.7.3、16.11.1);_phase 递增能否替代复位、arrive_and_drop 有无退出语义(16.3.2、16.3.4);1 + numValidTasks 里的 1 落在哪次调用(16.4.3、16.4.4);count_down() 的 <= 1 在计数为 0 或负时返回什么(16.5.2、16.6.2);wait() 无谓词循环配 release() 持锁通知是否正确、异常漏减的后果(16.5.3、16.6.3);wake() 不改 _value 为何能放行(16.7.5);DeleteQueue 在哪个目录、空 FrameStamp 传入 advance() 会怎样(16.8.1、16.8.4);wait_then_clear() 为何把删除绑在帧号变化上(16.8.5);find_if 的有序假设(16.9.2);prune() 为何被静默跳过(16.8.5、16.8.6);三个 3 有无引用关系(16.9.3);ref 用 relaxed、unref 用 seq_cst 是否写反(16.13.2);6 处 condition_variable 哪两处带超时(16.14.3);setAffinity 为何零调用且丢返回值(16.15.3、16.15.4);两套删除判据如何不互相踩踏(16.17.3)。

16.0.2 答案骨架

先把结论列在这里,后面逐条用源码展开。表中「性质」一列按本章的判定标准区分:凡能给出触发条件、后果与规避路径的记为硬缺陷,凡属于用简单拓扑换代码量的记为设计取舍,凡只是接口边界容易被误读的记为接口边界。

#结论主要证据(完整路径:行号)性质
1wait_for_change() 用 _value == value 的裸指针相等判变化,成立前提是每帧 FrameStamp::create() 造新对象;复用对象只改 frameCount 会让四个记录线程永久停在 _cv.wait(lock),并连带卡死主线程include/vsg/threading/FrameBlock.h:60/62、src/vsg/app/Viewer.cpp:181/191、src/vsg/app/Viewer.cpp:636/686/717/736、src/vsg/app/Viewer.cpp:843硬缺陷(隐性契约)
2Barrier 无超时、无复位、异常不回滚,_num_threads 为 const 且 _release() 不调整;任一参与者提前退出即让主线程 arrive_and_wait() 永久阻塞include/vsg/threading/Barrier.h:35-47/62-67/69、src/vsg/app/Viewer.cpp:621/843硬缺陷(无超时死锁)
3arrive_and_drop() 仍把到达计入 _num_arrived,既不减 _num_threads 也不登记退出;全库唯一调用点每帧都调,实际语义是「到达但不等待」,与名字承诺的「退出后不再参与」相反include/vsg/threading/Barrier.h:50-57/64、src/vsg/app/Viewer.cpp:642硬缺陷(API 语义落差)
4count_down() 的 fetch_sub(1) <= 1 在计数已为 0 或负时仍 release() 并返回 true,计数可下溢并重复通知;ExecuteCommands 以 create(0) 起步、completed() 无条件减一,正好踩中include/vsg/threading/Latch.h:53-56、src/vsg/commands/ExecuteCommands.cpp:18/65、include/vsg/threading/Latch.h:78-82硬缺陷(计数下溢)
5ReadOperation::run() 在 vsg::read() 抛异常时跳过 latch->count_down(),而 latch->wait() 无超时,批量读路径会永久阻塞;OperationThreads 的线程函数同样没有 try/catchsrc/vsg/io/read.cpp:147-151/172、src/vsg/threading/OperationThreads.cpp:23-32硬缺陷(异常路径不回滚)
6DeleteQueue::advance() 直接解引用 frameStamp->frameCount,而它的唯一调用者用 frameStamp ? ... : 0 显式容忍空值,传入的 _frameStamp 在首帧 advanceToNextFrame() 之前可为空,构成空指针解引用src/vsg/threading/DeleteQueue.cpp:36、src/vsg/io/DatabasePager.cpp:664-665、src/vsg/app/Viewer.cpp:804硬缺陷(空指针)
7wait_then_clear() 把「帧号变化」写成退出等待的必要条件,而 add() 只 notify_one() 不改 frameCount;帧停止推进后即使对象到期也不再删除,_objectsToDelete 只增不减src/vsg/threading/DeleteQueue.cpp:53-59、include/vsg/threading/DeleteQueue.h:47-52、src/vsg/threading/DeleteQueue.cpp:63硬缺陷(唤醒条件错绑 / 容器只增不减)
8wait_then_clear() 与 clear() 都只在 numObjectsToDelete > 0 时才调用 sharedObjects->prune(),而 add_prune 的调用方允许「只 prune 不 delete」,该情形下 prune 请求被静默丢弃src/vsg/threading/DeleteQueue.cpp:72-79/109-116、src/vsg/io/DatabasePager.cpp:791硬缺陷(静默降级 / 错误分支)
9setAffinity 全库零调用,四个平台分支全部丢弃底层 API 返回值,Android/CYGWIN/OHOS 三平台为空实现静默降级;atomics.h 的 exchange_if_lower 与 exchange_multiply 同样零调用src/vsg/threading/Affinity.cpp:44/88/101-111/141、include/vsg/threading/atomics.h:22/38硬缺陷(死代码 / 静默降级)
10三个 3 互不引用,retainForFrameCount 全库无外部赋值;它与 Fence::resetFenceAndDependencies() 按 exchange(0) 归零依赖构成两套彼此看不见的回收判据src/vsg/app/Viewer.cpp:501、include/vsg/vk/Swapchain.h:37、include/vsg/threading/DeleteQueue.h:39、src/vsg/vk/Fence.cpp:40-56设计取舍(隐式契约)

这十条里第 1–9 条是硬缺陷,第 10 条是设计取舍,第 3 条同时是接口边界。陷阱表与批判性结论补上那些不足以单列一条的边界:OperationThreads::stop() 的二次 join()、FrameBlock 允许空 ActivityStatus、find_if 的单调假设、frameCount 被外部改小、Affinity 在 64 核以上的移位宽度。

16.0.3 阅读路线

ActivityStatus → Barrier → Viewer::setupThreading → Latch → read.cpp / ExecuteCommands → FrameBlock → DeleteQueue → 三个 3 → ref_ptr/Object/Allocator → Viewer 主循环 → DatabasePager → 内存序与同步设施 → Affinity/线程名/Tracy → OperationQueue 对照组 → Fence → 硬结论。


16.1 目录清点:threading 的 12 个文件与不存在的 AtomicStack

16.1.1 include 侧九个头文件逐行职责

先把实测清单摆出来。find include/vsg/threading src/vsg/threading -type f | sort 给出 12 行,wc -l include/vsg/threading/* 给出 743 total,wc -l src/vsg/threading/* 给出 338 total。九个头文件按行数排序是:

头文件完整路径行数主要声明本章处理节
include/vsg/threading/ActivityStatus.h42ActivityStatus、四个方法、std::atomic_bool _active16.2
include/vsg/threading/Affinity.h45Affinity、setAffinity(std::thread&, ...)、setAffinity(...)16.15
include/vsg/threading/Barrier.h78Barrier、arrive_and_wait、arrive_and_drop、_release16.3
include/vsg/threading/DeleteQueue.h136DeleteQueue、ObjectToDelete、四个入队模板、三个计数器16.8
include/vsg/threading/FrameBlock.h79FrameBlock、initial_value、set/get/active/wake/wait_for_change16.7
include/vsg/threading/Latch.h95Latch、set/count_up/count_down/is_ready/wait/release/count16.5
include/vsg/threading/OperationQueue.h156ThreadSafeQueue<T>、Operation、OperationQueue 别名16.16
include/vsg/threading/OperationThreads.h60OperationThreads、threads、queue、status16.16
include/vsg/threading/atomics.h52exchange_if_lower 等四个模板函数16.13.4

16.1.2 src 侧三个实现文件

src/vsg/threading/ 只有三个 .cpp:Affinity.cpp 154 行、DeleteQueue.cpp 121 行、OperationThreads.cpp 63 行。其余全是 header-only:分支都在头文件里,摘录可直接标头文件行号。Barrier.h:17、Latch.h:17-18、FrameBlock.h:18 各 #include <condition_variable>;ActivityStatus.h 只 #include <vsg/core/Inherit.h>,连 <atomic> 都不显式包含,std::atomic_bool(ActivityStatus.h:38)靠传递包含。

16.1.3 方法名校准:主题清单里三个不存在的 API

本章主题清单里列了几组方法名,实测后必须先纠正三处,否则后面的行号证据会全部落空。

第一处,Latch 没有 arrive_and_wait()。include/vsg/threading/Latch.h:24-92 的公开方法是 set(int)(:33)、count_up()(:46)、count_down()(:51)、is_ready()(:64)、wait()(:69)、release()(:78)、count()(:84),共七个。arrive_and_wait 只属于 Barrier(include/vsg/threading/Barrier.h:35),全库 8 处调用全部落在 src/vsg/app/Viewer.cpp:693/699/706/721/725/740/752/843。

第二处,FrameBlock 没有 waitForFrame(),也没有 advanceToNextFrame()。它的五个方法是 set()(include/vsg/threading/FrameBlock.h:36)、get()(:43)、active()(:49)、wake()(:51)、wait_for_change()(:57)。advanceToNextFrame() 是 Viewer 的方法(include/vsg/app/Viewer.h:102、src/vsg/app/Viewer.cpp:155),waitForFrame() 全库 grep -rn 零命中。

第三处,threading 目录里没有 AtomicStack。find . -iname "*AtomicStack*" 零结果,grep -rn "AtomicStack" include/ src/ 零结果。与之最接近的是 include/vsg/threading/atomics.h,但它不含任何栈或容器,只含四个操作 std::atomic<T>& 的自由函数模板(:22、:30、:38、:46)。本章 16.13.4 会对这四个模板逐一清点调用点,不把一个不存在的类写进规模表。

16.1.4 all.h 的暴露面与本章边界

include/vsg/all.h:189-197 用九行把整个 threading 目录一次性暴露:

// include/vsg/all.h:189-197
#include <vsg/threading/ActivityStatus.h>
#include <vsg/threading/Affinity.h>
#include <vsg/threading/Barrier.h>
#include <vsg/threading/DeleteQueue.h>
#include <vsg/threading/FrameBlock.h>
#include <vsg/threading/Latch.h>
#include <vsg/threading/OperationQueue.h>
#include <vsg/threading/OperationThreads.h>
#include <vsg/threading/atomics.h>

逐字段与逐分支推导。 九行与 find 的九个头文件一一对应,说明本章边界与库的公开边界一致;atomics.h 排在末行且唯一小写文件名,提示它属工具函数。

代价与边界。 all.h 把三个同步头传给每个包含它的翻译单元,include/vsg/all.h 共 342 行。setAffinity 的两个声明(include/vsg/threading/Affinity.h:39/43)因此进入公开 ABI,但 16.15.4 证明它们零调用。

与前面章节的交叉引用。 第九章用 include/vsg/all.h 核对公开暴露面,本章只是把过滤条件从 state/ 换成 threading/;第十五章把 include/vsg/threading/DeleteQueue.h:39 列为三个独立常量之一,本章 16.9.3 补齐另外两个。

16.1.5 规模数字与正面处理文件清单

另有 11 个关联文件只在交叉引用里出现:include/vsg/commands/ExecuteCommands.h、include/vsg/core/Object.h、src/vsg/core/Object.cpp、include/vsg/core/Auxiliary.h、include/vsg/core/ref_ptr.h、include/vsg/core/Allocator.h、include/vsg/vk/CommandBuffer.h、include/vsg/vk/Swapchain.h、include/vsg/app/CompileManager.h、include/vsg/utils/TracyInstrumentation.h、include/vsg/all.h。合计 31 个文件,20 个在 16.0 主表给出角色,11 个在此给出引用处。


16.2 ActivityStatus:全库唯一的退出开关

16.2.1 源码摘录与逐字段推导

// 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;
    };
    VSG_type_name(vsg::ActivityStatus)

逐字段与逐分支推导。 字段只有 _active(:38);set()(:27)的 _active.exchange(flag) 丢弃旧值,等价于一次 seq_cst store;active()(:30)靠隐式转换读同一原子。~ActivityStatus()(:36)是 protected 空实现,对象只能由 ref_ptr 持有——于是 16.2.3 的 Viewer 与 DatabasePager 各持一份独立 status,前者停不掉后者的线程。

16.2.2 两个装配点与一份状态的分叉

// src/vsg/app/Viewer.cpp:33(构造函数初始化列表节选)
    status(vsg::ActivityStatus::create()),
// src/vsg/io/DatabasePager.cpp:490-501(构造函数节选)
DatabasePager::DatabasePager()
{
    if (!status) status = ActivityStatus::create();

    culledPagedLODs = CulledPagedLODs::create();

    _requestQueue = DatabaseQueue::create(status);
    _toMergeQueue = DatabaseQueue::create(status);
    deleteQueue = DeleteQueue::create(status);

    pagedLODContainer = PagedLODContainer::create(4000);
}

逐分支推导。 Viewer.cpp:33 在构造期无条件 create();DatabasePager.cpp:492 用 if (!status) 做幂等保护,说明 DatabasePager::status(include/vsg/io/DatabasePager.h:167)是公开成员,外部可以先注入一份共享的 ActivityStatus 再构造。第 :496-498 行把同一个 status 传给两个 DatabaseQueue 与一个 DeleteQueue,于是 DatabasePager 的三个后台队列共享一个退出开关。

16.2.3 代价与边界

代价与边界。 把退出判定压成一个 atomic_bool 的好处是所有等待循环只需读一次原子,不必取锁;代价是「停止」这个动作本身不带唤醒。任何阻塞在 std::condition_variable 上的线程,光靠 set(false) 不会自己醒来,必须由持有同一把锁的一方额外 notify。Viewer::stopThreading()(src/vsg/app/Viewer.cpp:783-784)因此是两行而不是一行:先 status->set(false),再 _frameBlock->wake()。

16.2.4 与前面章节的交叉引用

与前面章节的交叉引用。 第一章把 Object 的引用计数、Auxiliary 与 ref_ptr 拆成一套「谁持有多久」的模型,本章 16.10 会把这条链一直走到 DeleteQueue 的 objectsToDelete.clear();ActivityStatus 本身继承 Inherit<Object, ActivityStatus>,正是那套模型的一个实例,因此它能在 Viewer、DatabasePager、FrameBlock、DeleteQueue、OperationQueue、OperationThreads 之间以 ref_ptr 任意传递而不必担心提前析构。

16.3 Barrier:phase 计数与两种到达

16.3.1 源码摘录与逐字段推导

// include/vsg/threading/Barrier.h:22-75
    /// Barrier provides a means for synchronizing multiple threads that all release together once specified number of threads joined the Barrier.
    class Barrier : public Inherit<Object, Barrier>
    {
    public:
        explicit Barrier(uint32_t num_thread) :
            _num_threads(num_thread),
            _num_arrived(0),
            _phase(0) {}

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

        /// 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();
            }
        }

    protected:
        ~Barrier() override {}

        void _release()
        {
            _num_arrived = 0;
            ++_phase;
            _cv.notify_all();
        }

        const uint32_t _num_threads;
        uint32_t _num_arrived;
        uint32_t _phase;

        std::mutex _mutex;
        std::condition_variable _cv;
    };

逐字段与逐分支推导。 _num_threads(include/vsg/threading/Barrier.h:69)是 const,_num_arrived(:70)计本代到达,_phase(:71)计已放行代数;三者由 _mutex(:73)保护。arrive_and_wait() 到达数够时调 _release(),否则记下 _phase 进 wait;arrive_and_drop() 只保留前半段,未命中就直接返回。_release()(:62-67)清零计数、++_phase、notify_all(),所以「放行」是代数递增而非布尔开关,Barrier 可跨帧复用而无需复位。两个 unique_lock lock(_mutex)(:37、:52)靠 C++17 类模板实参推导;拷贝构造与赋值被删除,析构 protected。

16.3.2 _release 与 generation:能复用,不能复位

逐分支推导。 _phase 从 0 起步(:29),每次 _release() 自增(:65)。因为它是 uint32_t,按每秒 60 帧、每帧一次放行计算,回绕一次需要约 2^32 / (60 × 3600 × 24 × 365) ≈ 2.27 年;回绕本身在本章的缺陷清单里排不上号,真正的问题是 _phase 只增不减且没有任何外部可读接口:类体没有 phase()、没有 reset()、没有 num_threads() 访问器,_num_threads 还是 const。

_release() 里 _num_arrived = 0(:64)与 ++_phase(:65)必须同处一个临界区,否则后到的线程可能把清零后的计数再次加到 _num_threads 之外。_cv.notify_all()(:66)在持锁状态下发出,这一点常被当作性能问题讨论,但在本实现里是必要的:谓词读的是 _phase,而 _phase 由持锁方修改,唤醒若发生在释放锁之后,等待方醒来取锁读到的仍会读到旧值;持锁 notify 把「改状态」与「发通知」合成一个不可插入的序列。16.5.3 会看到 Latch 用另一种写法达到同样效果。

代价与边界。 「代数递增」替代「显式复位」省掉了一个 API,代价是把「这一代到底该来几个线程」永久固定在构造期。若某个参与者在两代之间退出,后续每一代的 _num_arrived 都只能到 _num_threads - 1,_release() 永不触发,_phase 停滞,所有 arrive_and_wait() 阻塞在 :45。这个后果与第九、十五章反复出现的「容器只增不减」是同一类结构问题,只是这里不增的是代数、不减的是参与者上限。

16.3.3 无超时、无复位、异常不回滚

逐分支推导。 _cv.wait(lock, pred)(include/vsg/threading/Barrier.h:45)是无超时重载,既没有 wait_for,也没有 wait_until。等待者的唯一出口是谓词 _phase != my_phase 成立,而谓词成立的唯一途径是某个线程走到 _release()。三类事件会让这条链断掉:

第一,参与者计数不足。构造参数是 1 + numValidTasks(src/vsg/app/Viewer.cpp:621),主线程 :843 与各 task 线程 :642/:706 每帧各贡献一次到达;任一 task 线程因 wait_for_change() 返回 false 退出(include/vsg/threading/FrameBlock.h:66),下一帧就少一次到达。

第二,到达过程中抛异常。viewer_task->submit(frameStamp)(src/vsg/app/Viewer.cpp:640)或 commandGraph->record(...)(:697)若抛出,C++ 会在栈展开时析构 std::unique_lock 并释放 _mutex,但 _num_arrived 已经在 :38 加过,没有任何 catch 或 RAII 守卫把它减回去。

第三,等待者被取消。Viewer::stopThreading()(src/vsg/app/Viewer.cpp:783-784)只 set(false) 加 _frameBlock->wake(),它唤醒的是阻塞在 FrameBlock::_cv 上的线程,对阻塞在 Barrier::_cv(include/vsg/threading/Barrier.h:74)上的线程没有任何通知。若恰好有线程停在 :45 而主线程又不再发起新帧,stopThreading() 的 thread.join()(:788)会一并挂住。

代价与边界。 上述三类都没有兜底路径:没有超时、没有中断、没有状态查询、没有析构时的强制 notify_all()(~Barrier() 在 :60 是空实现)。规避路径有三条,代价依次降低:把 :45 改成 wait_for(lock, duration, pred) 并在超时后返回错误码,调用方据此跳过本帧;把 _num_threads 改成可由 arrive_and_drop() 递减的动态计数,让退出自动收缩门槛;或者在 Viewer::stopThreading() 里对所有 Barrier 补一次 _cv.notify_all() 唤醒,代价是要为 Barrier 新增一个公开的 wake()。

与前面章节的交叉引用。 第十四章留下的死锁问题在本章落到具体一行:include/vsg/threading/Barrier.h:45。第十五章批判性结论第一条说「帧期失败没有统一错误通道」,这里补上另一半——帧期连「超时」这条最低限度的自救通道也没有,Queue::submit() 失败被上抛(RecordAndSubmitTask.cpp:279)、present 失败被丢弃(Viewer.cpp:860),而记录线程对这一切的感知方式是永远等在同一个条件变量上。

16.3.4 arrive_and_drop 的语义落差

逐字段推导。 注释把 arrive_and_drop()(include/vsg/threading/Barrier.h:49)写成「到达后不等待放行条件、立即返回」,字面上暗示调用者此后退出参与。但函数体(:50-57)只做 ++_num_arrived 与可能的 _release(),既不登记「谁退出了」,也不改 _num_threads(:69 是 const),更不调整后续代的到达门槛。它与 arrive_and_wait() 的真实差别只有一处:少了 :44-45 的 my_phase 记录与 _cv.wait。

代价与边界。 名字与实现不符的直接后果是误用风险:第三方若按注释写「一次性线程到达后 drop 并退出」,下一帧起 arrive_and_wait() 一侧必然少一次到达,触发 16.3.3 的第一类死锁。规避方式是把函数改名为 arrive_and_continue() 之类,或补齐 _num_threads 的动态递减;在改动之前,唯一正确的用法就是 Viewer.cpp:642 这种「每帧都到达、只是不等」的用法。

与前面章节的交叉引用。 第十五章陷阱表第 19、20 行把 Queue::submit(vector) 与 Viewer::waitForFences() 判为「写好没接上的死代码」;arrive_and_drop() 不属于死代码(它有唯一调用点),却属于同一家族的「接口承诺比实现多」:注释承诺了退出,实现只提供了不等。


16.4 Barrier 在 Viewer 里的三处装配

16.4.1 单 CommandGraph 分支

// src/vsg/app/Viewer.cpp:618-646
    status->set(true);
    _threading = true;
    _frameBlock = FrameBlock::create(status);
    _submissionCompleted = Barrier::create(1 + numValidTasks);

    // 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"));

逐分支推导。 :618 把 status 重新置 true(setupThreading() 开头 :600 先调 stopThreading(),故这是重入后的复位);:620 用同一份 status 造 _frameBlock;:621 造 _submissionCompleted,参与数 1 + numValidTasks。:613-616 的提前返回保证 numValidTasks == 0 时不会造出任何线程与任何 Barrier。run lambda 的形参按值捕获四个 ref_ptr,std::thread 在 :646 持有它们的副本,因此线程运行期间 FrameBlock 与 Barrier 不会因 Viewer 侧重新赋值而析构。

16.4.2 SharedData 多 CommandGraph 分支

// src/vsg/app/Viewer.cpp:648-677(SharedData 与线程数计算)
        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);
                }
                // shared between all threads
                ref_ptr<RecordAndSubmitTask> task;
                ref_ptr<FrameBlock> frameBlock;
                ref_ptr<Barrier> submissionCompletedBarrier;
                // shared between threads associated with each task
                ref_ptr<RecordedCommandBuffers> recordedCommandBuffers;
                ref_ptr<Barrier> recordStartBarrier;
                ref_ptr<Barrier> recordCompletedBarrier;
            };

            uint32_t numThreads = static_cast<uint32_t>(task->commandGraphs.size());
            if (task->transferTask) ++numThreads;

            ref_ptr<SharedData> sharedData = SharedData::create(task, _frameBlock, _submissionCompleted, numThreads);

逐字段推导。 此分支额外造 recordStartBarrier 与 recordCompletedBarrier(:659-660),参与数都是 numThreads(:674-675,有 transferTask 时加一),于是单个 task 内是三道屏障:

屏障参与数到达点作用
recordStartBarriernumThreadssrc/vsg/app/Viewer.cpp:693/721/740primary 调完 task->start() 后放行全部 record 线程
recordCompletedBarriernumThreadssrc/vsg/app/Viewer.cpp:699/725/752全部 record 完成后才允许 primary 调 task->finish()
submissionCompletedBarrier1 + numValidTaskssrc/vsg/app/Viewer.cpp:706/642/843全部 task 提交完成后才允许主线程进入 present()

run_secondary(:710-727)与 run_transfer(:729-754)只碰前两道屏障,run_primary(:679-708)额外碰第三道;三者都以 initial_value(:683、:714、:733)起步、由 wait_for_change(frameStamp) 驱动。run_transfer 在 :744 的 transferData() 非 VK_SUCCESS 时只跳过 earlyDataTransferredSemaphore 赋值,仍在 :752 到达第二道屏障。

代价与边界。 三道屏障共用一份 _frameBlock 与一份 status,但彼此的 _phase 完全独立;recordStartBarrier 与 recordCompletedBarrier 每帧各放行两次,submissionCompletedBarrier 每帧放行一次。任何一道屏障的参与者数与 numThreads 不符(例如某个 CommandGraph 为空导致 :756-762 少起一个线程),该屏障当帧即挂,而另外两道仍会照常推进,故障表现是「部分线程停住、部分线程继续跑」,比整体停住更难定位。

16.4.3 1 + numValidTasks 的配对

// src/vsg/app/Viewer.cpp:833-851
#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);
        }
    }

逐分支推导。 numValidTasks 在 :603-610 按 commandGraphs 非空的 task 计数。每个有效 task 恰好贡献一次到达:单 CommandGraph 分支由 :642 的 arrive_and_drop() 贡献,多 CommandGraph 分支由 :706 的 arrive_and_wait() 贡献(每个 task 只有一个 primary 线程)。

那个 1 必须与 :843 严格配对,原因就在 const uint32_t _num_threads(include/vsg/threading/Barrier.h:69):屏障既不统计「谁注册过」,也不接受运行期增减,它只认累计到达数是否等于构造时的常数。少一次到达,_release() 不执行;多一次到达,_num_arrived 越过后不再归零,下一帧从错误基数继续累加。

16.4.4 死锁推演与与前面章节的交叉引用

把 16.3.3 的三类断链代入这个装配,得到一张可复现的时序:

步骤事件_num_arrived_phase后果
1:842 set() 放行 N 个 task 线程0k记录线程开始 submit() / record()
2N−1 个 task 正常到达(:642 或 :706)N−1k未达 1 + N
3第 N 个 task 的 wait_for_change() 返回 false 退出N−1k本帧少一次到达
4主线程 :843 arrive_and_wait() 记 my_phase = k 并等待Nk谓词 _phase != k 恒假
5无任何线程再调 _release()Nk主线程与剩余 primary 永久阻塞

stopThreading() 的 status->set(false)(:783)与 _frameBlock->wake()(:784)作用于 FrameBlock::_cv,对停在 Barrier::_cv(include/vsg/threading/Barrier.h:74)上的 :843 无效;:788 的 thread.join() 因此也挂住。规避路径是把 :843 的等待换成带超时的 wait_for,并在超时后跳过 present()、记录一次帧期错误,这同时补上了第十五章批判性结论第一条所缺的那条帧期错误通道。

与前面章节的交叉引用。 第十五章把 numBuffers = 3(src/vsg/app/Viewer.cpp:501)、imageCount = 3(include/vsg/vk/Swapchain.h:37)与 retainForFrameCount = 3(include/vsg/threading/DeleteQueue.h:39)并列为三个独立常量;本节补上第四个计数——1 + numValidTasks。它同样独立:既不由 numBuffers 推导,也不随 commandGraphs 的增减在运行期修正,只在每次 setupThreading() 时重算一次。


16.5 Latch:原子计数与条件变量的双轨

16.5.1 源码摘录

// include/vsg/threading/Latch.h:23-92
    /// Latch provides a means for synchronizing multiple threads that waits for the latch count to be decremented to zero.
    class Latch : public Inherit<Object, Latch>
    {
    public:
        explicit Latch(int num) :
            _count(num) {}

        explicit Latch(size_t num) :
            Latch(static_cast<int>(num)) {}

        void set(int num)
        {
            if (num == 0)
            {
                if (_count.exchange(0) != 0)
                    release();
            }
            else
            {
                _count = num;
            }
        }

        void count_up()
        {
            ++_count;
        }

        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);
            }
        }

        virtual void release()
        {
            std::unique_lock lock(_mutex);
            _cv.notify_all();
        }

        int count() const { return _count.load(); }

    protected:
        ~Latch() override {}

        std::atomic_int _count;
        std::mutex _mutex;
        std::condition_variable _cv;
    };

逐字段推导。 Latch 把状态拆成两条轨:_count(:89)是 std::atomic_int,增减不取锁;wait()(:69)与 release()(:78)却要取 _mutex。size_t 构造(:30-31)用 static_cast<int> 窄化转发,是 16.6.1 与陷阱表第 11 行的来源。

16.5.2 count_down 的 <= 1 判据与下溢

逐分支推导。 _count.fetch_sub(1)(:53)返回减一之前的值,<= 1 即释放并返回 true;写成 <= 1 而非 == 1 有两处偏差。计数已为 0 时再减返回 0、仍 release() 且计数变 −1,可无限触发,is_ready()(:66)永久为真——对只判 > 0 的 wait() 无害,对把返回值当「我是最后一个」的调用方是错误信号。计数为负后 set(n != 0)(:42)直接覆盖可拉回正数,set(0)(:35-39)却因负数 != 0 额外 release(),两次通知不对称。

src/vsg/commands/ExecuteCommands.cpp:18 把 _latch 初始化为 Latch::create(0),:65 的 completed() 又在 if (commandBuffer) 块之外无条件 _latch->count_down();即使没有任何连接的 SecondaryCommandGraph(reset() 在 :41 用 set(0) 起步),一次 completed() 就把计数打到 −1 并 release()。这不是假想输入,是库内现存调用点,16.6.2 会把它与 record() 的 wait() 一起排演。

16.5.3 wait 的检查-等待协议:这一处是正确的

逐分支推导。 wait()(:69-76)用 while (_count > 0) _cv.wait(lock);,release()(:78-82)同样取 _mutex 后再 notify_all():读计数与进入等待在同一临界区,发通知也必须进同一临界区,因此通知不丢。set() 的非零分支(:42)改计数不发通知,2→3 时继续睡是正确的;0→3 时已返回的调用方不会回头,这是「Latch 无 generation」的代价而非丢唤醒。

代价与边界。 wait() 与 Barrier::arrive_and_wait()(include/vsg/threading/Barrier.h:45)都无超时,Latch 连 ActivityStatus 都没有,count_down() 漏调就无退路;while 挡住虚假唤醒,挡不住「计数永不归零」。

16.5.4 set 的双分支、无 generation 与与 Barrier 的差异

逐分支推导。 set(0)(:35-39)用 exchange(0) 拿旧值,只在旧值非 0 时 release();set(n != 0)(:40-43)用一次原子写覆盖。两者都不取 _mutex,也不通知。整个类没有 _phase、没有代数、没有「已放行」标志:is_ready() 只是 _count <= 0 的即时快照,一旦为真就永久为真,直到有人 set() 一个正数。

维度BarrierLatch
放行条件_num_arrived == _num_threads_count <= 0
放行标记_phase 递增(include/vsg/threading/Barrier.h:65)无,只有计数本身
是否可自动复用下一轮是,_release() 清零计数(include/vsg/threading/Barrier.h:64)否,需显式 set(n) 重置
等待方是否阻塞除最后到达者外全部阻塞全部 wait() 阻塞,count_down() 一侧不阻塞
计数保护_mutex(include/vsg/threading/Barrier.h:73)std::atomic_int 无锁 + _mutex 只保护 cv
全库 set() 调用点无此 APIExecuteCommands::reset() 在 src/vsg/commands/ExecuteCommands.cpp:41 对 _commandGraphsAndBuffers.size() 调一次 set()

代价与边界。 「双轨」设计让 count_down() 成为一次纯原子操作,工作线程完成录制后可以立即减一并继续,不必排在一把互斥量后面,这在 src/vsg/io/read.cpp:160 一次创建 filenames.size() 个 ReadOperation 的场景里是实打实的收益。代价是 set() 与 count_down() 之间没有顺序保证:两者都不持同一把锁,若 reset()(src/vsg/commands/ExecuteCommands.cpp:37,其中 _latch->set() 读 _commandGraphsAndBuffers.size())与 completed()(:49-66)交错,set(n) 可能覆盖掉一次已经发生的 count_down(),使计数永远差 1。

与前面章节的交叉引用。 第一章 Object::unref()(include/vsg/core/Object.h:125)用 fetch_sub(1) <= 1 判「最后一个引用」,与 Latch::count_down()(include/vsg/threading/Latch.h:53)是同一个判据模板;前者返回 <= 1 时 unref() 的对象计数恰好不会为负(引用计数从 1 起步且有 ref() 配对),后者却因 create(0) 与无条件 count_down() 可以为负。第九章 ShaderStage::compare 漏字段、第十五章 VkResult 六种去向,都属「同一判据在不同上下文里少了一条约束」;本章这一处是同一模式的第三次出现。

16.6 Latch 的两个真实调用点

16.6.1 read.cpp 的批量读

// src/vsg/io/read.cpp:131-173
    if (operationThreads && filenames.size() > 1)
    {
        // set up the entries container for operations to write to.
        for (const auto& filename : filenames)
        {
            entries[filename] = nullptr;
        }

        struct ReadOperation : public Operation
        {
            ReadOperation(const Path& f, ref_ptr<const Options> opt, ref_ptr<Object>& obj, ref_ptr<Latch> l) :
                filename(f),
                options(opt),
                object(obj),
                latch(l) {}

            void run() override
            {
                object = vsg::read(filename, options);
                latch->count_down();
            }

            Path filename;
            ref_ptr<const Options> options;
            ref_ptr<Object>& object;
            ref_ptr<Latch> latch;
        };

        // use latch to synchronize this thread with the file reading threads
        auto latch = Latch::create(static_cast<int>(filenames.size()));

        // add operations
        for (auto& [filename, object] : entries)
        {
            operationThreads->add(ref_ptr<Operation>(new ReadOperation(filename, options, object, latch)));
        }

        // use this thread to read the files as well
        operationThreads->run();

        // wait till all the read operations have completed
        latch->wait();
    }

逐字段与逐分支推导。 latch 初值是 static_cast<int>(filenames.size())(:160),经 include/vsg/threading/Latch.h:30-31 窄化转发;每个 ReadOperation::run()(:147-151)依次 vsg::read() 与 latch->count_down()。

计数配对是「N 个文件 = N 次 count_down()」。filenames.size() > 1 的门槛(:131)保证至少两次到达;若 operationThreads 为空或文件数 ≤ 1,走 :174-185 的单线程分支,根本不创建 Latch。这个分支选择让 Latch 在本调用点始终以 ≥ 2 的初值起步,避开了 16.5.2 的零初值下溢,但 static_cast<int> 的窄化没有上界检查:当 filenames.size() > INT_MAX 时结果为负,_count 从负数起步,is_ready() 立即为真,latch->wait() 立即返回,读操作全部还没开始。

16.6.2 ExecuteCommands 的 reset / completed / record 三拍

// src/vsg/commands/ExecuteCommands.cpp:17-66
ExecuteCommands::ExecuteCommands() :
    _latch(vsg::Latch::create(0))
{
}
...
void ExecuteCommands::reset()
{
    std::scoped_lock lock(_mutex);

    _latch->set(static_cast<int>(_commandGraphsAndBuffers.size()));

    for (auto& entry : _commandGraphsAndBuffers)
    {
        entry.cb = {};
    }
}

void ExecuteCommands::completed(const SecondaryCommandGraph& commandGraph, ref_ptr<CommandBuffer> commandBuffer)
{
    if (commandBuffer)
    {
        std::scoped_lock lock(_mutex);

        for (auto& [cg, cb] : _commandGraphsAndBuffers)
        {
            if (cg == &commandGraph)
            {
                cb = commandBuffer;
                break;
            }
        }
    }

    _latch->count_down();
}
// src/vsg/commands/ExecuteCommands.cpp:68-83
void ExecuteCommands::record(CommandBuffer& commandBuffer) const
{
    _latch->wait();

    std::scoped_lock lock(_mutex);
    std::vector<VkCommandBuffer> vk_commandBuffers;
    for (const auto& entry : _commandGraphsAndBuffers)
    {
        if (entry.cb) vk_commandBuffers.push_back(*entry.cb);
    }

    if (!vk_commandBuffers.empty())
    {
        vkCmdExecuteCommands(commandBuffer, static_cast<uint32_t>(vk_commandBuffers.size()), vk_commandBuffers.data());
    }
}

逐分支推导。 三拍是:reset()(:37-47)把计数设成 _commandGraphsAndBuffers.size() 并清空缓存的 cb;每个 SecondaryCommandGraph 录制完成后调 completed()(:49-66),写槽位再 count_down();record()(:68-83)先 wait() 再取锁收集非空 cb 交 vkCmdExecuteCommands。两处边界:_latch->count_down()(:65)在 if (commandBuffer) 与 scoped_lock 作用域之外,空 commandBuffer 也照减;count_down() 不持任何锁,Latch::_count 是原子、release() 另取 Latch::_mutex。代入构造(:18)的 create(0):无子图时 set(0) 不 release(),一次 completed() 即把计数打到 −1;record() 的 wait()(:70)立即返回、空 vk_commandBuffers 被 :79 跳过。功能对,但负值从不检查 count() 或 is_ready(),一直不被观察。

16.6.3 异常路径不回滚

逐分支推导。 ReadOperation::run()(src/vsg/io/read.cpp:147-151)把 vsg::read(...) 与 latch->count_down() 写成顺序两行,中间没有 try/catch,也没有 RAII 守卫。vsg::read() 在文件不存在、解析失败、插件抛异常时都可以抛出;一旦抛出,栈展开跳过 :150,latch 的计数少减一次,:172 的 latch->wait() 因 include/vsg/threading/Latch.h:72 的 while (_count > 0) 永远为真而挂住。

// src/vsg/threading/OperationThreads.cpp:23-32
    auto runThread = [](ref_ptr<OperationQueue> q, ref_ptr<ActivityStatus> thread_status) {
        while (thread_status->active())
        {
            ref_ptr<Operation> operation = q->take_when_available();
            if (operation)
            {
                operation->run();
            }
        }
    };

operation->run()(:29)若抛出,异常穿过 std::thread 的入口函数,直接触发 std::terminate,整个进程结束;即便不终止,该线程的 while 循环也一并退出,后续队列项再无人消费。两条后果都指向同一个缺口:count_down() 这类「配对收尾」动作没有放在析构或 scope_exit 里。

代价与边界。 这类缺陷在正常运行期不可见,只有 I/O 异常这一条路径能触发,因此很容易被当成「不会出问题」。但第十五章批判性结论第一条已经指出,帧期失败缺少统一通道;本章补的是更靠前的一层:连「工作线程自己崩了」这件事,汇合点都感知不到。

16.6.4 零调用 API 与与前面章节的交叉引用

与前面章节的交叉引用。 第十七章要接手 Options、ReaderWriter 与 read/write;src/vsg/io/read.cpp:160 的 Latch::create(static_cast<int>(filenames.size())) 正是 read() 在多线程分支里的汇合点,因此本章对 count_down() 异常路径的分析会直接成为下一章讨论「批量读失败如何上报」的前置条件。


16.7 FrameBlock:帧变化判据与退出握手

16.7.1 源码摘录

// include/vsg/threading/FrameBlock.h:23-77
    /// 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(); }

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

        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();
        }

    protected:
        ~FrameBlock() override {}

        std::mutex _mutex;
        std::condition_variable _cv;
        ref_ptr<FrameStamp> _value;
        ref_ptr<ActivityStatus> _status;
    };

逐字段推导。 四个字段是 _mutex(:72)、_cv(:73)、_value(:74)、_status(:75)。initial_value(:27)是共享的空 ref_ptr<FrameStamp>,作为各记录线程的起点(src/vsg/app/Viewer.cpp:633/683/714/733)。set()(:36-41)写 _value 后通知,wake()(:51-55)只通知不改值。

16.7.2 五个方法的分工与代价

逐分支推导。 set() 是写状态 + 通知,wake() 只通知,get() 只读,三者共用 _mutex;wait_for_change() 是唯一用 unique_lock 的方法,因为 _cv.wait(lock)(:62)要可释放的锁,且它在持锁下执行 value = _value;(:65)触发 ref()。wake() 不改 _value 却能放行,靠循环条件的 _status->active():先置 false,唤醒后重查为假、退出并返回 false(:66),语义是「让线程重新检查并退出」而非「看到新帧」。对照 Latch::release()(include/vsg/threading/Latch.h:78-82)同样只通知不改计数,但 wait() 条件只有 _count > 0(:72),所以单独 release() 放不放行任何线程。

代价与边界。 active()(:49)与 wait_for_change()(:60/66)直接解引用 _status,构造函数(:29-31)无断言;get() 与 active() 全库零调用,是写好没接上的 API。

16.7.3 指针相等契约与 FrameStamp::create

// src/vsg/app/Viewer.cpp:172-192
    // 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);
    }

逐分支推导。 wait_for_change() 的 _value == value(include/vsg/threading/FrameBlock.h:60)比较的是两个 ref_ptr<FrameStamp>。按 include/vsg/core/ref_ptr.h 的语义,ref_ptr 的相等比较落到裸指针 _ptr 上,因此这里比的是对象地址,不是 frameCount。

:181 与 :191 每帧 FrameStamp::create(...) 造新对象;:191 右侧的 _frameStamp->frameCount 读的是旧对象,赋值后才换成新对象,因此只要每次返回新地址,地址比较就能区分相邻帧。契约前提是「对象地址每帧都变」,不是「frameCount 递增」。

代价与边界。 地址当版本号省掉一个字段,代价是每帧分配新对象,且分配与 ref_ptr 计数被绑进帧同步正确性。规避:改比 _value->frameCount != value->frameCount(处理空首帧),或给 FrameBlock 加独立 _generation。

16.7.4 lost-wakeup 窗口:这一处同样是正确的

逐分支推导。 第十四章 14.x 留下的 lost-wakeup 问题,落在 FrameBlock 上要分两个方向验证。

方向一,set() 在 std::scoped_lock(include/vsg/threading/FrameBlock.h:38)内写 _value = frameStamp(:39)再 notify_all()(:40);wait_for_change() 在 unique_lock(:59)内判 _value == value(:60)后 _cv.wait(lock)(:62)。写与判、判与通知都在同一把锁下,不存在「通知落在判条件之后」的窗口。

方向二,ActivityStatus::set()(include/vsg/threading/ActivityStatus.h:27)不取 FrameBlock::_mutex,但 wake()(include/vsg/threading/FrameBlock.h:51-55)取同一把锁并通知,且 stopThreading() 先 set(false)(src/vsg/app/Viewer.cpp:783)后 wake()(:784):等待方持锁进入 _cv.wait 后 wake() 才拿到锁通知,重查 _status->active() 为假即退出。

代价与边界。 协议依赖三条:wake() 与 wait_for_change() 同一把 _mutex、状态位 seq_cst、while 每轮重读,少一条就出现第十四章的窗口。

16.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
    // 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();
}

逐分支推导。 :776 的 if (!_threading) return; 让 stopThreading() 可重入——setupThreading() 开头 :600 就是靠这一点做「先停后建」。

握手覆盖不到的地方有两处。第一,:843 主线程若正阻塞在 _submissionCompleted 的 Barrier::_cv(include/vsg/threading/Barrier.h:74)上,status->set(false) 与 _frameBlock->wake() 都碰不到它,:788 的 join() 会连带挂住——这是 16.3.3 第三类断链。第二,stopThreading() 只关 Viewer::status(src/vsg/app/Viewer.cpp:33),DatabasePager 用的是 :492 那份独立 status,其 deleteThread(src/vsg/io/DatabasePager.cpp:621-624)与读线程都不受这个函数影响。

与前面章节的交叉引用。 第十五章预告第三问「两条通知语义如何保证所有线程都退出」,答案在 16.7.4:靠的是「同一把锁 + 原子状态 + 每轮重读」,不是 set() 与 wake() 的先后。第十四章的 lost-wakeup 在 FrameBlock 上被正确实现挡住了,却在 DeleteQueue::wait_then_clear()(16.8.5)里以另一种形式出现——那里把唤醒条件绑到了帧号变化,而不是绑到「有到期对象」这件事本身。


16.8 DeleteQueue:真实路径与三条清理路径

16.8.1 路径实测:不在 app/,也不在 vk/

主题清单里写「实测真实路径,可能在 src/vsg/app/ 或 vk/」,实测结果是两者都不对。find . -iname "*DeleteQueue*" 给出两行:include/vsg/threading/DeleteQueue.h 与 src/vsg/threading/DeleteQueue.cpp。grep -rln "DeleteQueue" include/ src/ 给出六行:include/vsg/all.h、include/vsg/io/DatabasePager.h、include/vsg/threading/DeleteQueue.h、src/vsg/CMakeLists.txt、src/vsg/io/DatabasePager.cpp、src/vsg/threading/DeleteQueue.cpp。

16.8.2 头文件逐字段

// include/vsg/threading/DeleteQueue.h:24-42
    /// Thread safe queue deleting nodes/subgraphs as batches, typically done from a background thread.
    class VSG_DECLSPEC DeleteQueue : public Inherit<Object, DeleteQueue>
    {
    public:
        explicit DeleteQueue(ref_ptr<ActivityStatus> status);

        struct ObjectToDelete
        {
            uint64_t frameCount = 0;
            ref_ptr<Object> object;
        };

        using ObjectsToDelete = std::list<ObjectToDelete>;

        std::atomic_uint64_t frameCount = 0;
        uint64_t retainForFrameCount = 3;
        std::atomic_uint64_t deletedCount = 0;

        ActivityStatus* getStatus() { return _status; }
        const ActivityStatus* getStatus() const { return _status; }

逐字段推导。 ObjectToDelete(:30-34)只有 uint64_t frameCount 与 ref_ptr<Object> object,后者是回收链起点(16.10)。容器选 std::list(:36)是因为 16.8.5/16.8.6 的 splice() 依赖常数时间节点转移。三个计数器 public:frameCount(:38)与 deletedCount(:40)为原子,retainForFrameCount(:39)为普通 uint64_t、默认 3。

VSG_DECLSPEC(:25)与 src/vsg/threading/DeleteQueue.cpp 的实现分离,使 DeleteQueue 是 threading/ 里少数非 header-only 的类之一;另外两个非 header-only 的是 Affinity 与 OperationThreads。

16.8.3 四个入队入口

// include/vsg/threading/DeleteQueue.h:47-66
        void add(ref_ptr<Object> object)
        {
            std::scoped_lock lock(_mutex);
            _objectsToDelete.push_back(ObjectToDelete{frameCount + retainForFrameCount, object});
            _cv.notify_one();
        }

        template<typename T>
        void add(T& objects)
        {
            std::scoped_lock lock(_mutex);

            // register the Objects to delete
            for (auto& object : objects)
            {
                _objectsToDelete.emplace_back(ObjectToDelete{frameCount + retainForFrameCount, object});
            }

            _cv.notify_one();
        }
// include/vsg/threading/DeleteQueue.h:96-114
        template<typename T, typename R>
        void add_prune(T& objects, R& sharedObjectsList)
        {
            std::scoped_lock lock(_mutex);

            // register the Objects to delete
            for (auto& object : objects)
            {
                _objectsToDelete.emplace_back(ObjectToDelete{frameCount + retainForFrameCount, object});
            }

            // register the SharedObjects to call prune on
            for (auto& sharedObjects : sharedObjectsList)
            {
                if (std::find(_sharedObjectsToPrune.begin(), _sharedObjectsToPrune.end(), sharedObjects) == _sharedObjectsToPrune.end())
                    _sharedObjectsToPrune.push_back(sharedObjects);
            }
            _cv.notify_one();
        }

逐分支推导。 四个入口统一 std::scoped_lock、frameCount + retainForFrameCount 时间戳、_cv.notify_one() 收尾;差别是 add(ref_ptr<Object>)(:47-52)单个 push_back、add(T&)(:54-66)批量 emplace_back、prune()(:68-79)与 add_prune()(:96-114)用 std::find 对 _sharedObjectsToPrune 查重。两点边界:唯一消费端是 deleteThread(src/vsg/io/DatabasePager.cpp:633),多起线程会漏唤醒;_objectsToDelete 不去重,重复 add() 等于重复 unref()(16.10.1)。

16.8.4 advance:空指针边界

// src/vsg/threading/DeleteQueue.cpp:23-42
DeleteQueue::DeleteQueue(ref_ptr<ActivityStatus> status) :
    _status(status)
{
}

DeleteQueue::~DeleteQueue()
{
}

void DeleteQueue::advance(ref_ptr<FrameStamp> frameStamp)
{
    std::scoped_lock lock(_mutex);

    frameCount = frameStamp->frameCount;

    if (!_objectsToDelete.empty() && _objectsToDelete.front().frameCount <= frameStamp->frameCount)
    {
        _cv.notify_one();
    }
}

逐分支推导。 advance() 在锁内做三件事:把成员 frameCount 赋成 frameStamp->frameCount(:36);若队列非空且队首已到期,则 notify_one()(:38-41)。构造函数(:23-26)只存 _status,析构(:28-30)是空实现。

:36 直接解引用 frameStamp,没有判空。它的唯一调用点是 src/vsg/io/DatabasePager.cpp:665,紧邻的 :664 却是 frameCount.exchange(frameStamp ? frameStamp->frameCount : 0);——同一函数里上一行显式容忍空 FrameStamp,下一行就把它原样传进不设防的 advance()。再往上追,src/vsg/app/Viewer.cpp:804 传的是 _frameStamp,它在 :181 首帧或 :191 后续帧才被 FrameStamp::create() 赋值;Viewer::update()(:793)作为公开方法,可以在 advanceToNextFrame() 之前被调用,此时 _frameStamp 仍是 ref_ptr<FrameStamp> 的默认空值。

代价与边界。 这不是「理论上可能」,:664 的三元表达式就是作者知道入参可为空的证据,只是保护没有延续到 :665。规避路径有两条且都很短:把 advance() 写成 if (!frameStamp) return; 或 frameCount = frameStamp ? frameStamp->frameCount : frameCount.load();,并在 :38 的比较里同步改用这个局部变量;或者在 DatabasePager::updateSceneGraph() 里把 :665 也纳入 if (frameStamp) 保护。

16.8.5 wait_then_clear:唤醒条件错绑帧号

// src/vsg/threading/DeleteQueue.cpp:44-84
size_t DeleteQueue::wait_then_clear()
{
    ObjectsToDelete objectsToDelete;
    std::list<ref_ptr<SharedObjects>> sharedObjectsToPrune;

    {
        std::chrono::duration waitDuration = std::chrono::milliseconds(100);
        std::unique_lock lock(_mutex);

        uint64_t previous_frameCount = frameCount.load();

        // wait until the conditional variable signals that an operation has been added
        while ((_objectsToDelete.empty() || (frameCount.load() == previous_frameCount)) && _status->active())
        {
            _cv.wait_for(lock, waitDuration);
        }
        auto last_itr = std::find_if(_objectsToDelete.begin(), _objectsToDelete.end(), [&](const ObjectToDelete& otd) { return otd.frameCount > frameCount; });

        // use a swap of the container to keep the time the mutex is acquired as short as possible
        objectsToDelete.splice(objectsToDelete.end(), _objectsToDelete, _objectsToDelete.begin(), last_itr);

        sharedObjectsToPrune.swap(_sharedObjectsToPrune);
    }

    size_t numObjectsToDelete = objectsToDelete.size();

    objectsToDelete.clear();

    if (numObjectsToDelete > 0)
    {
        for (auto& sharedObjects : sharedObjectsToPrune)
        {
            sharedObjects->prune();
        }
        sharedObjectsToPrune.clear();
    }

    deletedCount += numObjectsToDelete;

    return numObjectsToDelete;
}

逐分支推导。 previous_frameCount(:53)进入等待前采样;while 条件(:56)是 (_objectsToDelete.empty() || frameCount == previous_frameCount) && _status->active(),退出要求队列非空且帧号已变。add()(16.8.3)只加节点并 notify_one(),从不改 frameCount,唯一写入者是 advance()(src/vsg/threading/DeleteQueue.cpp:36):被 add() 唤醒后第二项仍为真,只能等下一次 advance()。正常帧循环没问题,但帧停止推进后仍 add_prune()(src/vsg/io/DatabasePager.cpp:791)时,对象戳为 frameCount + 3 永远 > frameCount,find_if 返回 begin(),:63 的 splice 为空、容器只增不减。

代价与边界。 :72 的 if (numObjectsToDelete > 0) 是第二处错误分支::65 无条件 swap 来 _sharedObjectsToPrune,无对象 splice 时这些 SharedObjects 只被 :78 的 clear() 释放 ref_ptr,prune() 一次未调用;而 :791 的调用条件是 ||,明确允许「只 prune 不 delete」,这类帧的 prune 请求被静默丢弃。

16.8.6 clear 与析构

// src/vsg/threading/DeleteQueue.cpp:86-121
size_t DeleteQueue::clear()
{
    ObjectsToDelete objectsToDelete;
    std::list<ref_ptr<SharedObjects>> sharedObjectsToPrune;

    // use a swap of the container to keep the time the mutex is acquired as short as possible
    {
        std::scoped_lock lock(_mutex);

        auto last_itr = std::find_if(_objectsToDelete.begin(), _objectsToDelete.end(), [&](const ObjectToDelete& otd) { return otd.frameCount > frameCount; });

        // use a swap of the container to keep the time the mutex is acquired as short as possible
        objectsToDelete.splice(objectsToDelete.end(), _objectsToDelete, _objectsToDelete.begin(), last_itr);

        sharedObjectsToPrune.swap(_sharedObjectsToPrune);
    }

    size_t numObjectsToDelete = objectsToDelete.size();

    //vsg::info("DeleteQueue::clear(), releasing ", nodesToRelease.size());

    objectsToDelete.clear();

    if (numObjectsToDelete > 0)
    {
        for (auto& sharedObjects : sharedObjectsToPrune)
        {
            sharedObjects->prune();
        }
        sharedObjectsToPrune.clear();
    }

    deletedCount += numObjectsToDelete;

    return numObjectsToDelete;
}

逐分支推导。 clear() 与 wait_then_clear() 只差两点:不等待(无 unique_lock/wait_for/previous_frameCount)、用 std::scoped_lock(:93);:95 的 find_if、:98 的 splice、:100 的 swap、:109-116 的条件 prune 逐行对应。全库 clear() 零调用,是写好的即时清理 API。

代价与边界。 「缩短持锁时间」注释(:97、:62)解释了为何 splice/swap 后在锁外 clear():级联删除可能触发上千次 unref(),放在锁里会挡住 add()。代价是析构与 prune() 脱离 _mutex,无锁重入保护但也不会死锁。

与前面章节的交叉引用。 第十五章把 Fence::resetFenceAndDependencies()(src/vsg/vk/Fence.cpp:40-56)与 DeleteQueue 并列为两套延迟删除;本章 16.17 会指出二者判据不同。


16.9 时间戳、有序假设与三个 3

本节围绕三个公开计数器展开,先把它们原样摘出:

// include/vsg/threading/DeleteQueue.h:38-40
        std::atomic_uint64_t frameCount = 0;
        uint64_t retainForFrameCount = 3;
        std::atomic_uint64_t deletedCount = 0;

16.9.1 时间戳公式与与前面章节的交叉引用

add() 打戳 frameCount + retainForFrameCount(include/vsg/threading/DeleteQueue.h:50/62/104),clear() 以 otd.frameCount > frameCount(src/vsg/threading/DeleteQueue.cpp:95)保留未到期节点;默认 3 意味着帧 F 的对象要到 frameCount >= F + 3 才 splice。frameCount 只由 advance()(:36)写,驱动来自 DatabasePager::updateSceneGraph()(src/vsg/io/DatabasePager.cpp:664-665)← Viewer::update()(src/vsg/app/Viewer.cpp:804)。

16.9.2 find_if 的单调假设

逐分支推导。 std::find_if(..., otd.frameCount > frameCount)(src/vsg/threading/DeleteQueue.cpp:60/95)返回第一个未到期节点,splice 取 [begin, last_itr)。这个写法成立的前提是 _objectsToDelete 按 frameCount 非递减排列。

前提一旦被破坏,find_if 会在第一个大戳处提前停下,后面那些更早到期的节点被留在队列里。frameCount 是 public 的 std::atomic_uint64_t(include/vsg/threading/DeleteQueue.h:38),任何持有 DeleteQueue 的代码都能直接写它;advance() 也不校验新值比旧值大,src/vsg/io/DatabasePager.cpp:664 甚至允许 frameStamp 为空时把自身的 frameCount 置 0,而 deleteQueue->advance(frameStamp) 在空值时已经崩溃(16.8.4)。即便不谈恶意写入,只要某帧 FrameStamp::frameCount 回退(例如外部重置帧号、或跨 Viewer 实例复用 DatabasePager),队列里就会出现「大戳在前、小戳在后」,find_if 的截断让小戳对象一直不被删除,直到未来某次 frameCount 再次大于它——_objectsToDelete 因此长期只增不减。

16.9.3 三个独立常量

常量完整路径:行号值决定什么被谁校正
numBufferssrc/vsg/app/Viewer.cpp:5013RecordAndSubmitTask 的 fence 数与 _indices 长度(src/vsg/app/RecordAndSubmitTask.cpp:29-35)无,硬编码字面量
imageCountinclude/vsg/vk/Swapchain.h:373swapchain image 数,经 src/vsg/vk/Swapchain.cpp:170-171 的 min/max 夹逼回写 preferences驱动 surface capabilities
retainForFrameCountinclude/vsg/threading/DeleteQueue.h:393延迟删除保留帧数无,全库零处外部赋值

代价与边界。 --double-buffer 把 imageCount 降到 2 时,删除晚一帧、只多留内存;驱动把 imageCount 夹逼到 4 或 5 时,删除可能早于 GPU 用完,使用中对象被 unref() 归零并析构。两种方向不对称,后一种才是事故,而代码没有任何一处比较这两个数。

16.9.4 frameCount 作为公开 atomic 的冗余与与前面章节的交叉引用

逐字段推导。 frameCount(include/vsg/threading/DeleteQueue.h:38)虽是 std::atomic_uint64_t,每次读写都在 _mutex 内:advance() 写于 scoped_lock(src/vsg/threading/DeleteQueue.cpp:34-36)、add() 系列读于 scoped_lock(include/vsg/threading/DeleteQueue.h:49/57/84/99)、wait_then_clear() 读于 unique_lock(:53/56/60)。原子性冗余,去掉 atomic 功能不变。真正的边界是可见性:public 原子允许外部写小值,advance() 又不校验单调,破坏 16.9.2 的有序假设。

与前面章节的交叉引用。 第十五章批判性结论第二条把「在飞帧数」归为三个常量与两个隐式契约共同决定;本章 16.9 把这个结论推进到删除侧,并指出第四套计数 1 + numValidTasks(16.4.3)与第五套「依赖归零」判据同样独立:Fence::resetFenceAndDependencies() 在 src/vsg/vk/Fence.cpp:44 对 _dependentSemaphores 逐项 numDependentSubmissions().exchange(0)、在 :49 对 _dependentCommandBuffers 做同样动作。

16.10 延迟删除与引用计数的回收路径

16.10.1 源码摘录:ObjectToDelete 持有的是 ref_ptr

// include/vsg/threading/DeleteQueue.h:30-36
        struct ObjectToDelete
        {
            uint64_t frameCount = 0;
            ref_ptr<Object> object;
        };

        using ObjectsToDelete = std::list<ObjectToDelete>;
// include/vsg/core/ref_ptr.h:26-33 / 67-69
        ref_ptr() noexcept :
            _ptr(nullptr) {}

        ref_ptr(const ref_ptr& rhs) noexcept :
            _ptr(rhs._ptr)
        {
            if (_ptr) _ptr->ref();
        }
...
        ~ref_ptr()
        {
            if (_ptr) _ptr->unref();
        }

逐字段推导。 ObjectToDelete{frameCount + retainForFrameCount, object}(include/vsg/threading/DeleteQueue.h:50)聚合初始化时,ref_ptr<Object> 拷贝构造触发 include/vsg/core/ref_ptr.h:32 的 _ptr->ref(),所以 add() 后对象至少两份引用。16.8.3 的「不去重」意味着同一对象两次入队产生两个节点、两次 ref(),对应 clear() 时两次 unref();调用方释放次数与之不配对时,最后一次 unref() 会作用在已析构对象上。

16.10.2 unref 的内存序与 _attemptDelete

// include/vsg/core/Object.h:121-128
        // ref counting methods
        inline void ref() const noexcept { _referenceCount.fetch_add(1, std::memory_order_relaxed); }
        inline void unref() const noexcept
        {
            if (_referenceCount.fetch_sub(1, std::memory_order_seq_cst) <= 1) _attemptDelete();
        }
        inline void unref_nodelete() const noexcept { _referenceCount.fetch_sub(1, std::memory_order_seq_cst); }
        inline unsigned int referenceCount() const noexcept { return _referenceCount.load(); }
// src/vsg/core/Object.cpp:84-94
void Object::_attemptDelete() const
{
    // if there is an auxiliary attached signal to it we wish to delete, and give it an opportunity to decide whether a delete is appropriate.
    // if no auxiliary is attached then go straight ahead and delete.
    if (_auxiliary == nullptr || _auxiliary->signalConnectedObjectToBeDeleted())
    {
        delete this;
    }
    else
    {
        debug("Object::_delete() ", this, " choosing not to delete");
    }
}

逐分支推导。 unref()(include/vsg/core/Object.h:125)的 fetch_sub(1, std::memory_order_seq_cst) <= 1 与 Latch::count_down()(include/vsg/threading/Latch.h:53)是同一判据模板,但这里 <= 1 必要:计数从 1 起步,返回值小于 1 只能是误用。成立时进 _attemptDelete()(src/vsg/core/Object.cpp:84),由 _auxiliary == nullptr 或 signalConnectedObjectToBeDeleted() 同意才 delete this(:94)。ref() 用 relaxed、unref() 用 seq_cst 是刻意不对称:减到零时须让此前所有写 happens-before 析构,属正确实现。

16.10.3 operator delete 与 Allocator

// src/vsg/core/Object.cpp:241-244
void Object::operator delete(void* ptr)
{
    vsg::deallocate(ptr);
}

逐分支推导。 Object::_attemptDelete() 在 _auxiliary == nullptr || _auxiliary->signalConnectedObjectToBeDeleted() 为真时才执行 delete this(src/vsg/core/Object.cpp:94),后者最终落到 Object::operator delete(:241),它调用 vsg::deallocate(ptr)(include/vsg/core/Allocator.h:89),与 Object::operator new(:238,调用 vsg::allocate(count, vsg::ALLOCATOR_AFFINITY_OBJECTS))配对。Allocator 的单例由 Allocator::instance()(include/vsg/core/Allocator.h:51)提供,nestedAllocator(:83)保留旧分配器以便回收它分配过的块——第二章展开过这套内存池。

代价与边界。 这条链意味着 SharedObjects::prune() 与 Vulkan 句柄销毁不在 DeleteQueue 里:VkImage、VkBuffer 等由各自对象的析构函数(Swapchain.cpp:135-152 的 SwapchainImage 主动放弃 VkImage 所有权、Surface::release() 把销毁责任交还第三方)另行处理。

16.10.4 本机 ABI 相关的尺寸测量

sizeof(ObjectToDelete)、sizeof(ref_ptr<Object>)、sizeof(std::atomic_uint64_t) 这些数字依赖编译器、标准库实现与本机 Vulkan SDK 头文件版本,写进文档必然过期,因此本章不给具体字节数,只给可在本机直接编译运行的测量程序,结论以本机 SDK 为准:

// 测量程序:在 VSG 构建环境内编译,输出以本机编译器与 Vulkan SDK 为准
#include <vsg/threading/DeleteQueue.h>
#include <vsg/core/Object.h>
#include <vsg/core/ref_ptr.h>
#include <atomic>
#include <cstdio>
int main()
{
    std::printf("sizeof(ref_ptr<vsg::Object>) = %zu\n", sizeof(vsg::ref_ptr<vsg::Object>));
    std::printf("sizeof(vsg::DeleteQueue::ObjectToDelete) = %zu\n", sizeof(vsg::DeleteQueue::ObjectToDelete));
    std::printf("sizeof(std::atomic_uint64_t) = %zu\n", sizeof(std::atomic_uint64_t));
    std::printf("alignof(vsg::DeleteQueue::ObjectToDelete) = %zu\n", alignof(vsg::DeleteQueue::ObjectToDelete));
    std::printf("sizeof(std::list<...>::node padding) 依赖标准库实现,以本机输出为准\n");
    return 0;
}

读者据此可以自行核对 16.8.3 提到的「每个 add() 一个 list 节点」在本机的真实内存代价;同样的做法适用于第十五章讨论的 VkSubmitInfo、VkPresentInfoKHR 等结构体,凡依赖 Vulkan SDK 的尺寸都不写死数值。

与前面章节的交叉引用。 第一章的 Auxiliary/Object、第二章的 Allocator、本章的 DeleteQueue 是同一条回收链的三个环节;第十五章 Fence::resetFenceAndDependencies() 按 exchange(0) 归零依赖则是另一条链,两条链在 16.17 交汇。


16.11 Viewer 主循环的同步时序

16.11.1 四个阶段与 FrameStamp 的创建点

// src/vsg/app/Viewer.cpp:155-205(advanceToNextFrame 节选)
    if (!active())
    {
        return false;
    }
    pollEvents(true);
    if (!acquireNextFrame()) return false;
    ...
        _frameStamp = FrameStamp::create(time, _frameStamp->frameCount + 1, simulationTime);
    ...
    for (auto& task : recordAndSubmitTasks)
    {
        task->advance();
    }
    // create an event for the new frame.
    _events.emplace_back(new FrameEvent(_frameStamp));

逐分支推导。 advanceToNextFrame()(:155)依次 active()(:162)、pollEvents(true)(:168)、acquireNextFrame()(:170),再在 :181/191 造新 FrameStamp。:199 的 task->advance() 是 RecordAndSubmitTask::advance()(src/vsg/app/RecordAndSubmitTask.cpp:46-70),推进 _currentFrameIndex 与 _indices,不是 DeleteQueue::advance()。

16.11.2 update 到 deleteQueue->advance

// src/vsg/app/Viewer.cpp:793-806
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);
        }
    }
    ...
}

逐分支推导。 update()(:793)遍历每个 task 的 databasePager,把 _frameStamp 传进 updateSceneGraph()(src/vsg/io/DatabasePager.cpp:660),后者在 :665 调 deleteQueue->advance(frameStamp)。所以 DeleteQueue 的帧号来源既不是 swapchain 也不是 fence,而是 Viewer::_frameStamp。

16.11.3 recordAndSubmit 的 set 与 arrive_and_wait

recordAndSubmit()(:820)先在 :824-830 逐个 commandGraph->reset(),再在 :842 set(_frameStamp)、:843 arrive_and_wait();次序不可交换,否则记录线程未唤醒,:843 一直等。

16.11.4 帧序号错位与与前面章节的交叉引用

代价与边界。 第十五章批判性结论第三条指出 present 与 submit 通过 Window::Frame 隐式耦合:window->acquireNextImage() 返回 VK_SUBOPTIMAL_KHR(src/vsg/app/Viewer.cpp:225)时主循环会 window->resize(),恰好破坏「imageIndex 不变」这条契约。

与前面章节的交叉引用。 第十四章 14.x 的死锁问题落在 :843;第十五章的 numBuffers = 3 落在 :501;本章 16.4.3 的 1 + numValidTasks 落在 :621;16.9.3 的 retainForFrameCount = 3 落在 include/vsg/threading/DeleteQueue.h:39。四个数字在 Viewer.cpp 与 DatabasePager.cpp 两个文件里各自为政,构成批判性结论第二条的素材。


16.12 DatabasePager:DeleteQueue 的唯一宿主

16.12.1 装配与删除线程

// src/vsg/io/DatabasePager.cpp:490-501 / 615-634
DatabasePager::DatabasePager()
{
    if (!status) status = ActivityStatus::create();
    culledPagedLODs = CulledPagedLODs::create();
    _requestQueue = DatabaseQueue::create(status);
    _toMergeQueue = DatabaseQueue::create(status);
    deleteQueue = DeleteQueue::create(status);
    pagedLODContainer = PagedLODContainer::create(4000);
}
...
    auto deleteThread = [](DatabasePager& databasePager, const std::string& threadName) {
        debug("Started DatabaseThread deletethread");
        auto local_instrumentation = shareOrDuplicateForThreadSafety(databasePager.instrumentation);
        if (local_instrumentation) local_instrumentation->setThreadName(threadName);
        while (databasePager.status->active())
        {
            databasePager.deleteQueue->wait_then_clear();
        }
        debug("Finished DatabaseThread delete thread");
    };
...
    threads.emplace_back(deleteThread, std::ref(*this), "DatabasePager delete thread ");

逐分支推导。 :498 用 DatabasePager 自己的 status(:492)造 deleteQueue;deleteThread(:621-624)以 status->active() 为循环条件,循环体只有 wait_then_clear()(:623);:633 只起一个删除线程,与 16.8.3 的 notify_one() 匹配。

16.12.2 updateSceneGraph 与 add_prune

// src/vsg/io/DatabasePager.cpp:660-667 / 791
void DatabasePager::updateSceneGraph(ref_ptr<FrameStamp> frameStamp, CompileResult& cr)
{
    CPU_INSTRUMENTATION_L1(instrumentation);

    frameCount.exchange(frameStamp ? frameStamp->frameCount : 0);
    deleteQueue->advance(frameStamp);

    numActiveRequests -= _requestQueue->prune(frameCount.load());
...
    if (!deleteList.empty() || !sharedObjectsToPrune.empty()) deleteQueue->add_prune(deleteList, sharedObjectsToPrune);

逐分支推导。 :664 把 DatabasePager::frameCount(include/vsg/io/DatabasePager.h:144,atomic_uint64_t)置成本帧号,并显式容忍空 frameStamp;:665 把同一个 frameStamp 传给 DeleteQueue::advance(),构成 16.8.4 的空指针缺陷。

16.12.3 与 CompileManager 的交接

逐分支推导。 compileManager(include/vsg/io/DatabasePager.h:141)在编译线程累加 successfulCompileCount 与 failedCompileCount(include/vsg/app/CompileManager.h:105-106),点在 src/vsg/app/CompileManager.cpp:377/381;二者与 DeleteQueue 无数据通路,失败子图是否进 deleteList 由 culledPagedLODs 决定(:674 后)。

代价与边界。 DatabasePager 与 Viewer 的 status 是两份(16.2.2),stopThreading() 关不掉 deleteThread;~DatabasePager()(src/vsg/io/DatabasePager.cpp:503-505)只有 debug,无 set(false) 与 join(),可接合的 std::thread 析构会 std::terminate。

与前面章节的交叉引用。 第十九章的 DatabasePager、第十二章的 CompileManager、本章的 DeleteQueue 三者通过 updateSceneGraph()(:660)串成一条链;第十五章的 RecordAndSubmitTask::advance() 与它同名但不同物,16.11.1 已辨析。


16.13 std::atomic 内存序全库盘点

16.13.1 memory_order 只有三处

// include/vsg/core/Object.h:122-127
        inline void ref() const noexcept { _referenceCount.fetch_add(1, std::memory_order_relaxed); }
        inline void unref() const noexcept
        {
            if (_referenceCount.fetch_sub(1, std::memory_order_seq_cst) <= 1) _attemptDelete();
        }
        inline void unref_nodelete() const noexcept { _referenceCount.fetch_sub(1, std::memory_order_seq_cst); }

实测 grep -rn "memory_order" include/ src/ | wc -l 得 3,三处全在 include/vsg/core/Object.h:122/125/127::122 的 _referenceCount.fetch_add(1, std::memory_order_relaxed) 是全库唯一刻意放宽的一处。其余原子操作都用默认 std::memory_order_seq_cst,逐文件点出本文件成员,避免一句里混进别的文件符号:

  • include/vsg/threading/ActivityStatus.h:27 — _active.exchange(flag) 用默认序。
  • include/vsg/threading/Latch.h:37 — _count.exchange(0) 用默认序。
  • include/vsg/threading/DeleteQueue.h:38 — frameCount 与 retainForFrameCount 紧邻,用默认序。
  • include/vsg/io/DatabasePager.h:143 — numActiveRequests 用默认序。
  • include/vsg/nodes/PagedLOD.h:87 — priority 用默认序,七个原子成员同。
  • include/vsg/vk/CommandBuffer.h:76 — _numDependentSubmissions 用默认序。
  • include/vsg/vk/Semaphore.h:43 — _numDependentSubmissions 用默认序。
  • include/vsg/app/CompileManager.h:105 — successfulCompileCount 用默认序。
  • include/vsg/utils/Profiler.h:50 — threadNames、frameIndices 旁边的 index 用默认序。

16.13.2 ref 用 relaxed、unref 用 seq_cst 的正确性

逐分支推导。 16.10.2 已判定这是刻意的不对称:ref() 只增加计数,对象在此前已被某个 ref_ptr 持有,无需与其他线程建立同步;unref() 减到零时要 delete this,必须让此前所有线程对对象的写 happens-before 析构,seq_cst 的 fetch_sub 提供这一保证。unref_nodelete()(:127)同样用 seq_cst,因为它常与观察者指针配合,需要相同的可见性。

16.13.3 其余 26 行的默认 seq_cst

逐分支推导。 默认 seq_cst 是安全上界:ActivityStatus::_active(include/vsg/threading/ActivityStatus.h:38)只是退出标志,Latch::_count(include/vsg/threading/Latch.h:89)的写者受 release() 锁协议约束,DeleteQueue::frameCount(include/vsg/threading/DeleteQueue.h:38)读写都在 _mutex 内——用 relaxed 也够。真正要紧的是 include/vsg/nodes/PagedLOD.h:87-107 七个 mutable std::atomic 成员(含 priority),默认全序让「先读 priority 再读 requestStatus」保持全序,代价是遍历热路径上的多次全序读。

16.13.4 atomics.h 四个模板与两个零调用

// include/vsg/threading/atomics.h:20-50
    template<typename T>
    void exchange_if_lower(std::atomic<T>& reference, T t)
    {
        T original_value = reference.load();
        while (t < original_value && !reference.compare_exchange_weak(original_value, t)) {}
    };
...
    template<typename T>
    void exchange_if_greater(std::atomic<T>& reference, T t)
    {
        T original_value = reference.load();
        while (t > original_value && !reference.compare_exchange_weak(original_value, t)) {}
    };
...
    template<typename T>
    void exchange_multiply(std::atomic<T>& reference, T t)
    {
        T original_value = reference.load();
        while (!reference.compare_exchange_weak(original_value, original_value * t)) {}
    };
...
    template<typename T>
    bool compare_exchange(std::atomic<T>& reference, T from, T to)
    {
        T original_value = from;
        return reference.compare_exchange_strong(original_value, to);
    };

逐分支推导。 四个模板都用 compare_exchange_weak/strong 的 CAS 循环,exchange_if_lower(:22)与 exchange_if_greater(:30)在条件不成立时直接退出,exchange_multiply(:38)无条件循环到成功,compare_exchange(:46)用 strong 且把 original_value 初始化为 from,返回是否命中。实测调用点:compare_exchange 命中 src/vsg/app/RecordTraversal.cpp:224 之外,还有 src/vsg/io/DatabasePager.cpp:542/565/638/733/771 五处;exchange_if_greater 只有 src/vsg/app/RecordTraversal.cpp:224 一处;exchange_if_lower(:22)与 exchange_multiply(:38)零调用。

代价与边界。 compare_exchange_weak 的虚假失败会在循环里更新 original_value,写法正确;exchange_multiply 以 original_value * t 为期望新值,无符号溢出会静默回绕。四个函数都默认 seq_cst。

与前面章节的交叉引用。 第十九章 DatabasePager 的 requestStatus 状态机用的正是 compare_exchange(src/vsg/io/DatabasePager.cpp:638),本章 16.12.3 已点出这条交接;第一章 Object::ref() 用 relaxed 是全库唯一刻意放宽的位置,与这里四个模板的默认 seq_cst 形成对照。


16.14 std::mutex 与 std::condition_variable 分布

六处 cv 的声明形态以 Barrier 为例,两个成员紧邻:

// include/vsg/threading/Barrier.h:73-74
        std::mutex _mutex;
        std::condition_variable _cv;

16.14.1 六处 condition_variable

实测 grep -rln "std::condition_variable" include/ src/ 六个文件、grep -rn "std::condition_variable" include/ src/ | wc -l 得 6,每文件恰好一处:include/vsg/threading/Barrier.h:74、include/vsg/threading/Latch.h:91、include/vsg/threading/FrameBlock.h:73、include/vsg/threading/DeleteQueue.h:128、include/vsg/threading/OperationQueue.h:137、include/vsg/io/DatabasePager.h。前四个是本章原语,第五个属 ThreadSafeQueue,第六个属第十九章 DatabaseQueue。

16.14.2 40 个文件、126 处 mutex

# 期望:40 个文件路径,末行计数 126
grep -rln "std::mutex" include/ src/ | wc -l
grep -rn "std::mutex" include/ src/ | wc -l

16.14.3 超时只在两处队列,三处原语无超时

等待点完整路径:行号是否带超时退出条件
ThreadSafeQueue::take_when_available()include/vsg/threading/OperationQueue.h:110-133是,wait_for(lock, 100ms)(:120)队列非空或 status->cancel()(:124)
DeleteQueue::wait_then_clear()src/vsg/threading/DeleteQueue.cpp:44-84是,wait_for(lock, 100ms)(:58)队列非空且帧号变化,或 status 关闭
Barrier::arrive_and_wait()include/vsg/threading/Barrier.h:35-47否_phase != my_phase(:45)
Latch::wait()include/vsg/threading/Latch.h:69-76否_count <= 0(:72)
FrameBlock::wait_for_change()include/vsg/threading/FrameBlock.h:57-67否地址变化或 status 关闭(:60)

逐分支推导。 两个带超时的都是队列消费者,用 std::chrono::milliseconds(100)(include/vsg/threading/OperationQueue.h:112、src/vsg/threading/DeleteQueue.cpp:50);三个不带超时的是本章原语,Barrier 与 Latch 连 ActivityStatus 都没有。

代价与边界。 100 ms 硬编码、两处各写局部变量,改一处不同步另一处,与 16.9.3 的三个 3 同属「数字各写各的」。

与前面章节的交叉引用。 第十四章 14.x 的死锁问题在本章被拆成「三个无超时等待点」;第十五章 Viewer::waitForFences() 零调用(陷阱表第 20 行)与这里三个原语无超时叠加,使帧期没有任何一层能主动让步。


16.15 Affinity、线程名与 Tracy 边界

16.15.1 源码摘录

// include/vsg/threading/Affinity.h:23-44
    /// Affinity struct provides a set of cpu ids that a thread can be set to have affinity to.
    struct Affinity
    {
        Affinity() {}

        explicit Affinity(uint32_t cpu, uint32_t num = 1)
        {
            for (uint32_t i = 0; i < num; ++i) cpus.insert(cpu + i);
        }

        std::set<uint32_t> cpus;

        operator bool() const { return !cpus.empty(); }
    };

    /// Set the CPU affinity of specified std::thread
    extern VSG_DECLSPEC void setAffinity(std::thread& thread, const Affinity& affinity);

    /// Set the CPU affinity of current thread
    /// Note, under Linux the CPU affinity of thread is inherited by any threads that it creates
    extern VSG_DECLSPEC void setAffinity(const Affinity& affinity);

逐字段推导。 Affinity(:24-36)只有 std::set<uint32_t> cpus(:33),构造函数按 cpu + i(:30)插入编号,operator bool()(:35)以集合非空表示已指定亲和性;两个 setAffinity 声明(:39、:43)分别作用于指定线程与当前线程。

16.15.2 四平台实现与返回值丢弃

// src/vsg/threading/Affinity.cpp:20-55(Windows 分支节选)
static void win32_setAffinity(HANDLE tid, const vsg::Affinity& affinity)
{
    uint32_t numProcessors = std::thread::hardware_concurrency();

    DWORD_PTR affinityMask = 0x0;
    if (affinity)
    {
        for (auto cpu : affinity.cpus)
        {
            if (cpu < numProcessors)
            {
                affinityMask |= (0x1LL << cpu);
            }
        }
    }
    ...
    /*DWORD_PTR res =*/SetThreadAffinityMask(tid, affinityMask);
}

void vsg::setAffinity(std::thread& thread, const Affinity& affinity)
{
    win32_setAffinity((HANDLE)thread.native_handle(), affinity);
}
// src/vsg/threading/Affinity.cpp:101-111(Android / CYGWIN / OHOS 分支)
#elif defined(__ANDROID__) || defined(__CYGWIN__) || defined(__OHOS__)

void vsg::setAffinity(std::thread&, const Affinity&)
{
    // Not currently implemented
}

void vsg::setAffinity(const Affinity&)
{
    // Not currently implemented
}

逐分支推导。 文件按 _WIN32(:15)、__APPLE__(:57)、__ANDROID__/__CYGWIN__/__OHOS__(:101)、#else // unices(:113)分四支共 154 行。Windows 的 SetThreadAffinityMask(:44)、macOS 的 thread_policy_set(:88)、pthread 的 pthread_setaffinity_np(:141)返回值全被丢弃,三处都不检查失败、不打印告警。

16.15.3 零调用与静默降级

实测 grep -rn "setAffinity" include/ src/ | wc -l 得 19 行,grep -rn "setAffinity" include/ src/ | grep -v "threading/Affinity" | wc -l 得 0 行:19 行全是声明与四个平台分支里的定义。Viewer 起线程处 src/vsg/app/Viewer.cpp:646 的 threads.emplace_back(run, ...),其 run lambda 每帧调 arrive_and_drop();另见 :759/761/766。DatabasePager(src/vsg/io/DatabasePager.cpp:630/633)与 OperationThreads(src/vsg/threading/OperationThreads.cpp:36)同样一次都没调用 setAffinity()。这是 16.0.2 第 9 条硬结论:154 行、四平台、公开导出的能力全库零调用,失败还静默降级;Affinity 构造函数(:28-31)同样零调用。

16.15.4 setThreadName 与 Tracy 边界

实测 grep -rn "setThreadName" src/vsg/app/Viewer.cpp src/vsg/io/DatabasePager.cpp 给出八行:src/vsg/app/Viewer.cpp:631/681/712/731 与 src/vsg/io/DatabasePager.cpp:531/619,另有同行号的 shareOrDuplicateForThreadSafety(...)。每个后台线程先复制 instrumentation 再 setThreadName。

代价与边界。 这些名字只在 Instrumentation 存在时生效(if (local_instrumentation) 判空),而 Instrumentation 的实现之一是 TracyInstrumentation(include/vsg/utils/TracyInstrumentation.h,254 行),第二十七章展开 Tracy 的 FrameMark、ZoneScoped 与线程名注册时会用到这条边界。

与前面章节的交叉引用。 第二十七章的 Tracy 边界在这里落到 setThreadName 八处调用;第十五章的 CPU_INSTRUMENTATION_L1_NC(src/vsg/app/Viewer.cpp:638/688/719/738)与本章 16.4 的三个 run_* lambda 是同一批线程,Instrumentation 的线程安全复制是它们能并发记录的前提。


16.16 OperationQueue / OperationThreads:本章原语的对照组

16.16.1 100 ms 超时与与前面章节的交叉引用

// include/vsg/threading/OperationQueue.h:110-133
        value_type take_when_available()
        {
            std::chrono::duration waitDuration = std::chrono::milliseconds(100);

            std::unique_lock lock(_mutex);

            // wait until the conditional variable signals that an operation has been added
            while (_queue.empty() && _status->active())
            {
                // debug("Waiting on condition variable");
                _cv.wait_for(lock, waitDuration);
            }

            // if the threads we are associated with should no longer be running go for a quick exit and return nothing.
            if (_status->cancel())
            {
                return {};
            }

            // remove and return the head of the queue
            auto operation = _queue.front();
            _queue.erase(_queue.begin());
            return operation;
        }

逐分支推导。 while (_queue.empty() && _status->active())(:117)与 FrameBlock::wait_for_change()(include/vsg/threading/FrameBlock.h:60)同构,差别是 wait_for(:120)带 100 ms 超时并在退出后复查 cancel()(:124)。

16.16.2 stop() 二次 join

// src/vsg/threading/OperationThreads.cpp:40-63
OperationThreads::~OperationThreads()
{
    stop();
}
...
void OperationThreads::stop()
{
    status->set(false);

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

    threads.clear();
}

逐分支推导。 stop()(:53-63)先 status->set(false)(:55)再裸 join()(:59),没有 joinable() 保护;~OperationThreads()(:40-43)又无条件再调一次。显式 stop() 后析构时,第二次 join() 抛 std::system_error。

代价与边界。 stop() 不 notify,依赖 take_when_available() 的 100 ms 超时自行重查 active()(include/vsg/threading/OperationQueue.h:117),因此停止延迟上限 100 ms;Viewer 侧用 wake() 可以立即收敛(16.2.3)。

与前面章节的交叉引用。 第十七章 read.cpp:169 的 operationThreads->run() 与 :172 的 latch->wait() 都建立在这个队列之上;16.6.3 的异常穿透(src/vsg/threading/OperationThreads.cpp:29)与本节二次 join() 是同一文件里两处不同的收尾缺口。


16.17 Fence 依赖归零与两套延迟删除

16.17.1 源码摘录

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

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

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

    reset();
}

逐分支推导。 两轮 exchange(0) 后清两个容器再 reset()(:55,即 vkResetFences,:63-66)。numDependentSubmissions() 返回 std::atomic_uint&(include/vsg/vk/CommandBuffer.h:37、include/vsg/vk/Semaphore.h:31),成员在 :76 与 :43。

16.17.2 两套判据的冲突

逐分支推导。 fence 按「依赖列表归零」判安全,DeleteQueue 按「帧号差 ≥ 3」判安全(16.9.1),没有共享变量:Fence 不读 DeleteQueue::frameCount,advance() 不读 numDependentSubmissions()。src/vsg/app/RecordAndSubmitTask.cpp:248 的 current_fence->dependentSemaphores() = signalSemaphores; 整体赋值冲掉 :239 推入的 renderFinishedSemaphore,缩短 fence 侧名单而帧数不变。

代价与边界。 统一有两条:把 retainForFrameCount 绑定到 fence 数(16.9.3),或让 advance() 在帧数之外兼查 numDependentSubmissions() == 0,把帧数降级为下界。两条都要动 DeleteQueue 公开面与 DatabasePager 装配。

16.17.3 与前面章节的交叉引用

与前面章节的交叉引用。 第十五章批判性结论第二条把 numBuffers、imageCount、retainForFrameCount 并列,本章 16.9.3 沿用;第十五章预告第五问点名 RecordAndSubmitTask.cpp:248 的覆盖缺陷,本节给出它在两套删除判据里的具体后果。


16.18 关键行的逐字摘录

前面各节用文字点到的关键行在此原样摘出;每条结论都只能由读代码得出。

// src/vsg/vk/Fence.cpp:26-28
    if (VkResult result = vkCreateFence(*device, &createFenceInfo, _device->getAllocationCallbacks(), &_vkFence); result != VK_SUCCESS)
    {
        throw Exception{"Error: Failed to create Fence.", result};

vkCreateFence 失败即抛 Exception,构造不返回半成品。

// src/vsg/vk/Fence.cpp:63-66
VkResult Fence::reset() const
{
    return vkResetFences(*_device, 1, &_vkFence);
}

reset() 把 vkResetFences 的 VkResult 原样返回。

// src/vsg/vk/Fence.cpp:58-61
VkResult Fence::wait(uint64_t timeout) const
{
    return vkWaitForFences(*_device, 1, &_vkFence, VK_TRUE, timeout);
}

wait() 传 VK_TRUE,等待全部(此处仅一个)fence。

// include/vsg/vk/Semaphore.h:28-31
        VkPipelineStageFlags& pipelineStageFlags() { return _pipelineStageFlags; }
        const VkPipelineStageFlags& pipelineStageFlags() const { return _pipelineStageFlags; }

        std::atomic_uint& numDependentSubmissions() { return _numDependentSubmissions; }

numDependentSubmissions() 返回 _numDependentSubmissions 引用。

// include/vsg/vk/Semaphore.h:41-43
        VkSemaphore _semaphore;
        VkPipelineStageFlags _pipelineStageFlags = VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT;
        std::atomic_uint _numDependentSubmissions{0};

_numDependentSubmissions{0} 初值就是 0。

// include/vsg/vk/CommandBuffer.h:35-37
        VkCommandBuffer vk() const { return _commandBuffer; }

        std::atomic_uint& numDependentSubmissions() { return _numDependentSubmissions; }

vk() 与 numDependentSubmissions() 同处 public 区。

// include/vsg/vk/CommandBuffer.h:73-76
        VkCommandBuffer _commandBuffer;
        VkCommandBufferLevel _level;

        std::atomic_uint _numDependentSubmissions{0};

_level 与 _numDependentSubmissions 相邻,后者亦从 0 起步。

16.18.2 Viewer 与 DatabasePager 装配

// src/vsg/app/RecordAndSubmitTask.cpp:32-35
    _fences.resize(numBuffers);
    for (uint32_t i = 0; i < numBuffers; ++i)
    {
        _fences[i] = Fence::create(device);

_fences 长度由 numBuffers 决定。

// src/vsg/app/RecordAndSubmitTask.cpp:54-56
        _currentFrameIndex = 0;
    ...
    }

advance() 首帧把 _currentFrameIndex 回绕到 0。

// src/vsg/app/RecordAndSubmitTask.cpp:134-137
        uint64_t timeout = std::numeric_limits<uint64_t>::max();
        if (VkResult result = current_fence->wait(timeout); result != VK_SUCCESS) return result;

        current_fence->resetFenceAndDependencies();

start() 等完 fence 后调 resetFenceAndDependencies()。

// src/vsg/app/RecordAndSubmitTask.cpp:238-239
        vk_signalSemaphores.emplace_back(frame.renderFinishedSemaphore->vk());
        current_fence->dependentSemaphores().push_back(frame.renderFinishedSemaphore);

:239 把 renderFinishedSemaphore 推入依赖列表。

// src/vsg/app/RecordAndSubmitTask.cpp:248-250
    current_fence->dependentSemaphores() = signalSemaphores;
    for (auto& semaphore : signalSemaphores)
    {

:248 的整体赋值覆盖依赖列表。

// include/vsg/vk/Swapchain.h:35-37
    struct SwapchainPreferences
    {
        uint32_t imageCount = 3; // default to triple buffering

imageCount = 3 是 SwapchainPreferences 首字段。

// include/vsg/io/DatabasePager.h:141-144
        ref_ptr<CompileManager> compileManager;

        std::atomic_uint numActiveRequests{0};
        std::atomic_uint64_t frameCount{0};

compileManager 与两个原子计数并列公开。

// src/vsg/app/CompileManager.cpp:375-378
    if (result.result == VK_SUCCESS)
    {
        ++successfulCompileCount;
    }

successfulCompileCount 在 VK_SUCCESS 分支自增。

// include/vsg/app/CompileManager.h:105-106
        std::atomic_uint successfulCompileCount{0};
        std::atomic_uint failedCompileCount{0};

两个计数器都是 std::atomic_uint。

// include/vsg/nodes/PagedLOD.h:87-90
        mutable std::atomic<double> priority{0.0};

        mutable std::atomic_uint64_t frameHighResLastUsed{0};
        mutable std::atomic_uint requestCount{0};

priority 是 atomic<double>,紧跟两个原子计数。

// src/vsg/threading/OperationThreads.cpp:17-20
OperationThreads::OperationThreads(uint32_t numThreads, ref_ptr<ActivityStatus> in_status) :
    status(in_status)
{
    if (!status) status = ActivityStatus::create();

构造里 if (!status) 兜底。

// include/vsg/threading/OperationQueue.h:85-90
        {
            std::unique_lock lock(_mutex);
    ...
            objects.swap(_queue);

take_all() 用 swap 一次取空。

16.18.3 队列、回收链与平台实现

// src/vsg/commands/ExecuteCommands.cpp:31-33
void ExecuteCommands::connect(ref_ptr<SecondaryCommandGraph> commandGraph)
{
    _commandGraphsAndBuffers.push_back(CommandGraphAndBuffer{commandGraph, {}});

connect() push 的空槽由 completed() 填。

// src/vsg/io/read.cpp:174-177
    else
    {
        // run reads single threaded
        for (auto& filename : filenames)

单线程分支不创建 Latch。

// src/vsg/threading/Affinity.cpp:57-62

#    include <mach/mach.h>
#    include <pthread.h>
    ...
static void macos_setAffinity(pthread_t thread_native_handle, const vsg::Affinity& affinity)

macOS 支路的 integer_t cpuset 只有 32 位。

// src/vsg/app/Viewer.cpp:603-608
    for (const auto& task : recordAndSubmitTasks)
    {
    ...
            ++numValidTasks;

numValidTasks 按非空 commandGraphs 现场数出。

// src/vsg/app/Viewer.cpp:686-690
                {
                    CPU_INSTRUMENTATION_L1_NC(local_instrumentation, "Viewer primary", COLOR_RECORD);
    ...
                    // primary thread starts the task

primary 先调 task->start()。

// src/vsg/app/Viewer.cpp:721-724
                    data->recordStartBarrier->arrive_and_wait();

                    commandGraph->record(data->recordedCommandBuffers, frameStamp, data->task->databasePager);

secondary 调 commandGraph->record()。

// src/vsg/app/Viewer.cpp:740-743
                    data->recordStartBarrier->arrive_and_wait();

                    //vsg::info("run_transfer");

transfer 先到 recordStartBarrier。

// src/vsg/app/Viewer.cpp:824-830
    for (const auto& recordAndSubmitTask : recordAndSubmitTasks)
    {
    ...
        }

recordAndSubmit() 逐个 commandGraph->reset()。

// src/vsg/io/DatabasePager.cpp:621-624
        while (databasePager.status->active())
        {
            databasePager.deleteQueue->wait_then_clear();
        }

删除线程循环体只有 wait_then_clear()。

// include/vsg/utils/TracyInstrumentation.h:120-122
        void setThreadName(const std::string& name) const override
        {
            tracy::SetThreadName(name.c_str());

setThreadName 直达 tracy::SetThreadName。

// include/vsg/app/Viewer.h:165-167
        bool _threading = false;
        ref_ptr<FrameBlock> _frameBlock;
        ref_ptr<Barrier> _submissionCompleted;

_frameBlock 与 _submissionCompleted 都是私有 ref_ptr。

// include/vsg/threading/DeleteQueue.h:68-70
        void prune(ref_ptr<SharedObjects> sharedObjects)
        {
            std::scoped_lock lock(_mutex);

prune() 取 _mutex 后用 std::find 去重。

# 交叉核对:文件:行号与该行符号
# src/vsg/vk/Fence.cpp:36 vkDestroyFence
# src/vsg/vk/Fence.cpp:60 vkWaitForFences
# include/vsg/vk/Semaphore.h:25 _semaphore
# src/vsg/app/RecordAndSubmitTask.cpp:70 _indices
# src/vsg/io/DatabasePager.cpp:630 readThread
# src/vsg/threading/Affinity.cpp:64 numProcessors
# include/vsg/nodes/PagedLOD.h:95 RequestStatus
# include/vsg/app/CompileManager.h:106 failedCompileCount

数字表与源码索引

按文件分组,逐条给出 完整路径:行区间 与结论,全部经过 wc -l / grep -n / sed -n 实测。

include/vsg/threading/ActivityStatus.h(42 行)::24 默认 active = true;:27 exchange(flag) 丢弃旧值,等价 seq_cst store;:30/33 active() 隐式 load、cancel() 取反,全库两处调用;:38 std::atomic_bool _active 是全库唯一退出开关载体。

include/vsg/threading/Barrier.h(78 行)::26-29 三个字段初值;:35-47 arrive_and_wait() 两分支,:45 带谓词无超时;:50-57 arrive_and_drop() 只加计数不登记退出;:62-67 _release() 清零、++_phase、notify_all();:69-74 const uint32_t _num_threads 与 _mutex/_cv。

include/vsg/threading/Latch.h(95 行)::27-31 size_t 构造窄化为 int;:33-44 set() 零值 exchange(0)、非零直接写;:51-62 count_down() 的 <= 1 判据;:69-82 wait() 手动 while 与 release() 持锁通知;:89-91 atomic_int _count 与双轨 _mutex/_cv。

include/vsg/threading/FrameBlock.h(79 行)::27 initial_value 为空 ref_ptr;:36-47 set() 写值通知、get() 零调用;:49/51-55 active() 转发、wake() 只通知不改值;:57-67 wait_for_change() 指针相等与状态双重条件;:72-75 四个字段。

include/vsg/threading/DeleteQueue.h(136 行)::30-36 ObjectToDelete 与 std::list 选型;:38-40 三个 public 计数器,:39 默认 3;:47-66 两个 add() 统一 frameCount + 3 与 notify_one();:68-94 两个 prune() 用 std::find 查重;:96-114 add_prune() 合批;:116-122 wait_then_clear()/clear() 声明;:124-133 五个 protected 成员。

src/vsg/threading/DeleteQueue.cpp(121 行)::23-30 构造存 _status、析构空实现;:32-42 advance() 写帧号并按队首到期 notify_one();:44-84 wait_then_clear() 的等待条件、splice、swap、条件 prune;:86-121 clear() 与前者逐行对应,全库零调用。

src/vsg/threading/Affinity.cpp(154 行)::15-55 Windows 分支,:44 丢弃 SetThreadAffinityMask 返回值;:57-99 macOS 分支,:88 丢弃 thread_policy_set 返回值;:101-111 Android/CYGWIN/OHOS 空实现;:113-152 pthread 分支,:141 丢弃返回值。

include/vsg/threading/OperationQueue.h(156 行)::46-75 两个 add() 与 notify_one/notify_all 分派;:85-93 take_all() 用 swap;:110-133 take_when_available() 的 100 ms 超时;:146-153 Operation 基类与 OperationQueue 别名。

src/vsg/threading/OperationThreads.cpp(63 行)::17-38 构造、默认 status、无 try/catch 的线程函数;:40-43 析构无条件调 stop();:53-63 stop() 裸 join()。

include/vsg/threading/atomics.h(52 行)::22/30/38/46 四个 CAS 模板,:22、:38 零调用,:46 在 src/vsg/io/DatabasePager.cpp 有五处调用。

src/vsg/app/Viewer.cpp(892 行)::33 status(ActivityStatus::create());:155-205 advanceToNextFrame(),:181/191 每帧造新 FrameStamp,:199 调 RecordAndSubmitTask::advance();:501 numBuffers = 3;:598-621 setupThreading() 与 Barrier::create(1 + numValidTasks);:626-646 单 CommandGraph 分支,:642 arrive_and_drop();:648-768 SharedData 三道屏障与三个 run_*;:772-791 stopThreading();:793-818 update() 与 updateSceneGraph(_frameStamp, cr);:833-851 _frameBlock->set() 与 arrive_and_wait()。

include/vsg/app/Viewer.h(174 行)::129/130/160/165-167 status、threads、_frameStamp、_threading、_frameBlock、_submissionCompleted 声明;:102 advanceToNextFrame()。

src/vsg/io/DatabasePager.cpp(792 行)与 include/vsg/io/DatabasePager.h(180 行)::490-501 构造,:498 DeleteQueue::create(status);:615-634 deleteThread 与唯一一次 emplace_back;:660-667 updateSceneGraph() 帧号灌入与 advance();:791 add_prune(...);头文件 :143-144 两个原子计数、:149/152 两个默认常量、:165/167-168 线程与状态成员。

src/vsg/app/RecordAndSubmitTask.cpp(365 行)::29-35 numBuffers 决定 _indices 与 _fences 长度;:46-70 advance() 索引轮转;:130-140 start() 等 fence 并 resetFenceAndDependencies();:239/248 整体赋值冲掉 renderFinishedSemaphore。

src/vsg/vk/Fence.cpp(66 行)::40-56 resetFenceAndDependencies() 两轮 exchange(0);:58-66 wait() 与 reset()。

src/vsg/commands/ExecuteCommands.cpp(83 行)与 include/vsg/commands/ExecuteCommands.h(55 行)::17-20 create(0);:37-47 reset() 持锁 set(size);:49-66 completed() 写 cb 后锁外 count_down();:68-83 record() 先 wait();头文件 :48-49 _mutex 与 _latch。

src/vsg/io/read.cpp(223 行)::131-173 多线程批量读分支,:160 创建 Latch、:172 wait();:147-151 ReadOperation::run() 两行顺序。

include/vsg/core/Object.h(297 行)与 src/vsg/core/Object.cpp(244 行)::122-127 全库仅有的三处显式 memory_order;src/vsg/core/Object.cpp:84-94 _attemptDelete() 与 Auxiliary 裁决;:241-244 operator delete 转 vsg::deallocate()。

其余关联文件,逐文件点出本文件成员,避免跨文件符号混在同一句里:

  • include/vsg/all.h:189 — 从 ActivityStatus.h 起九行 threading 暴露面。
  • include/vsg/vk/Swapchain.h:37 — imageCount = 3 默认三缓冲。
  • include/vsg/app/CompileManager.h:105、src/vsg/app/CompileManager.cpp:377 — successfulCompileCount 在编译成功时自增。
  • include/vsg/utils/TracyInstrumentation.h:120 — setThreadName 是第二十七章 Tracy 边界的落点。
  • include/vsg/core/Auxiliary.h:103 — _referenceCount 与 signalConnectedObjectToBeDeleted() 属第一章回收链。
  • include/vsg/core/ref_ptr.h:29 — 拷贝构造用 _ptr(rhs._ptr) 并调 ref()。
  • include/vsg/core/Allocator.h:87 — nestedAllocator 保留旧分配器,属第二章。
  • include/vsg/vk/CommandBuffer.h:76、include/vsg/vk/Semaphore.h:43 — 两处 _numDependentSubmissions 支撑 numDependentSubmissions()。

可复现验证

以下命令全部在仓库根目录 VulkanSceneGraph-1.1.16 直接运行,输出为本机实测值。

# 期望:末行输出 "1081 total",文件数为 12
wc -l include/vsg/threading/*.h src/vsg/threading/*.cpp | tail -1
find include/vsg/threading src/vsg/threading -type f | wc -l
# 期望:输出 3,且三行都在 include/vsg/core/Object.h 的 122/125/127 行
grep -rn "memory_order" include/ src/ | wc -l
grep -n "memory_order" include/vsg/core/Object.h
# 期望:输出 6;每个文件恰好一处 condition_variable 声明
grep -rn "std::condition_variable" include/ src/ | wc -l
grep -rln "std::condition_variable" include/ src/ | sort
# 期望:第一行 19,第二行 0;说明 setAffinity 全库零调用
grep -rn "setAffinity" include/ src/ | wc -l
grep -rn "setAffinity" include/ src/ | grep -v "threading/Affinity" | wc -l
# 期望:输出 9(8 次 arrive_and_wait + 1 次 arrive_and_drop)
grep -c "arrive_and_wait\|arrive_and_drop" src/vsg/app/Viewer.cpp
grep -n "arrive_and_drop\|Barrier::create" src/vsg/app/Viewer.cpp
# 期望:输出 6,全部在 include/vsg/threading/DeleteQueue.h 内;外部赋值 0 处
grep -rc "retainForFrameCount" include/vsg/threading/DeleteQueue.h
grep -rn "retainForFrameCount" include/ src/ | grep -v "threading/DeleteQueue.h" | wc -l
# 期望:恰好四行 498 / 623 / 665 / 791
grep -n "DeleteQueue::create\|deleteQueue->advance\|wait_then_clear\|add_prune" src/vsg/io/DatabasePager.cpp
# 期望:40 与 126;三个 3 各在不同文件
grep -rln "std::mutex" include/ src/ | wc -l
grep -rn "std::mutex" include/ src/ | wc -l
grep -n "numBuffers = 3\|imageCount = 3\|retainForFrameCount = 3" src/vsg/app/Viewer.cpp include/vsg/vk/Swapchain.h include/vsg/threading/DeleteQueue.h
# 期望:零调用 API 计数全部为 0(排除头文件定义行)
for sym in "count_up()" "is_ready()" "->get()" "cancel()"; do printf "%s: " "$sym"; grep -rn "$sym" include/ src/ | grep -v "threading/Latch.h\|threading/FrameBlock.h\|threading/ActivityStatus.h" | wc -l; done
# 期望:三个无超时等待点与两个带超时等待点的行号
grep -n "_cv.wait(lock)\|_cv.wait_for(lock, waitDuration)\|_cv.wait(lock, \[" include/vsg/threading/Barrier.h include/vsg/threading/Latch.h include/vsg/threading/FrameBlock.h
grep -n "wait_for(lock" include/vsg/threading/OperationQueue.h src/vsg/threading/DeleteQueue.cpp

陷阱表与批判性结论

陷阱表

#陷阱完整路径:行号触发条件与后果规避
1指针相等当帧判据include/vsg/threading/FrameBlock.h:60复用 FrameStamp 只改 frameCount,四个记录线程与主线程全部挂住改比 frameCount,或给 set() 加独立 _generation
2屏障无超时无回滚include/vsg/threading/Barrier.h:45/69参与者提前退出或 submit() 抛异常,_phase 停滞wait_for + 动态参与数 + catch 里回减 _num_arrived
3arrive_and_drop 名实不符include/vsg/threading/Barrier.h:50-57按注释退出参与,下一帧到达数不足改名或让 _num_threads 随 drop 递减
4计数下溢与重复 releaseinclude/vsg/threading/Latch.h:53-56create(0) 起步、无条件 count_down(),计数为负且返回 true判据改 == 1 并钳制下界
5异常跳过 count_downsrc/vsg/io/read.cpp:147-151/172vsg::read() 抛异常,批量读 wait() 永久阻塞析构守卫或 try/catch 补减后重抛
6advance 空指针src/vsg/threading/DeleteQueue.cpp:36Viewer::update() 在首帧前调用,_frameStamp 为空advance() 判空,调用方 if (frameStamp) 保护
7唤醒条件错绑帧号src/vsg/threading/DeleteQueue.cpp:56帧停止推进后仍 add_prune(),到期对象不删、容器只增不减退出条件改「存在到期节点」
8prune 请求静默丢弃src/vsg/threading/DeleteQueue.cpp:72/109只 prune 不 delete 的帧,SharedObjects::prune() 未调用去掉 numObjectsToDelete > 0 前置条件
9find_if 单调假设src/vsg/threading/DeleteQueue.cpp:60/95frameCount 被写小或帧号回退,早到期节点滞留完整遍历摘出到期节点
10setAffinity 零调用且丢返回值src/vsg/threading/Affinity.cpp:44/88/141调用后失败无告警,三平台空实现回传返回值并告警,或删除整套 API
11Latch::create(size_t) 窄化include/vsg/threading/Latch.h:30-31、src/vsg/io/read.cpp:160filenames.size() > INT_MAX,计数为负、wait() 立即返回改用 64 位计数或上界检查
12OperationThreads::stop() 二次 joinsrc/vsg/threading/OperationThreads.cpp:42/59显式 stop() 后再析构,抛 std::system_error加 joinable() 判断与「已停」标志
13FrameBlock 允许空 statusinclude/vsg/threading/FrameBlock.h:29-31/49/60FrameBlock::create({}),active() 与 wait_for_change() 空指针构造函数断言非空
14take_when_available 取 front() 不复查include/vsg/threading/OperationQueue.h:130cancel() 后队列被其他消费者取空:130 前补一次 empty() 判空
15三个 3 互不校正src/vsg/app/Viewer.cpp:501、include/vsg/vk/Swapchain.h:37、include/vsg/threading/DeleteQueue.h:39--double-buffer 或驱动夹逼,保留帧数与实际在飞帧数失配装配期从 window->numFrames() 推导
16两套删除判据无通路src/vsg/vk/Fence.cpp:44/49、src/vsg/threading/DeleteQueue.cpp:95RecordAndSubmitTask.cpp:248 覆盖后,引用计数与帧数结论冲突共享 fence 数或让 advance() 兼查 numDependentSubmissions()
17vkCreateFence 失败即抛异常src/vsg/vk/Fence.cpp:26-28设备内存不足时构造抛 Exception,调用方无降级路径捕获异常并延迟重试
18reset() 的 VkResult 被丢弃src/vsg/vk/Fence.cpp:63-65、src/vsg/app/RecordAndSubmitTask.cpp:137resetFenceAndDependencies() 不查 vkResetFences,fence 仍 signaled 时下次 wait() 提前返回返回 VkResult 并在 start() 上报
19dependentSemaphores 整体覆盖src/vsg/app/RecordAndSubmitTask.cpp:239/248:239 入列的 renderFinishedSemaphore 被 :248 冲掉,归零名单不完整改用 insert 追加或先合并
20imageCount 夹逼与保留帧数脱钩src/vsg/vk/Swapchain.cpp:170-171、include/vsg/threading/DeleteQueue.h:39驱动夹到 4/5 时保留帧数仍为 3,删除早于 GPU 用完按 imageCount 推导保留帧数

三条批判性结论

第一,全部同步原语共享一个结构性缺陷:退出状态是一位的原子布尔,唤醒动作却分散在三把互不知晓的互斥量后面,「停止」永远不是一次原子操作,而是「写状态 + 逐处补通知」的手工序列。 ActivityStatus::_active(include/vsg/threading/ActivityStatus.h:38)是全库唯一退出开关,set(false)(:27)只改一个位、不唤醒任何人。真正让线程退出的是三次各自的 notify_all():Viewer::stopThreading() 的 _frameBlock->wake()(src/vsg/app/Viewer.cpp:784)、DeleteQueue::wait_then_clear() 的 100 ms wait_for(src/vsg/threading/DeleteQueue.cpp:58)、ThreadSafeQueue::take_when_available() 的 100 ms wait_for(include/vsg/threading/OperationQueue.h:120),三把锁、两套超时、一条显式 wake();而 Barrier::_cv(include/vsg/threading/Barrier.h:74)与 Latch::_cv(include/vsg/threading/Latch.h:91)这两处等待点完全没有唤醒路径,DatabasePager 的删除线程用的还是 :492 那份独立 status。于是 Viewer::stopThreading() 能收敛 FrameBlock 上的四个记录线程,却收敛不了停在 :843 的 Barrier、src/vsg/io/read.cpp:172 的 latch->wait()(与 :160 的 Latch::create(static_cast<int>(filenames.size())) 配对)与数据库删除线程。

第二,「延迟删除」的安全性不是被证明的,而是被三个互不相干的字面量 3 与两套互不通信的回收判据临时凑出来的。 src/vsg/app/Viewer.cpp:501 的 numBuffers = 3 决定 fence 数,include/vsg/vk/Swapchain.h:37 的 imageCount = 3 经驱动夹逼决定 swapchain image 数,include/vsg/threading/DeleteQueue.h:39 的 retainForFrameCount = 3 决定保留帧数;实测 grep -rn "retainForFrameCount" include/ src/ 只有 6 行、全在同一头文件、零处外部赋值,三者没有引用关系。更关键的是 DeleteQueue 不在 Viewer 装配路径上:宿主是 DatabasePager(src/vsg/io/DatabasePager.cpp:498),帧号由 Viewer::update() 经 updateSceneGraph()(src/vsg/app/Viewer.cpp:804 → src/vsg/io/DatabasePager.cpp:665)灌入,而 GPU 是否用完由 Fence::resetFenceAndDependencies()(src/vsg/vk/Fence.cpp:40-56)按 exchange(0) 判定,两者没有共享变量。src/vsg/threading/DeleteQueue.cpp:56 又把删除动作绑在「帧号变化」而非「存在到期对象」上:帧一旦停止推进,find_if(:60)因 otd.frameCount > frameCount 恒真而返回 begin(),splice 区间为空,容器只增不减,且 numObjectsToDelete == 0 时 :72 连 SharedObjects::prune() 都跳过。

第三,同步设施分布极不均匀:全库 126 处 std::mutex、6 处 std::condition_variable、29 行 std::atomic 声明,却只有 3 行显式 memory_order,结果「最该被仔细论证的等待条件」反而最缺少形式化约束。 三个显式序都在 include/vsg/core/Object.h:122-127,ref() 用 relaxed、unref() 用 seq_cst 是正确设计;其余 26 处一律默认 seq_cst,包括 ActivityStatus::_active、Latch::_count、DeleteQueue::frameCount 这类用 relaxed 已足够的标志,也包括 include/vsg/nodes/PagedLOD.h:87-107 遍历热路径上的七个原子成员。这种「一律最强」掩盖了真正需要区分之处:Latch 的计数写在锁外(include/vsg/threading/Latch.h:53)、release() 通知在锁内(:80),二者靠默认全序才成立,若有人把 _count 改成 relaxed,wait()(:69)与 count_down() 的检查-等待协议立刻失效,而代码里没有任何注释记录这个依赖。FrameBlock::wait_for_change()(include/vsg/threading/FrameBlock.h:57-67)用「同一把锁 + 原子状态 + 每轮重读」正确挡住第十四章担心的 lost-wakeup,却把帧变化判据建在 ref_ptr 裸指针相等上,等于把正确性外包给 src/vsg/app/Viewer.cpp:181/191 每帧分配新 FrameStamp 这个远在另一个文件的实现细节。


下章预告

本章结束。下一章对齐 README 第 17 章标题「IO 与资源管线:Options、ReaderWriter、read/write」,回答本章留下的六个问题:

  • src/vsg/io/read.cpp:131-173 用 Latch::create(static_cast<int>(filenames.size()))(:160)汇合,ReadOperation::run()(:147-151)异常时漏 count_down();下一章 Options 的错误通道如何回送到 latch->wait()(:172),避免 OperationThreads.cpp:29 的异常穿透?
  • Options(include/vsg/io/Options.h)如何在 ReadOperation(src/vsg/io/read.cpp:139-157)按值传递?ref_ptr<const Options>(:143)与 object(:155)的生命周期由谁保证,与 ObjectToDelete(include/vsg/threading/DeleteQueue.h:30-34)推迟三帧释放是否同一套引用计数?
  • ReaderWriter 的 read/write 签名里 Options 与 Allocator 各在哪一参数位?Object::operator delete → vsg::deallocate()(src/vsg/core/Object.cpp:241-244)反序列化时是否绕过 DeleteQueue 的帧数保留?
  • 单线程分支(src/vsg/io/read.cpp:174-185)不创建 Latch,窄化只在批量分支出现;下一章 read() 重载如何按文件数与 operationThreads 分派,哪几条共用 100 ms 超时?
  • DatabasePager::request()(src/vsg/io/DatabasePager.cpp:638)用 compare_exchange 切 requestStatus;下一章 extensionHint 与 ReaderWriter 注册表如何决定插件,失败后 CompileManager(include/vsg/app/CompileManager.h:105-106)如何记账?
  • IO 侧是否还有第四个常量:targetMaxNumPagedLODWithHighResSubgraphs = 1500(include/vsg/io/DatabasePager.h:149)与 delayBeforeNextLoadAttempt = 60(:152),是否也像 retainForFrameCount = 3 一样全库零校正?