《VulkanSceneGraph 1.1.16 源码深度解析》第十九章 数据库分页:DatabasePager 与 PagedLOD

0 阅读1小时+

《VulkanSceneGraph 1.1.16 源码深度解析》第十九章 数据库分页:DatabasePager 与 PagedLOD

19.0 先把规模和答案摆出来

第十八章收尾时留下六个问题,全部压在同一个转换上:一个文件变成对象之后,成千上万个文件怎样在帧预算内变成对象。那六问依次是——PagedLOD::filename 与 PagedLOD::options 在 read/write 里怎样序列化、从 .vsgb 还原的插件表空槽是否会让子文件失去 ReaderWriter;DatabasePager.cpp:557 把 vsg::read 的返回值存进 read_object 再 cast<Node>() 后,:598 的 cast<ReadError>() 是不是唯一主动识别错误对象的消费点;DatabasePager.h:53/149 与 :135 的三个默认值怎样决定帧预算;PagedLOD::requestStatus 的状态机在 :565 的 compare_exchange(Reading → Compiling) 失败后怎样把失败静默吞掉;DatabaseQueue 与 PagedLODContainer 怎样把可见性变成加载请求、只增不减的容器是不是与第十八章的 objectIDMap 同一种代价;ObjectCache / SharedObjects 的缓存键漏字段在「同一文件被多个 PagedLOD 引用」时是否重演第十七章批判结论三。

本章逐条回答,先纠正两处与 1.1.16 实测不符的措辞:预告里的 ObjectCache 不是本仓库的类型,DatabasePager 也不存在 ReadOperation、CompileOperation、update()、requiresUpdate()、signal()、cull()、startThread()、stopThread() 这组方法。本章沿用第十六章的「命名边界澄清」做法,不顺着预告措辞往下写。

先给可复核的规模。本章正面处理 33 个文件,合计 8,252 行,全部用 wc -l 实测,下表逐行列出完整路径、行数与本章角色:

文件行数本章角色
include/vsg/io/DatabasePager.h180CulledPagedLODs、PagedLODContainer、DatabaseQueue、DatabasePager 四个类的字段与公开接口全表
src/vsg/io/DatabasePager.cpp792容器侵入式链表、两个队列、读线程、删除线程、request、requestDiscarded、updateSceneGraph 全量实现
include/vsg/nodes/PagedLOD.h114children、filename、priority、requestStatus、八态枚举、pending、index
src/vsg/nodes/PagedLOD.cpp93拷贝构造、compare、read、write 四处字段不对称
include/vsg/nodes/LOD.h73非分页 LOD 的 Children、t_traverse 与「必须始终有合法子节点」契约
src/vsg/nodes/LOD.cpp87LOD::compare 的长度保护、read/write 的 children 计数
include/vsg/nodes/CullNode.h50单孩子视锥剔除节点、注释里明写「无内部检查」
include/vsg/app/RecordTraversal.h191frameStamp、databasePager、culledPagedLODs 三个成员与 setDatabasePager
src/vsg/app/RecordTraversal.cpp704apply(const LOD&)、apply(const PagedLOD&)、apply(const CullNode&) 三条遍历路径
include/vsg/app/CompileManager.h119CompileResult、ResourceScavenger、CompileManager 的接口与 compile 契约
src/vsg/app/CompileManager.cpp447CompileResult::add/reset/requiresViewerUpdate、ResourceScavenger::scavenge、compile
include/vsg/app/Viewer.h174updateOperations、animationManager、compileManager、status、_frameStamp 字段
src/vsg/app/Viewer.cpp892Viewer::compile 的分页装配、Viewer::update 的硬编码挂接、stopThreading
include/vsg/app/UpdateOperations.h66ONE_TIME/ALL_FRAMES、run(),用于证明 pager 不走这条路
include/vsg/threading/DeleteQueue.h136ObjectToDelete、retainForFrameCount=3、四个 add/prune 入口
src/vsg/threading/DeleteQueue.cpp121advance、wait_then_clear、clear 三条删除路径
include/vsg/threading/Latch.h95count_down() 的 <= 1 判据、wait()、release()
include/vsg/threading/ActivityStatus.h42set/active/cancel 三个原子位操作
include/vsg/threading/atomics.h52compare_exchange、exchange_if_greater 两个模板的实现
include/vsg/io/Options.h147sharedObjects、readerWriters、paths、extensionHint 等字段全集
src/vsg/io/Options.cpp191Options::compare 的九个字段、read/write 的插件表往返
src/vsg/io/read.cpp223vsg::read 单文件分派、sharedObjects 缓存路径、ReadOperation 与 Latch
include/vsg/io/ReaderWriter.h134ReadError 定义、ReaderWriter 六个虚函数的空默认实现
include/vsg/utils/SharedObjects.h213LoadedObject、SuitableForSharing、share(ref_ptr<T>&, Func) 模板
src/vsg/utils/SharedObjects.cpp241suitable、prune、LoadedObject::compare、apply(const PagedLOD&)
include/vsg/core/compare.h115compare_pointer 的深比较语义,决定缓存键是否按内容判定
include/vsg/io/tile.h80vsg::tile 是一个 ReaderWriter,不是扩展名
src/vsg/io/tile.cpp927.tile 虚拟文件名、read_root/read_subtile、生成 PagedLOD 并回填 options
include/vsg/nodes/TileDatabase.h126TileDatabaseSettings、TileDatabase、readDatabase
src/vsg/nodes/TileDatabase.cpp324readDatabase 把 tileReader 插到 readerWriters 头部、第二处 cast<ReadError>()
include/vsg/state/ResourceHints.h99numDatabasePagerReadThreads=4、containsPagedLOD、allocatedMemoryLimit
include/vsg/app/TransferTask.h124编译期传输任务的接口
src/vsg/app/TransferTask.cpp880分页子图编译后的数据上传落点

19.0.1 本章的问题清单

本章的问题清单收敛为五组:其一,七个零命中的方法名与两个不存在的类型名如何澄清,真实接口与 ObjectCache 的替代者是什么(19.1);其二,PagedLOD 的字段、八态状态机、read/write/compare 三方不对称,以及 LOD/CullNode 的遍历差异(19.2–19.3);其三,apply(const PagedLOD&) 怎样把可见性变成请求,帧号无符号减法、priority 除零、容器侵入式链表与 DatabaseQueue 的边界(19.4–19.7);其四,start() 的三条失败路径、requestDiscarded 的 pending 泄漏、updateSceneGraph 的帧号置 0 与回收/合并,以及 CompileResult::add 的 break 在批量合并下怎样放大(19.8–19.12);其五,编译链、Viewer 挂接、.vsgt/.vsgb/.tile 读链、DeleteQueue/Latch 与一条请求的全局账本(19.13–19.17)。每组都对应正文里至少一条可用 grep -n 复核的硬结论。

19.0.2 答案骨架

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

#结论主要证据性质
11.1.16 的 DatabasePager 公开接口只有 start、request、updateSceneGraph、assignInstrumentation 加一个受保护的 requestDiscarded;ReadOperation/CompileOperation/update/requiresUpdate/signal/cull/startThread/stopThread 在本类两个文件里合计 0 处命中,signal 唯一一次出现是 :404 的英文注释单词include/vsg/io/DatabasePager.h:130–176、src/vsg/io/DatabasePager.cpp:404命名边界 / 设计取舍
2仓库里没有 ObjectCache 类型:grep -rn "ObjectCache" include/ src/ 为 0,仅 cmake/cppcheck-suppression-list.txt:98 留着一条指向已删除头文件的抑制项;实际缓存是 SharedObjects + LoadedObjectsrc/vsg/io/read.cpp:76–115、include/vsg/utils/SharedObjects.h:86–100命名边界 / 硬缺陷(抑制项失效)
3CompileResult::add 的 break 在分页下被批量放大:_toMergeQueue 用 add(plod, cr) 累积多个结果,take_all 再整批 cr.add(_compileResult),任一空 binDetails 会截断其后所有 view,令 requiresViewerUpdate 漏判src/vsg/app/CompileManager.cpp:48–55、src/vsg/io/DatabasePager.cpp:389–395、:669、:481硬缺陷
4requestDiscarded 里 plod->pending = nullptr 的三行清理全部被注释,失败/异常/过期路径残留已加载子图,与 trim 分支的 plod->pending = {} 不对称src/vsg/io/DatabasePager.cpp:646–658、:740–741硬缺陷
5numActiveRequests 是无符号 atomic_uint,在 :642 自增,却在 :657、:667、:784 三处扣减,其中 :784 无条件减 nodes.size() 而 merge 循环只处理 CAS 成功者,计数可下溢到接近 2^32include/vsg/io/DatabasePager.h:143、src/vsg/io/DatabasePager.cpp:642/657/667/784硬缺陷
6updateSceneGraph 的 :746 无条件解引用 plod->options->sharedObjects,而 PagedLOD 拷贝构造不复制 options、默认构造也不初始化它,手写/clone 出来的节点在回收路径上空指针解引用src/vsg/io/DatabasePager.cpp:746–750、src/vsg/nodes/PagedLOD.cpp:22–31、include/vsg/nodes/PagedLOD.h:84硬缺陷
7Deleting = 7 全库零使用,DeleteRequest = 6 在 :733 被 CAS 设入后 :738 立刻 exchange(NoRequest) 清回,没有任何消费方;Merging 同样设入即清include/vsg/nodes/PagedLOD.h:95–105、src/vsg/io/DatabasePager.cpp:733/738/771/781硬缺陷(死状态)/ 设计取舍
8maxNumPagedLOD = 10000 只是 PagedLODContainer 构造的默认参数,实际 DatabasePager 用 create(4000);帧预算用的 targetMaxNumPagedLODWithHighResSubgraphs = 1500 是另一套量纲,容器上限与预算上限互不相干include/vsg/io/DatabasePager.h:53/149、src/vsg/io/DatabasePager.cpp:500/721设计取舍 / 静默降级
9apply(const PagedLOD&) 的 priority = sphere.r / cutoff 在 minimumScreenHeightRatio = 0.0(头文件默认值,注释写「0.0 is always visible」)时除零得 +inf,exchange_if_greater 把 priority 永久钉在无穷大src/vsg/app/RecordTraversal.cpp:223–224、include/vsg/nodes/PagedLOD.h:43硬缺陷
10frameCount、frameHighResLastUsed 全是 uint64_t,updateSceneGraph 在 frameStamp 为空时把 frameCount 置 0,此后六处「当前帧减上次使用帧」全部无符号下溢,把所有 PagedLOD 判成过期src/vsg/io/DatabasePager.cpp:664、include/vsg/nodes/PagedLOD.h:57、src/vsg/app/RecordTraversal.cpp:191/210/240硬缺陷

十条里第 3、4、5、6、7、9、10 条是硬缺陷,第 1、2 条是命名边界澄清,第 8 条是设计取舍。正文再补 vsg::read 插件独占、SuitableForSharing::apply(const PagedLOD&) 让缓存整体失效、LoadedObject::compare 缓存键漏字段、DeleteQueue::advance 空指针、wait_then_clear 跳过 prune、SharedObjects::share 锁外 init、PagedLOD::read/write 字段不对称、start() 未判 compileManager 等十三条,均给出路径、行号、触发条件、后果与规避。

19.0.3 阅读路线

命名边界 → PagedLOD 字段与状态机 → LOD/CullNode 的距离判定 → RecordTraversal::apply(const PagedLOD&) → CulledPagedLODs 与三条侵入式链表 → 五个帧预算数字 → DatabaseQueue → DatabasePager 构造与四个装配点 → start() 的两个线程 → request/requestDiscarded → updateSceneGraph → CompileResult::add 的放大 → CompileManager/ResourceScavenger/TransferTask → Viewer 挂接 → .vsgt/.vsgb/.tile 读链 → DeleteQueue/Latch → 一条请求的全局账本。


19.1 命名边界澄清:本章真正存在的类型与方法

接手第十八章预告前,必须先把两组名字钉死。第一组是七个方法名与两个类名,第二组是三种文件名。第十七章 17.1.3 已经用 find 与 grep 证明了 vsgXchange 与 ObjectCache 都不在本仓库,本章把同样的证据方法用在 DatabasePager 身上。

// include/vsg/io/DatabasePager.h:127-177
    class VSG_DECLSPEC DatabasePager : public Inherit<Object, DatabasePager>
    {
    public:
        DatabasePager();
        DatabasePager(const DatabasePager&) = delete;
        DatabasePager& operator=(const DatabasePager& rhs) = delete;
        virtual void start(uint32_t numReadThreads = 4);
        virtual void request(ref_ptr<PagedLOD> plod);
        virtual void updateSceneGraph(ref_ptr<FrameStamp> frameStamp, CompileResult& cr);
        ref_ptr<CompileManager> compileManager;
        std::atomic_uint numActiveRequests{0};
        std::atomic_uint64_t frameCount{0};
        ref_ptr<CulledPagedLODs> culledPagedLODs;
        uint32_t targetMaxNumPagedLODWithHighResSubgraphs = 1500;
        uint64_t delayBeforeNextLoadAttempt = 60;
        std::mutex pendingPagedLODMutex;
        ref_ptr<PagedLODContainer> pagedLODContainer;
        ref_ptr<Instrumentation> instrumentation;
        void assignInstrumentation(ref_ptr<Instrumentation> in_instrumentation);
        std::list<std::thread> threads;
        ref_ptr<ActivityStatus> status;
        ref_ptr<DeleteQueue> deleteQueue;
    protected:
        ~DatabasePager() override;
        void requestDiscarded(PagedLOD* plod);
        ref_ptr<DatabaseQueue> _requestQueue;
        ref_ptr<DatabaseQueue> _toMergeQueue;
    };

19.1.1 真实接口逐项对齐

start(uint32_t numReadThreads = 4)(:135)创建读线程与删除线程;request(ref_ptr<PagedLOD>)(:137)把节点放进 _requestQueue;updateSceneGraph(FrameStamp, CompileResult&)(:139)是主线程每帧调用一次的唯一入口;assignInstrumentation(:162)只赋值一个字段;requestDiscarded(:173)是受保护的失败回收函数。四个数据成员 compileManager、numActiveRequests、frameCount、culledPagedLODs 与四个对象成员 pagedLODContainer、instrumentation、status、deleteQueue 全部公开,没有 getter,调用方直接读写,这与第九章 GraphicsPipeline 的 vk(viewID) 封装风格相反,是分页子系统刻意选的「结构体式」暴露。

_requestQueue 与 _toMergeQueue 是仅有的两个受保护队列(:175–176)。前者装「等待读盘」的 PagedLOD,后者装「已编译、等待挂到场景图」的 PagedLOD。两个队列是同一个 DatabaseQueue 类的实例,靠 add 的两个重载区分用途,这是理解 19.7 的前提。

19.1.2 七个零命中的方法名

对 include/vsg/io/DatabasePager.h 与 src/vsg/io/DatabasePager.cpp 两个文件逐词统计:ReadOperation 0 处、CompileOperation 0 处、requiresUpdate 0 处、void cull 0 处、startThread 0 处、stopThread 0 处、void update( 0 处;signal 1 处,落在 src/vsg/io/DatabasePager.cpp:404 的注释 // wait until the conditional variable signals that an operation has been added,不是方法。ReadOperation 这个名字在本仓库确实存在,但它是 src/vsg/io/read.cpp:139–157 里 vsg::read(const Paths&, ...) 的局部 struct,与 DatabasePager 无关,第十九章 19.16.4 会单独拆它。

停线程也没有独立方法:~DatabasePager()(:503–513)做 status->set(false) 再 join() 全部线程,Viewer::stopThreading()(src/vsg/app/Viewer.cpp:772–791)负责把所有引用清空让析构发生。换言之「开始」有 start(),「停止」靠「析构 + 引用归零」,这不是遗漏,是把生命周期绑在 ref_ptr 上的设计取舍,代价是 status 一旦被 set(false) 就无法再 start()——ActivityStatus::set(include/vsg/threading/ActivityStatus.h:27)是 exchange,但 DatabasePager 没有任何一处把它写回 true。

19.1.3 ObjectCache、SharedObjects、LoadedObject 三者归一

grep -rn "ObjectCache" include/ src/ 返回 0 行,find . -iname "*ObjectCache*" 返回空。全仓库 8 处 ObjectCache 字样里,7 处在 docs/series/ 的前几章文档(含第十八章预告那一处),1 处在 cmake/cppcheck-suppression-list.txt:98:

unusedStructMember:*/include/vsg/io/ObjectCache.h

这条静态检查抑制项指向一个不存在的头文件,属于删除类型后没清理构建配置的残留,是第 2 条硬结论的实证。第十八章预告把「缓存键漏字段」归给 ObjectCache,本章 19.15.3 会把它归回 LoadedObject::compare(src/vsg/utils/SharedObjects.cpp:218–227),结论不变,证据路径全部替换成实测存在的文件。

19.1.4 vsgXchange 与 .tile 的边界

vsgXchange 是 README.md:21 列出的独立仓库,本仓库 include/ src/ 里只有 include/vsg/state/ViewDependentState.h:104 一条注释提到它,没有任何实现。.tile 也不是 vsg::read 认识的扩展名:src/vsg/io/read.cpp:42–73 的内置分派只列 .vsga/.vsgt/.vsgb/.spv/.json/GLSL/txt。这条链是 19.15.6 的主线。


19.2 PagedLOD 节点:两个孩子、六个原子量与八态状态机

PagedLOD 是分页子系统里唯一横跨「场景图」「线程」「序列化」三层的节点。它既是 Node 子类,又带六个 mutable std::atomic 字段,又自己实现 read/write;类注释里的 PagedLODChild 指的就是它的两个定长孩子。先看字段全表。

// include/vsg/nodes/PagedLOD.h:35-111
    class VSG_DECLSPEC PagedLOD : public Inherit<Node, PagedLOD>
    {
    public:
        PagedLOD();
        PagedLOD(const PagedLOD& rhs, const CopyOp& copyop = {});
        struct Child
        {
            double minimumScreenHeightRatio = 0.0; // 0.0 is always visible
            ref_ptr<Node> node;
        };
        // external file to load when child 0 is null.
        Path filename;
        dsphere bound;
        using Children = std::array<Child, 2>;
        Children children;
        bool highResActive(uint64_t frameCount, uint64_t inactiveAge = 3) const
        {
            return (frameCount - frameHighResLastUsed.load()) <= inactiveAge;
        }
    public:
        ref_ptr<Object> clone(const CopyOp& copyop = {}) const override { return PagedLOD::create(*this, copyop); }
        int compare(const Object& rhs) const override;
        // t_traverse / traverse overrides omitted
        void read(Input& input) override;
        void write(Output& output) const override;
    protected:
        ~PagedLOD() override;
    public:
        ref_ptr<Options> options;
        mutable std::atomic<double> priority{0.0};
        mutable std::atomic_uint64_t frameHighResLastUsed{0};
        mutable std::atomic_uint requestCount{0};
        mutable std::atomic_uint64_t frameNextLoadAttempt{0};
        mutable std::atomic_uint64_t loadAttempts{0};
        enum RequestStatus : unsigned int
        {
            NoRequest = 0, ReadRequest = 1, Reading = 2, Compiling = 3,
            MergeRequest = 4, Merging = 5, DeleteRequest = 6, Deleting = 7
        };
        mutable std::atomic<RequestStatus> requestStatus{NoRequest};
        mutable uint32_t index = 0;
        ref_ptr<Node> pending;
    };

19.2.1 children[0] 与 children[1] 的固定分工

Children 是 std::array<Child, 2>(:52),定长两个,不是 LOD 的 std::vector。类注释(:28–34)写明「孩子按分辨率从高到低排列,一旦某个孩子通过可见高度测试就不再检查后续孩子,因此一次记录遍历最多遍历一个孩子」。这个「最多一个」的约定由 RecordTraversal::apply(const PagedLOD&) 落实:children[0].node 存在且可见时 :218 遍历后 return,否则继续检查 children[1](:248–259)。

Child::minimumScreenHeightRatio 默认 0.0(:43),注释写「0.0 is always visible」。这个默认值是整个分页生成器的常用值:src/vsg/io/tile.cpp:212 把低精孩子写成 PagedLOD::Child{0.0, tile_node},:211 把高精孩子写成 {0.25, {}},:386–387 的子 tile 用 settings->lodTransitionScreenHeightRatio(TileDatabase.h:39 默认 0.25)与 0.0 配对。于是「0.0 恒可见」不是理论边界,而是每棵 tile 树里低精孩子的实际取值,19.3.4 的除零结论正是由此触发。

// src/vsg/io/tile.cpp:211-212
                plod->children[0] = vsg::PagedLOD::Child{0.25, {}};
                plod->children[1] = vsg::PagedLOD::Child{0.0, tile_node};

tile_node 对应的 minimumScreenHeightRatio 被写成 0.0,除零结论因此不是理论边界。

children[0].node 为空是「高精子图尚未加载」的标记,filename(:48)注释直接写「external file to load when child 0 is null」。加载完成后 DatabasePager.cpp:778 把 plod->pending 赋给 plod->children[0].node;回收时 :736 把它重新置空。三者构成「:65 读时置空 → :778 合并填入 → :736 回收置空」的闭环,缺口在于 pending 自身在合并后从未清空(19.11.6)。

19.2.2 filename、bound、options 三个非原子字段

filename 是 vsg::Path,bound 是 dsphere,options 是 ref_ptr<Options>(:84)。前两个参与 compare(src/vsg/nodes/PagedLOD.cpp:44、:54),options 不参与。这是设计取舍,不是显式保证。

options 还有一个更直接的坑:默认构造 PagedLOD::PagedLOD()(PagedLOD.cpp:18–20)函数体为空,拷贝构造(:22–31)只复制 filename、bound、两个 minimumScreenHeightRatio 与两个 node,不复制 options,六个原子量与 requestStatus、index、pending 也全部用类内默认初始化重建。只有 read(:79)会 options = Options::create_if(input.options, *input.options) 创建它。19.11.4 的空指针缺陷就落在这个差异上。

19.2.3 六个原子量与一个非原子 index

priority(std::atomic<double>)、frameHighResLastUsed、requestCount、frameNextLoadAttempt、loadAttempts、requestStatus(std::atomic<RequestStatus>)全部是 mutable,因为 apply(const PagedLOD&)(src/vsg/app/RecordTraversal.cpp:180)先用 getCommandBuffer 做 COLOR_PAGER 插桩后,收到的是 const 引用却要写 frameHighResLastUsed.exchange(...)(:209)、priority(:224)、requestCount.fetch_add(1)(:226)。mutable + atomic 是这里能让「const 遍历」与「写状态」共存的唯一办法。

值得单独点出 index(PagedLOD.h:108):它是 mutable uint32_t,不是原子。这套「靠时序而非锁」的并发模型在 19.5.1 展开。

// include/vsg/nodes/PagedLOD.h:107-108
        mutable std::atomic<RequestStatus> requestStatus{NoRequest};
        mutable uint32_t index = 0;

requestStatus 是原子而紧邻的 index 不是,这一对字段的同步口径不同。

highResActive(frameCount, inactiveAge = 3)(:55–58)是判定「高精子图最近三帧是否被用过」的内联函数,返回 (frameCount - frameHighResLastUsed.load()) <= inactiveAge。两个操作数都是 uint64_t,减法无符号,这是第 10 条硬结论在头文件里的源头。

// include/vsg/nodes/PagedLOD.h:55-55
        bool highResActive(uint64_t frameCount, uint64_t inactiveAge = 3) const
        {

frameCount 与 inactiveAge 的无符号减法从第 55 行开始。

19.2.4 八态枚举与两个死状态

RequestStatus(:95–105)八个值从 NoRequest = 0 到 Deleting = 7。把 src/vsg/io/DatabasePager.cpp 与 src/vsg/app/RecordTraversal.cpp 里所有状态迁移列出来,实际发生的只有六条:

  • :638 NoRequest → ReadRequest(request())
  • :542 ReadRequest → Reading(读线程 compare_exchange)
  • :565 Reading → Compiling(读线程 compare_exchange)
  • :577 → MergeRequest(exchange,编译成功)
  • :733 NoRequest → DeleteRequest(trim 的 CAS)
  • :771 MergeRequest → Merging(merge 的 CAS)

Compiling 只在 :565 作为 CAS 的目标出现一次,之后 :577 无条件 exchange(MergeRequest) 越过它,没有任何代码在 Compiling 状态下做事。Merging 在 :771 设入,:781 立刻 exchange(NoRequest) 清回。状态机不是错,但它比枚举声明表达的简单得多:真正持久的状态只有 NoRequest、ReadRequest、Reading、MergeRequest 四个。

19.2.5 compare / read / write 的三方不对称

compare 先比 bound、再逐个比 Child、最后比 filename,与 read/write 的字段集并不重合。

// include/vsg/nodes/PagedLOD.h:43-44
            double minimumScreenHeightRatio = 0.0; // 0.0 is always visible
            ref_ptr<Node> node;

minimumScreenHeightRatio 默认为 0.0,Child 的 node 默认空,两者都由 compare 逐字段比。

// src/vsg/nodes/PagedLOD.cpp:37-93  compare 先比 bound 后比 filename
int PagedLOD::compare(const Object& rhs_object) const
{
    int result = Object::compare(rhs_object);
    if (result != 0) return result;
    auto& rhs = static_cast<decltype(*this)>(rhs_object);
    if ((result = compare_value(bound, rhs.bound)) != 0) return result;
    auto rhs_itr = rhs.children.begin();
    for (auto lhs_itr = children.begin(); lhs_itr != children.end(); ++lhs_itr, ++rhs_itr)
    {
        if ((result = compare_value(lhs_itr->minimumScreenHeightRatio, rhs_itr->minimumScreenHeightRatio)) != 0) return result;
        if ((result = compare_pointer(lhs_itr->node, rhs_itr->node)) != 0) return result;
    }
    return compare_value(filename, rhs.filename);
}

// src/vsg/nodes/PagedLOD.cpp:57-93  read 逐字读 bound
void PagedLOD::read(Input& input)
{
    Node::read(input);
    input.read("bound", bound);
    input.read("child.minimumScreenHeightRatio", children[0].minimumScreenHeightRatio);
    input.read("child.filename", filename);
    children[0].node = nullptr;
    if (input.filename)
    {
        auto path = filePath(input.filename);
        if (path)
        {
            filename = (path / filename).lexically_normal();
        }
    }
    input.read("child.minimumScreenHeightRatio", children[1].minimumScreenHeightRatio);
    input.read("child.node", children[1].node);
    options = Options::create_if(input.options, *input.options);
}

// src/vsg/nodes/PagedLOD.cpp:82-93  write 写 bound
void PagedLOD::write(Output& output) const
{
    Node::write(output);
    output.write("bound", bound);
    output.write("child.minimumScreenHeightRatio", children[0].minimumScreenHeightRatio);
    output.write("child.filename", filename);
    output.write("child.minimumScreenHeightRatio", children[1].minimumScreenHeightRatio);
    output.write("child.node", children[1].node);
}

compare 比 bound、两个 Child、最后 filename,共四组(:44、:50–51、:54);write 写 bound、两个 minimumScreenHeightRatio、filename、children[1].node(:86–92);read 读 bound、两个 minimumScreenHeightRatio、filename、children[1].node,外加三件 write 没有的事:children[0].node = nullptr(:65)、把 input.filename 所在目录拼到 filename 前面(:67–74)、用 Options::create_if 造 options(:79)。

于是 read/write/compare 三方两两不对齐:compare 不比 options,write 不写 options 也不写 children[0].node,read 强制把 children[0].node 置空并改写 filename。这不是疏忽而是有意的序列化契约——高精子图是运行期加载的,永远不进文件;filename 必须是相对主文件的路径,反序列化时按 filePath(input.filename) 还原成绝对/相对路径(第十八章 18.x 的 Input::filename 机制)。代价有两条:其一,compare 把两个 options 不同、filename 相同的 PagedLOD 判为相等,第十八章预告第六问的「同一文件多个 options」在这里已经埋下第一层;其二,filename 的目录拼接只在 read 发生,tile.cpp:213 生成的 "x y 0.tile" 这类虚拟文件名不经过 read,所以不会被拼路径,直接交给 vsg::tile ReaderWriter,这是两种分页文件格式的又一条分界。

19.3 LOD 与 PagedLOD:同一个 lodDistance,两套切换语义

LOD/PagedLOD/CullNode 同属「判断后 traverse」一族,在记录遍历里共用 state->lodDistance(sphere) 与 state->intersect(bound),但只有 PagedLOD 把判定写回原子状态并触发跨线程请求。

// include/vsg/nodes/LOD.h:38-63
        struct Child
        {
            double minimumScreenHeightRatio = 0.0; // 0.0 is always visible
            ref_ptr<Node> node;
        };
        using Children = std::vector<Child, allocator_affinity_nodes<Child>>;
        dsphere bound;
        Children children;
        void addChild(const Child& lodChild) { children.push_back(lodChild); }
        template<class N, class V>
        static void t_traverse(N& node, V& visitor)
        {
            for (auto& child : node.children) child.node->accept(visitor);
        }
        void traverse(Visitor& visitor) override { t_traverse(*this, visitor); }
        void traverse(ConstVisitor& visitor) const override { t_traverse(*this, visitor); }
        void traverse(RecordTraversal& visitor) const override { t_traverse(*this, visitor); }
// src/vsg/app/RecordTraversal.cpp:153-178
void RecordTraversal::apply(const LOD& lod)
{
    GPU_INSTRUMENTATION_L2_NCO(instrumentation, *getCommandBuffer(), "LOD", COLOR_RECORD_L2, &lod);
    const auto& sphere = lod.bound;
    // check if lod bounding sphere is in view frustum.
    auto lodDistance = state->lodDistance(sphere);
    if (lodDistance < 0.0)
    {
        return;
    }
    if (viewDependentState) lodDistance *= viewDependentState->LODScale;
    for (auto& child : lod.children)
    {
        auto cutoff = lodDistance * child.minimumScreenHeightRatio;
        bool child_visible = sphere.r > cutoff;
        if (child_visible)
        {
            child.node->accept(*this);
            return;
        }
    }
}

19.3.1 LOD 的 apply 与 t_traverse 各自的无判空

LOD::t_traverse(LOD.h:56–59)遍历 Child 时是 for (auto& child : node.children) child.node->accept(visitor);,没有 if (child.node);apply(const LOD&) 的 :174 同样是 child.node->accept(*this)。两处都假定孩子非空。对照 PagedLOD::t_traverse(PagedLOD.h:64–71)的 if (child.node),同一个库里两种节点对「空孩子」的容忍度不一致;该文件 :57 的 highResActive 用 frameCount 与 inactiveAge 判高精,却从不判孩子为空。

19.3.2 PagedLOD 的 distance 与 LOD 的差别

apply(const PagedLOD&) 的 :188–199 与 apply(const LOD&) 的 :160–166 逐字相同:取 bound、lodDistance、判 < 0.0、乘 LODScale。差别从 :201 开始:PagedLOD 只检查 children[0] 与 children[1] 两个定长孩子,而 LOD 遍历整个 vector;PagedLOD 在判定过程中写 frameHighResLastUsed.exchange(frameCount)(:209)、priority(:224)、requestCount.fetch_add(1)(:226),LOD 一个原子量都不写;PagedLOD 的视锥外分支(:189–197)会把节点登记进 culledPagedLODs->highresCulled,LOD 直接 return。

19.3.3 CullNode / CullGroup 的视锥路径

// include/vsg/nodes/CullNode.h:21-47
    /// CullNode that enables view frustum culling on a single child node.
    /// A valid node must always be assigned to a CullNode before it's used,
    /// for performance reasons there are no internal checks made when accessing the child.
    class VSG_DECLSPEC CullNode : public Inherit<Node, CullNode>
    {
    public:
        CullNode();
        CullNode(const CullNode& rhs, const CopyOp& copyop = {});
        CullNode(const dsphere& in_bound, Node* in_child);
        dsphere bound;
        ref_ptr<vsg::Node> child;
        void traverse(Visitor& visitor) override { child->accept(visitor); }
        void traverse(ConstVisitor& visitor) const override { child->accept(visitor); }
        void traverse(RecordTraversal& visitor) const override { child->accept(visitor); }
        void read(Input& input) override;
        void write(Output& output) const override;
    };
// src/vsg/app/RecordTraversal.cpp:269-289
void RecordTraversal::apply(const CullGroup& cullGroup)
{
    GPU_INSTRUMENTATION_L2_NCO(instrumentation, *getCommandBuffer(), "CullGroup", COLOR_RECORD_L2, &cullGroup);
    if (state->intersect(cullGroup.bound))
    {
        // debug("Passed node");
        cullGroup.traverse(*this);
    }
}

void RecordTraversal::apply(const CullNode& cullNode)
{
    GPU_INSTRUMENTATION_L2_NCO(instrumentation, *getCommandBuffer(), "CullNode", COLOR_RECORD_L2, &cullNode);
    if (state->intersect(cullNode.bound))
    {
        //debug("Passed node");
        cullNode.traverse(*this);
    }
}

CullNode.h:22–23 把契约写得很直白:「必须始终赋予合法孩子,出于性能原因访问孩子时不做内部检查」。三个 traverse(:38–40)都是 child->accept(visitor),无判空。PagedLOD.h:34 的注释特意声明「记录遍历里也检查 bound 的视锥,因此不需要额外的 CullNode/CullGroup 装饰」,这句承诺由 apply(const PagedLOD&) 的 :189 落实。

19.3.4 除零、+inf 与优先级的钉死

PagedLOD::Child::minimumScreenHeightRatio 默认 0.0(PagedLOD.h:43),tile.cpp:212、:387 给低精孩子的实际值也是 0.0。在 apply(const PagedLOD&) 里,高精孩子若尚未加载且可见,会走到 src/vsg/app/RecordTraversal.cpp:223:

// src/vsg/app/RecordTraversal.cpp:221-231
            else if (databasePager)
            {
                auto priority = sphere.r / cutoff;
                exchange_if_greater(plod.priority, priority);
                auto previousRequestCount = plod.requestCount.fetch_add(1);
                if (previousRequestCount == 0)
                {
                    // we are the first request so tell the databasePager about it
                    databasePager->request(ref_ptr<PagedLOD>(const_cast<PagedLOD*>(&plod)));
                }
                else
                {
                    //debug("repeat request ",&plod,", ",plod.filename,", ",plod.requestStatus.load());
                }
            }

cutoff = lodDistance * child.minimumScreenHeightRatio(:205)。这个 PagedLOD 在 DatabaseQueue::take_when_available(src/vsg/io/DatabasePager.cpp:441–444)的优先级扫描里永远排在前面,且所有 0.0 ratio 的节点彼此都是 +inf,比较退化为队列里的物理次序。

// src/vsg/io/DatabasePager.cpp:441-441
    for (; itr != _queue.end(); ++itr)
    {

priority 相等时不换 highest_itr。

触发条件要说准:只有 children[0].minimumScreenHeightRatio == 0.0 且 children[0].node 为空时才会走到 :223。这是第 9 条硬结论的完整推导。

// src/vsg/app/RecordTraversal.cpp:207-207
        if (child_visible)
        {

frameHighResLastUsed.exchange 的返回值参与无符号减法。


19.4 RecordTraversal::apply(const PagedLOD&) 六条分支逐行推导

这是把「相机看见什么」翻译成「后台该读什么」的唯一函数,也是 culledPagedLODs 两个 vector 的唯一生产者。

// src/vsg/app/RecordTraversal.cpp:180-260
void RecordTraversal::apply(const PagedLOD& plod)
{
    GPU_INSTRUMENTATION_L2_NCO(instrumentation, *getCommandBuffer(), "PagedLOD", COLOR_PAGER, &plod);
    const auto& sphere = plod.bound;
    auto frameCount = frameStamp->frameCount;
    // check if lod bounding sphere is in view frustum.
    auto lodDistance = state->lodDistance(sphere);
    if (lodDistance < 0.0)
    {
        if ((frameCount - plod.frameHighResLastUsed) > 1 && culledPagedLODs)
        {
            culledPagedLODs->highresCulled.emplace_back(&plod);
        }
        return;
    }
    if (viewDependentState) lodDistance *= viewDependentState->LODScale;
    // check the high res child to see if it's visible
    {
        const auto& child = plod.children[0];
        auto cutoff = lodDistance * child.minimumScreenHeightRatio;
        bool child_visible = sphere.r > cutoff;
        if (child_visible)
        {
            auto previousHighResUsed = plod.frameHighResLastUsed.exchange(frameCount);
            if (culledPagedLODs && ((frameCount - previousHighResUsed) > 1))
            {
                culledPagedLODs->newHighresRequired.emplace_back(&plod);
            }
            if (child.node)
            {
                // high res visible and available so traverse it
                child.node->accept(*this);
                return;
            }
            else if (databasePager)
            {
                auto priority = sphere.r / cutoff;
                exchange_if_greater(plod.priority, priority);
                auto previousRequestCount = plod.requestCount.fetch_add(1);
                if (previousRequestCount == 0)
                {
                    databasePager->request(ref_ptr<PagedLOD>(const_cast<PagedLOD*>(&plod)));
                }
            }
        }
        else
        {
            if (culledPagedLODs && ((frameCount - plod.frameHighResLastUsed) <= 1))
            {
                culledPagedLODs->highresCulled.emplace_back(&plod);
            }
        }
    }
    // low res child: cutoff / child_visible / accept 省略
}

19.4.1 frameStamp 与视锥外的第一条分支

:185 的 auto frameCount = frameStamp->frameCount; 直接解引用 frameStamp,而 frameStamp 是 RecordTraversal.h:176 的 ref_ptr<FrameStamp>,由 RecordTraversal::setFrameStamp(src/vsg/app/RecordTraversal.cpp:98–101)在记录前设置。正常帧路径第七/十四章已保证它非空,但函数自身零防御;任何在 setFrameStamp 之前调用 apply(const PagedLOD&) 的 Visitor 都会空指针解引用。databasePager 与 culledPagedLODs 则由 setDatabasePager 注入,三者对同一参数态度不同。

// src/vsg/app/RecordTraversal.cpp:98-98
void RecordTraversal::setFrameStamp(FrameStamp* fs)
{

setFrameStamp 直接赋裸指针,不判空。

:189 判 lodDistance < 0.0(视锥外)。culledPagedLODs 由 setDatabasePager(RecordTraversal.cpp:103–109)在 :108 赋值 dp ? dp->culledPagedLODs.get() : nullptr,所以「有 pager」与「有 culledPagedLODs」是同一条件的两种写法。

19.4.2 高精可见分支的三件事

高精孩子可见(:207 的 sphere.r > cutoff)后连续做三件事。第三件 :215–236 分高精已加载与未加载两条路。

19.4.3 请求发起、const_cast 与除零

高精未加载(:215 的 child.node 为空)且有 databasePager(:221)时,:223–230 做四步:算 priority、用 exchange_if_greater 更新、requestCount.fetch_add(1)、若旧值为 0 则 request()。requestCount 的作用是「同一帧或同一批遍历里只发一次请求」:多个 CommandGraph、多个 View 可能在同一帧多次访问同一个 PagedLOD,:227 的 previousRequestCount == 0 保证只有第一次真正调用 DatabasePager::request。请求被消费后,requestDiscarded(:650)、prune(:464)、trim(:737)三处都会 requestCount.exchange(0) 复位,下一轮遍历才能再发。

// src/vsg/app/RecordTraversal.cpp:226-226
                auto previousRequestCount = plod.requestCount.fetch_add(1);
                if (previousRequestCount == 0)

旧值为 0 才触发 request。

ref_ptr<PagedLOD>(const_cast<PagedLOD*>(&plod))(:230)值得单独标注:apply 的形参是 const PagedLOD&,这里却 const_cast 去掉 const 后构造一个 ref_ptr<PagedLOD>,会调用 ref() 增加引用计数,并把这个裸指针交给跨线程的 _requestQueue(DatabasePager.cpp:641)。它之所以没立刻出错,是因为场景图本身持有该节点的强引用,ref_ptr 的增减不改变所有权;但 const_cast 绕过了「遍历期不得修改节点」的 const 契约,而 PagedLOD 的六个状态字段恰好都靠 mutable 合法写入——真正需要跨线程写的字段本就不需要 const_cast,这里去掉 const 只为满足 ref_ptr<PagedLOD> 的模板参数类型。这是接口类型设计留下的别扭处:若把 request 的形参改成 ref_ptr<const PagedLOD> 或 const PagedLOD*,这行 cast 可以消失。

19.4.4 低精分支的空指针与「最多一个孩子」

高精不可见(:238–244)时,若 (frameCount - plod.frameHighResLastUsed) <= 1 把节点塞进 highresCulled。低精分支有 if (child.node) 判空,与 :215 的高精判空一致,却与 LOD::apply 的 :174、CullNode::traverse 的 child->accept 不一致——同一个函数里对两个孩子的判空做对了,对普通 LOD 与 CullNode 就没做,这是 19.3.1 结论在遍历层的镜像。

19.4.5 六处无符号帧号减法的下溢链

把全库 frameCount - frameHighResLastUsed 形态的表达式列全:PagedLOD.h:57(highResActive)、DatabasePager.cpp:540(frameDelta)、:773(debug 打印)、RecordTraversal.cpp:191(视锥外)、:210(newHighresRequired)、:240(highresCulled)。六处全部是 uint64_t 减法,全部假定 frameCount >= frameHighResLastUsed。这个假定在两条路径上会被打破:

其一,DatabasePager.cpp:664 的 frameCount.exchange(frameStamp ? frameStamp->frameCount : 0) 在 frameStamp 为空时把分页器的 frameCount 置 0,而 PagedLOD::frameHighResLastUsed 是节点自己的原子量,不会跟着归零。下一帧 RecordTraversal 用 Viewer 的真实 frameStamp->frameCount(比如 5000)去减节点里可能仍为 5000 的 frameHighResLastUsed 尚可,但若分页器的 frameCount 与 Viewer 的 frameCount 因任何原因不同步,DatabasePager.cpp:540 的 frameDelta 就会下溢成 2^64 - k,:542 的 frameDelta > 1 恒真,读线程把每一个请求都判为过期、直接 requestDiscarded(:545),分页彻底停摆。

其二,Viewer.cpp:181 的 _frameStamp = FrameStamp::create(time, 0, simulationTime) 在重定时把帧号从 0 重新起算(第十四章 14.2 的 _firstFrame 分叉),而场景图里的 PagedLOD 对象可能复用了上一段计时的 frameHighResLastUsed 值。这是第 10 条硬结论,也是本章把「帧号」当作分布式状态而非单调时钟的代价讲透的地方。


19.5 CulledPagedLODs 与 PagedLODContainer:可见性到活跃集合的索引结构

updateSceneGraph 不直接遍历场景图,它读两个由记录遍历填好的 vector,再在一个「只增不减」的元素数组上搬动三条侵入式链表。这套结构是全章最容易被误读成缓存的部分。

// include/vsg/io/DatabasePager.h:31-90
    /// Class used by the DatabasePager to keep track of PagedLOD nodes
    class CulledPagedLODs : public Inherit<Object, CulledPagedLODs>
    {
    public:
        CulledPagedLODs()
        {
            highresCulled.reserve(512);
            newHighresRequired.reserve(8);
        }
        void clear()
        {
            highresCulled.clear();
            newHighresRequired.clear();
        }
        std::vector<const PagedLOD*> highresCulled;
        std::vector<const PagedLOD*> newHighresRequired;
    };

    struct PagedLODContainer : public Inherit<Object, PagedLODContainer>
    {
        explicit PagedLODContainer(uint32_t maxNumPagedLOD = 10000);
        struct List
        {
            uint32_t head = 0;
            uint32_t tail = 0;
            uint32_t count = 0;
            std::string name;
        };
        struct Element
        {
            uint32_t previous = 0;
            uint32_t next = 0;
            ref_ptr<PagedLOD> plod;
            List* list = nullptr;
        };
        using Elements = std::vector<Element>;
        Elements elements;
        List availableList;
        List inactiveList;
        List activeList;
        void resize(uint32_t new_size);
        void resize();
        void inactive(const PagedLOD* plod);
        void active(const PagedLOD* plod);
        void remove(PagedLOD* plod);
        void _move(const PagedLOD* plod, List* targetList);
        bool check();
        bool check(const List& list);
        void print(std::ostream& out);
    };

19.5.1 两个 vector 的生产-消费时序

highresCulled.reserve(512)、newHighresRequired.reserve(8)(:37–38)构造时一次性预留,clear()(:41–45)只清空不 shrink_to_fit()。与第十八章 objectIDMap 的「只增不减」同属容量代价,但这里是每帧复用的暂存区,上限由单帧可见节点数决定,属于可控预分配。

生产者是记录遍历线程(RecordTraversal.cpp:193、:212、:242),消费者是主线程 updateSceneGraph(DatabasePager.cpp:679、:702、:714)。若应用把 update() 与记录阶段并行化(第十四章的两种线程模型之一),两个 vector 就是裸数据竞争。

19.5.2 三条 List 与 Element 的侵入式索引

PagedLODContainer::elements(:73)是 std::vector<Element>,Element(:63–69)里 previous/next 是 uint32_t 下标而非指针,list 指回所属 List,plod 是强引用。三条 List(:74–76)是 availableList、inactiveList、activeList,各自只有 head/tail/count/name。下标 0 被保留为「空」哨兵——构造函数 elements(1)(src/vsg/io/DatabasePager.cpp:31)先放一个空元素,resize(new_size + 1)(:44)始终把第 0 号留作 null entry,PagedLOD::index(PagedLOD.h:108)默认 0 表示「尚未分配」。

「一个 PagedLOD 是否在活跃集合里」靠 plod->index 非 0 且 elements[plod->index].list == &activeList(updateSceneGraph:681)判定。下标代替指针换来缓存友好;elements 搬家无碍,因为 Element::list 指向作为 PagedLODContainer 成员、地址稳定的 List。

Element::plod 是 ref_ptr<PagedLOD>,意味着「被容器登记」本身构成一个强引用。这解释了一个反直觉现象:trim 分支 DatabasePager.cpp:743 把 plod 本身 push_back 进 deleteList 交给 DeleteQueue,但节点并不会因此被销毁——场景图父节点仍持有它,elements 归还 availableList 时 remove()(:265–270)才把 element.plod = nullptr 释放容器的那份引用。

19.5.3 resize 的边界与 availableList 初始化

// src/vsg/io/DatabasePager.cpp:30-88
PagedLODContainer::PagedLODContainer(uint32_t maxNumPagedLOD) :
    elements(1)
{
    availableList.name = "availableList";
    activeList.name = "activeList";
    inactiveList.name = "inactiveList";
    resize(std::max(maxNumPagedLOD, 10u));
}

// src/vsg/io/DatabasePager.cpp:40-88
void PagedLODContainer::resize(uint32_t new_size)
{
    // note first entry in elements is the null entry, so have to add/take away 1 when accounting for it.
    uint32_t original_size = static_cast<uint32_t>(elements.size()) - 1;
    elements.resize(new_size + 1);
    uint32_t i = 1 + original_size;
    uint32_t previous = availableList.tail;
    if (availableList.head == 0)
    {
        availableList.head = i;
    }
    if (availableList.tail > 0)
    {
        elements[availableList.tail].next = i;
    }
    ... // 逐元素挂入 availableList 的循环省略
    // set up tail
    elements[i].previous = previous;
    elements[i].next = 0;
    elements[i].list = &availableList;
    availableList.tail = i;
    availableList.count += (new_size - original_size);
}

void PagedLODContainer::resize()
{
    uint32_t original_size = static_cast<uint32_t>(elements.size() - 1);
    uint32_t new_size = original_size * 2;
    resize(new_size);
}

逐字段推导:elements.resize(new_size + 1) 使合法下标为 0..new_size。循环 for (; i < new_size; ++i)(:59)把 i 从 1 + original_size 走到 new_size - 1,每个元素的 next = i + 1;循环退出时 i == new_size,:69–71 单独处理最后一个元素(下标 new_size)并把它设为 availableList.tail。所以循环条件写 < new_size 而非 <= new_size 是为了把最后一个元素留给循环外的 tail 设置,没有越界。

但三处边界没有保护。其一,availableList.count += (new_size - original_size)(:75)是无符号加法,resize() 无参版本(:83–88)用 new_size = original_size * 2 保证递增,构造用 std::max(maxNumPagedLOD, 10u) 保证初值足够,因此正常路径不会下溢;可 resize(uint32_t) 是公开方法,外部若传一个小于当前 original_size 的值,new_size - original_size 下溢成极大 uint32_t,availableList.count 瞬间变成天文数字,而 elements 实际被缩小——count 与真实链长彻底脱节。也就是说 check() 是写好的一致性校验,却在默认构建里零调用——第十九 19.5.5 会把它归进「死代码与零调用 API」清单。

19.5.4 _move 的两个分支与 const_cast

// src/vsg/io/DatabasePager.cpp:110-167(分支一:index == 0)
void PagedLODContainer::_move(const PagedLOD* plod, List* targetList)
{
    if (plod->index == 0)
    {
        // resize if there are no available empty elements.
        if (availableList.head == 0)
        {
            resize();
        }
        // take the first element from availableList and move head to next item.
        uint32_t index = availableList.head;
        auto& element = elements[availableList.head];
        if (availableList.head == availableList.tail)
        {
            availableList.head = 0;
            availableList.tail = 0;
        }
        else
        {
            availableList.head = element.next;
        }
        // next_element.previous 清零省略
        // 挂到 targetList 尾部的链表搬移省略
        // assign index to PagedLOD
        plod->index = index;
        element.plod = const_cast<PagedLOD*>(plod);
        --(availableList.count);
        ++(targetList->count);
        return;
    }

_move 的形参是 const PagedLOD*,函数体却写 plod->index = index(:160)与 element.plod = const_cast<PagedLOD*>(plod)(:161)。index 是 mutable uint32_t(PagedLOD.h:108),所以写它合法;const_cast 则是为了把 const 指针塞进 ref_ptr<PagedLOD>。与 19.4.3 的 const_cast 同源,都是「接口用 const、实现要持有非 const 强引用」的折中。

分支二(:169–230)处理已分配 index 的节点:先从 previousList 摘除(:186–204 改前后元素的 next/previous、必要时挪 head/tail),再挂到 targetList 尾部(:206–226),最后 --previousList.count / ++targetList.count(:228–229)。:172–178 是短路:若 previousList == targetList 直接返回,避免自搬。整个函数只改下标与计数,不分配不释放,是典型的侵入式链表搬移。

19.5.5 check() 与两个编译期为零的宏

// src/vsg/io/DatabasePager.cpp:23-24
#define PRINT_CONTAINER 0
#define CHECK_CONTAINER 0
// src/vsg/io/DatabasePager.cpp:280-365(摘要)
bool PagedLODContainer::check(const List& list)
{
    if (list.head == 0)
    {
        if (list.tail == 0)
        {
            if (list.count == 0) return true;
            warn("list ", list.name, " has a head==0 and tail==0 but length is ", list.count);
            return false;
        }
        warn("list ", list.name, " has a head==0, but tail is non zero");
        return false;
    }
    const auto& head_element = elements[list.head];
    if (head_element.previous != 0) { ... return false; }
    const auto& tail_element = elements[list.tail];
    if (tail_element.next != 0) { ... return false; }
    uint32_t count = 0;
    for (uint32_t i = list.head; i > 0 && count < elements.size();)
    {
        ...
        ++count;
        i = element.next;
    }
    if (count == list.count) return true;
    return false;
}

bool PagedLODContainer::check()
{
    bool result1 = check(availableList);
    bool result2 = check(activeList);
    bool result3 = check(inactiveList);
    return result1 && result2 && result3;
}

容量 elements 只增不减,create(4000)(DatabasePager.cpp:500)预开 4001 个 Element,每个含一个 ref_ptr、两个 uint32_t 与一个 List*;sizeof(Element) 随 ABI 变化,19.17 给出测量程序。容量上限与 targetMaxNumPagedLODWithHighResSubgraphs = 1500(DatabasePager.h:149)无关,预算只在 updateSceneGraph:721 起回收作用,这是两套量纲。

19.6 帧预算的五个数字:10000 / 4000 / 1500 / 60 / 3

第十八章预告第三问把 maxNumPagedLOD = 10000、targetMaxNumPagedLODWithHighResSubgraphs = 1500、start(numReadThreads = 4) 并列成「三个默认值决定帧预算」。实测后要拆成五个数、三套量纲,其中两个默认值从未按字面生效。

// include/vsg/io/DatabasePager.h:53/135/143-156
        explicit PagedLODContainer(uint32_t maxNumPagedLOD = 10000);
        virtual void start(uint32_t numReadThreads = 4);
        std::atomic_uint numActiveRequests{0};
        std::atomic_uint64_t frameCount{0};
        ref_ptr<CulledPagedLODs> culledPagedLODs;
        /// for systems with smaller GPU memory limits you may need to reduce the targetMaxNumPagedLODWithHighResSubgraphs to keep memory usage within available limits.
        uint32_t targetMaxNumPagedLODWithHighResSubgraphs = 1500;
        /// number of frames before a PagedLOD with a failed load/compile is attempted to be loaded/compiled again.
        uint64_t delayBeforeNextLoadAttempt = 60;
        std::mutex pendingPagedLODMutex;
        ref_ptr<PagedLODContainer> pagedLODContainer;
// 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);
}

19.6.1 五个数字的归属表

数字完整位置类型实际用途
10000include/vsg/io/DatabasePager.h:53构造默认参数PagedLODContainer 不传参时的初始容量,DatabasePager 从未用这个默认值
4000src/vsg/io/DatabasePager.cpp:500实际实参DatabasePager 构造的容器上限,resize(std::max(4000, 10u)) 得 4001 个元素
1500include/vsg/io/DatabasePager.h:149公开可调成员updateSceneGraph:721 的回收阈值,单位「带高精子图的 PagedLOD 个数」
60include/vsg/io/DatabasePager.h:152公开可调成员requestDiscarded:655 的 frameNextLoadAttempt 增量,单位「帧」
3include/vsg/nodes/PagedLOD.h:55内联默认参数highResActive 的 inactiveAge,单位「帧」;另有 include/vsg/threading/DeleteQueue.h:39 的 retainForFrameCount = 3,单位也是帧但属于删除队列

start(uint32_t numReadThreads = 4)(DatabasePager.h:135)与 include/vsg/state/ResourceHints.h:76 的 numDatabasePagerReadThreads = 4 是第六、第七个数字,量纲是读线程条数,由 src/vsg/app/Viewer.cpp:410–413 决定用 hint 还是默认 4。

19.6.2 10000 与 4000:一个从未生效的默认值

PagedLODContainer::PagedLODContainer(uint32_t maxNumPagedLOD)(src/vsg/io/DatabasePager.cpp:30–38)把实参交给 resize(std::max(maxNumPagedLOD, 10u))(:37)。全库对 PagedLODContainer::create 的调用只有 :500 一处,实参写死 4000;grep -rn "maxNumPagedLOD" include/ src/ 只命中 DatabasePager.h:53、DatabasePager.cpp:30、:37 三行,没有第二处构造。于是 10000 这个默认值在 1.1.16 的 DatabasePager 路径上从未生效,它只服务于「外部直接 PagedLODContainer::create() 不传参」的假想用法。

19.6.3 1500 与 3:预算判定与 inactiveAge 的配合

// src/vsg/io/DatabasePager.cpp:716-727
        // set the number of PagedLOD to expire
        uint32_t total = pagedLODContainer->activeList.count + pagedLODContainer->inactiveList.count;
        debug("DatabasePager : activeList.count = ", pagedLODContainer->activeList.count, ", inactiveList.count = ", pagedLODContainer->inactiveList.count, ", total = ", total);
        if ((nodes.size() + total) > targetMaxNumPagedLODWithHighResSubgraphs)
        {
            uint32_t numPagedLODHighRestSubgraphsToRemove = (static_cast<uint32_t>(nodes.size()) + total) - targetMaxNumPagedLODWithHighResSubgraphs;
            uint32_t targetNumInactive = (numPagedLODHighRestSubgraphsToRemove < pagedLODContainer->inactiveList.count) ? (pagedLODContainer->inactiveList.count - numPagedLODHighRestSubgraphsToRemove) : 0;
            debug("Need to remove, inactive count = ", pagedLODContainer->inactiveList.count, ", target = ", targetNumInactive);

nodes 是 _toMergeQueue->take_all(cr)(:669)取出的「本帧待合并」节点,total 是容器里已登记的节点,两者相加才与 1500 比。numPagedLODHighRestSubgraphsToRemove 是「超出的个数」,targetNumInactive 是「回收后 inactiveList 允许保留的个数」,:724 的三元在超出量大于 inactiveList 全部时取 0。随后 :728–756 从 inactiveList.head 起逐个 CAS 并 trim,直到 inactiveList.count <= targetNumInactive。

inactiveList 的成员由 highResActive 判定迁入:PagedLOD.h:55–58 的 inactiveAge = 3 意味着「连续 3 帧没被高精使用」才 !highResActive。updateSceneGraph:679–698 两个循环把这类节点从 activeList 搬到 inactiveList,预算回收只从 inactiveList 摘(:728),不会动 activeList。这是「帧预算无上界」的一种软性表现——阈值存在,但没有强制在单帧内回落到阈值以下的机制。

19.6.4 60 与 frameNextLoadAttempt

delayBeforeNextLoadAttempt = 60(DatabasePager.h:152)只在 requestDiscarded 里被用一次:plod->frameNextLoadAttempt = frameCount.load() + delayBeforeNextLoadAttempt(DatabasePager.cpp:655)。消费点是 DatabaseQueue::take_when_available(:428、:443)的 frameNextLoadAttempt.load() <= frameCount。于是「失败后 60 帧内不再尝试」不是靠定时器,而是让读线程扫队列时跳过它。

// src/vsg/io/DatabasePager.cpp:426-426
    for (; itr != _queue.end(); ++itr)
    {

frameNextLoadAttempt 超期的元素先被 skipped 计数。

这里有个不对称:frameNextLoadAttempt 只在失败路径设置,成功路径(:577 之后)从不清零,也不在 read(PagedLOD.cpp:57–80)里序列化——该函数只读 bound、child.minimumScreenHeightRatio 与 child.filename;atomic_uint64_t 不是 Object 子类,write(:82–93)完全不写它。节点从文件重载后该值回到类内默认的 0,历史失败记录丢失。收益是避免对坏文件高频重试;代价是 60 帧内相机已经靠近、用户愿意重试也没办法,且 60 是固定帧数而非时间,高刷屏与低刷屏下实际等待时长不同。


19.7 DatabaseQueue:条件变量、优先级扫描与丢失唤醒

两个 DatabaseQueue 实例(请求队列、合并队列)是同一份代码。它既要当「读线程的阻塞队列」,又要当「主线程的 CompileResult 累加器」,两个职责挤在一个类里,是 19.12 的 break 缺陷被放大的结构原因。

// include/vsg/io/DatabasePager.h:92-123
    /// Thread safe queue for tracking PagedLOD that needs to be loaded, compiled or merged by the DatabasePager
    class VSG_DECLSPEC DatabaseQueue : public Inherit<Object, DatabaseQueue>
    {
    public:
        explicit DatabaseQueue(ref_ptr<ActivityStatus> status);
        using Nodes = std::list<ref_ptr<PagedLOD>>;
        ActivityStatus* getStatus() { return _status; }
        const ActivityStatus* getStatus() const { return _status; }
        void add(ref_ptr<PagedLOD> plod);
        void add(ref_ptr<PagedLOD> plod, const CompileResult& cr);
        /// prune entries older than specified frameCount
        uint32_t prune(uint64_t frameCount);
        ref_ptr<PagedLOD> take_when_available(uint64_t frameCount);
        Nodes take_all(CompileResult& result);
    protected:
        ~DatabaseQueue() override;
        std::mutex _mutex;
        std::condition_variable _cv;
        Nodes _queue;
        CompileResult _compileResult;
        ref_ptr<ActivityStatus> _status;
    };

19.7.1 两个 add 与 notify 的次序

// src/vsg/io/DatabasePager.cpp:380-395
void DatabaseQueue::add(ref_ptr<PagedLOD> plod)
{
    std::scoped_lock lock(_mutex);
    _queue.emplace_back(plod);
    _cv.notify_one();
}

void DatabaseQueue::add(ref_ptr<PagedLOD> plod, const CompileResult& cr)
{
    std::scoped_lock lock(_mutex);
    _queue.emplace_back(plod);
    _cv.notify_one();
    _compileResult.add(cr);
}

单参 add(:380–387)给 _requestQueue 用;双参 add(:389–395)给 _toMergeQueue 用,多带一个 CompileResult。两处都在 std::scoped_lock 持锁期间 notify_one(),这是合法但非最优的写法:被唤醒的线程立刻要抢同一把 _mutex,会短暂阻塞,属于「hurry up and wait」,不影响正确性。

真正的问题在双参版的次序::393 先 notify_one(),:394 才 _compileResult.add(cr)。当前调用链掩盖了这个缺陷,属于潜在竞态而非已触发的 bug。

19.7.2 take_when_available 的四个分支

// src/vsg/io/DatabasePager.cpp:397-451
ref_ptr<PagedLOD> DatabaseQueue::take_when_available(uint64_t frameCount)
{
    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())
    {
        _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 (_queue.empty() || _status->cancel())
    {
        return {};
    }
    // find the PagedLOD with the highest priority;
    auto itr = _queue.begin();
    size_t skipped = 0;
    // find first PagedLOD in queue that can be loaded/compiled
    for (; itr != _queue.end(); ++itr)
    {
        if ((*itr)->frameNextLoadAttempt.load() <= frameCount) break;
        ++skipped;
    }
    if (itr == _queue.end())
    {
        return {};
    }
    auto highest_itr = itr++;
    // find lowest priority PagedLOD in queue.
    for (; itr != _queue.end(); ++itr)
    {
        if ((*itr)->frameNextLoadAttempt.load() <= frameCount && (*itr)->priority > (*highest_itr)->priority) highest_itr = itr;
    }
    ref_ptr<PagedLOD> plod = *highest_itr;
    _queue.erase(highest_itr);
    return plod;
}

分支一 :405–409 的 while (_queue.empty() && _status->active()) 配 wait_for(100ms):wait_for 超时返回后不重新判谓词本身,但 while 条件会在下一轮重查 _queue.empty() && _status->active(),所以「超时后队列仍空」会继续睡,不会误取。分支四 :438–447 从那个元素起往后扫,取 priority 最大者,:447 从链表擦除并返回。

19.7.3 skipped 死变量与优先级扫描的覆盖缺口

size_t skipped = 0(:423)在 :429 自增,之后只在 :449 的注释里被提到一次(该行整行是注释),实际代码从未读取它。这是一个编译期不报(变量被写入)、运行期无用的死变量,属于第十九章「死代码与零调用 API」清单里最轻的一例。

比死变量更重要的是扫描覆盖缺口::426–430 的第一个循环只用来「定位起点」,它遇到第一个 frameNextLoadAttempt <= frameCount 的元素就 break,不比较这个起点之前元素的 priority;:441–444 的第二个循环才从 itr++ 开始比。这是文档级错误,不影响行为,但会误导读者以为队列按低优先级淘汰。

19.7.4 prune 的强制状态复位

// src/vsg/io/DatabasePager.cpp:453-474
uint32_t DatabaseQueue::prune(uint64_t frameCount)
{
    std::unique_lock lock(_mutex);
    uint32_t numRemoved = 0;
    for (auto itr = _queue.begin(); itr != _queue.end();)
    {
        if (((*itr)->frameHighResLastUsed.load() + 1) < frameCount)
        {
            ++numRemoved;
            (*itr)->requestCount.exchange(0);
            (*itr)->requestStatus.exchange(PagedLOD::NoRequest);
            itr = _queue.erase(itr);
        }
        else
        {
            ++itr;
        }
    }
    return numRemoved;
}

:460 的过期判据是 (frameHighResLastUsed + 1) < frameCount,即「上次使用至少早于当前帧两帧」。更实际的风险是 numActiveRequests -= _requestQueue->prune(...)(:667):prune 返回「被摘掉的个数」,:667 直接按这个数扣 numActiveRequests,而 request()(:642)的 ++numActiveRequests 与「进队列」是一一对应的,看似守恒;可 :657 的 --numActiveRequests(requestDiscarded)、:784 的 -= nodes.size() 也各扣一次,19.10.3 会证明三条扣减路径能对同一个计数重复作用。

prune 还漏了 frameNextLoadAttempt 与 loadAttempts 的复位,pending 更没碰。被 prune 的节点若之前 requestDiscarded 过,frameNextLoadAttempt 仍是「未来 60 帧」的值,下一次 request() 把它放回队列后,take_when_available:428 会继续跳过它——失败记录跨请求残留。

19.7.5 take_all 与两处带超时的条件变量

// src/vsg/io/DatabasePager.cpp:476-484
DatabaseQueue::Nodes DatabaseQueue::take_all(CompileResult& cr)
{
    std::scoped_lock lock(_mutex);
    Nodes nodes;
    nodes.swap(_queue);
    cr.add(_compileResult);
    _compileResult.reset();
    return nodes;
}

take_all 一次性 swap 整个队列(:480),把累积的 _compileResult 用 cr.add(...) 合进调用方的 CompileResult(:481),再 reset()(:482)。第十六章 16.14.3 说「两处带超时」,若按「分页子系统直接相关」计是 DatabasePager.cpp:408 与 DeleteQueue.cpp:58 两处,若按所有 _cv.wait_for 计是三处,本章采用实测的三处口径。

wait_for(100ms) 与读线程 :609 的 sleep_for(16 * 2)(32ms)共同决定「空队列时的响应延迟」:读线程取到空 ref_ptr 后睡 32ms 再重入 take_when_available,而后者最多再等 100ms。规避办法是把 :609 的 sleep_for 换成带谓词的 _cv.wait,或让 add 在 notify_one() 外再 notify_all()。


19.8 DatabasePager 的构造、四个装配点与析构停线程

第十六章 16.12 实测出 DeleteQueue 在 DatabasePager.cpp 的四个装配/使用点 :498、:623、:665、:791。本节用完整构造与析构代码复验这四个行号,并补上「停止」这条缺失的对称路径。

// src/vsg/io/DatabasePager.cpp:490-518
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);
}

// src/vsg/io/DatabasePager.cpp:503-513
DatabasePager::~DatabasePager()
{
    debug("DatabasePager::~DatabasePager()");
    status->set(false);
    for (auto& thread : threads)
    {
        thread.join();
    }
}

void DatabasePager::assignInstrumentation(ref_ptr<Instrumentation> in_instrumentation)
{
    instrumentation = in_instrumentation;
}

19.8.1 构造函数逐字段

status = ActivityStatus::create()(:492)用 if (!status) 守卫,允许派生类或外部先注入;ActivityStatus 的默认构造 active = true(include/vsg/threading/ActivityStatus.h:24)。pagedLODContainer(:500)硬编码 4000,19.6.2 已拆。

构造里没有 compileManager = CompileManager::create(...)。compileManager(DatabasePager.h:141)是公开的裸 ref_ptr,默认空;真正的赋值在 Viewer::compile(src/vsg/app/Viewer.cpp:383–386)里:databasePager->compileManager = compileManager。于是「构造完立刻 start()」而没经过 Viewer::compile 的 DatabasePager 会在读线程 :575 解引用空 compileManager(19.9.6)。

// src/vsg/app/Viewer.cpp:383-383
    if (databasePager && !databasePager->compileManager)
    {

compileManager 与 resourceScavenger 同处一个装配分支。

19.8.2 四个装配点复验

行号代码角色
:498deleteQueue = DeleteQueue::create(status)装配:构造时创建删除队列并共享 status
:623databasePager.deleteQueue->wait_then_clear()使用:删除线程循环里阻塞等待并执行删除
:665deleteQueue->advance(frameStamp)使用:主线程每帧灌入帧号、按到期条件 notify_one()
:791deleteQueue->add_prune(deleteList, sharedObjectsToPrune)使用:trim 与 merge 之后把待删对象与待 prune 的 SharedObjects 入队

19.8.3 析构停线程与 startThread/stopThread 的缺席

~DatabasePager()(:503–513)只做两件事:status->set(false)(:507)、遍历 threads 逐个 join()(:509–512)。第二次 start() 会创建第二组读线程与第二个删除线程,两组线程共享同一对队列,属于重复启动无保护。

19.8.4 assignInstrumentation 的声明与实现不符

DatabasePager.h:161–162 的注释写「assign Instrumentation to all CompileTraversal and their associated Context」,而实现(:515–518)只有一行 instrumentation = in_instrumentation;,没有遍历任何 CompileTraversal,也没有碰 compileManager。这是「声明与实现不符」型静默降级:调用方若只调 databasePager->assignInstrumentation(...)(如 Viewer.cpp:352 在自动创建 pager 时做的那样),编译遍历侧不会拿到 instrumentation。

// src/vsg/io/DatabasePager.cpp:515-515
void DatabasePager::assignInstrumentation(ref_ptr<Instrumentation> in_instrumentation)
{

实现只有一次赋值,没有遍历 CompileTraversal。

19.9 start():读线程、三条失败路径与删除线程

start() 把「读盘 → 编译 → 入合并队列」整条流水线封进一个 lambda,另起一个删除线程。它是分页子系统唯一的生产者。

// src/vsg/io/DatabasePager.cpp:533-559
        while (databasePager.status->active())
        {
            auto plod = databasePager._requestQueue->take_when_available(databasePager.frameCount.load());
            if (plod)
            {
                CPU_INSTRUMENTATION_L1_NC(databasePager.instrumentation, "DatabasePager read", COLOR_PAGER);
                uint64_t frameDelta = databasePager.frameCount - plod->frameHighResLastUsed.load();
                if (frameDelta > 1 || !compare_exchange(plod->requestStatus, PagedLOD::ReadRequest, PagedLOD::Reading))
                {
                    info("Expire read request : databasePager.frameCount = ", databasePager.frameCount, ", plod->frameHighResLastUsed.load() = ", plod->frameHighResLastUsed.load());
                    databasePager.requestDiscarded(plod);
                    continue;
                }
                ++plod->loadAttempts;
                ref_ptr<Node> subgraph = plod->pending;
                ref_ptr<Object> read_object;
                if (!subgraph)
                {
                    read_object = vsg::read(plod->filename, plod->options);
                    subgraph = read_object.cast<Node>();
                }
// src/vsg/io/DatabasePager.cpp:565-604
                if (subgraph && compare_exchange(plod->requestStatus, PagedLOD::Reading, PagedLOD::Compiling))
                {
                    {
                        std::scoped_lock<std::mutex> lock(databasePager.pendingPagedLODMutex);
                        plod->pending = subgraph;
                    }
                    try
                    {
                        if (auto result = databasePager.compileManager->compile(subgraph))
                        {
                            plod->requestStatus.exchange(PagedLOD::MergeRequest);
                            databasePager._toMergeQueue->add(plod, result);
                        }
                    ... // 编译失败与抛异常两条路径各调一次 requestDiscarded
                }
                else
                {
                    if (auto read_error = read_object.cast<ReadError>())
                        warn(read_error->message);
                    else
                        warn("Failed to read ", plod, " ", plod->filename);
                    databasePager.requestDiscarded(plod);
                }

19.9.1 读线程主循环与过期判定

:533 的 while (status->active()) 与 :535 的 take_when_available(frameCount) 构成消费循环,:536 的 if (plod) 区分「取到节点」与「队列空/全在冷却/正在停线程」,后者在 :609 睡 32ms。:540 的 frameDelta = frameCount - frameHighResLastUsed 是 19.4.5 六处无符号减法中的一处:一旦 frameCount 被 :664 置 0 或帧号回退,frameDelta 下溢成极大值,:542 的 frameDelta > 1 恒真,所有请求在 :545 被 requestDiscarded 丢弃,分页停摆。:542 的第二个条件 !compare_exchange(ReadRequest, Reading)(实现见 atomics.h:46–50)处理「状态已被别的路径改动」,与过期判定共用同一个 requestDiscarded,日志却统一打 Expire read request,把「状态竞争失败」误报成「帧过期」。

// include/vsg/threading/atomics.h:46-46
    bool compare_exchange(std::atomic<T>& reference, T from, T to)
    {

compare_exchange 的 from 只是本地副本。

// src/vsg/io/DatabasePager.cpp:540-542
                uint64_t frameDelta = databasePager.frameCount - plod->frameHighResLastUsed.load();
                if (frameDelta > 1 || !compare_exchange(plod->requestStatus, PagedLOD::ReadRequest, PagedLOD::Reading))

frameDelta 只在无符号减法后与 1 比较,requestStatus 竞争失败共用一个日志文案。

19.9.2 三条失败路径与 ReadError 唯一识别点

:565 把「读成功」与「状态 Reading → Compiling」合成一个条件。于是 :597–604 的 else 有两种成因:其一是 vsg::read 真的失败(subgraph 空),其二是读成功但 compare_exchange 被别的线程抢先改了状态。第二种情况下 read_object 是合法 Node,:598 的 cast<ReadError>() 必为空,:601 打 Failed to read——状态竞争失败被误报为文件读取失败,这是错误分支的硬缺陷。

:572–594 的 try/catch(...) 包住 compileManager->compile(subgraph)。但 CompileManager.h:93–97 的注释明写「Does not throw on compile failure: any vsg::Exception is caught internally and reported via the returned CompileResult」,所以 catch(...) 只在非 vsg::Exception 的异常(如 std::bad_alloc、第三方插件抛的异常)时触发。三条失败路径——compile 返回假(:584–588)、compile 抛异常(:590–594)、读失败或 CAS 失败(:597–604)——全部调用同一个 requestDiscarded,而该函数不清 pending(19.10.2)。

19.9.3 删除线程与 compileManager 空指针

:615–626 的 deleteThread 只做 while (status->active()) databasePager.deleteQueue->wait_then_clear();:628–633 创建 numReadThreads 个读线程加 1 个删除线程。正常路径由 Viewer::compile:383–386 补齐,属于「装配顺序隐式契约」而非显式校验。


19.10 request / requestDiscarded:状态机与 pending 泄漏

// src/vsg/io/DatabasePager.cpp:636-658
void DatabasePager::request(ref_ptr<PagedLOD> plod)
{
    if (compare_exchange(plod->requestStatus, PagedLOD::NoRequest, PagedLOD::ReadRequest))
    {
        debug("DatabasePager::request(", plod.get(), ") adding to requestQueue ", plod->filename, ", ", plod->priority, " plod=", plod.get());
        _requestQueue->add(plod);
        ++numActiveRequests;
    }
}

// src/vsg/io/DatabasePager.cpp:646-658
void DatabasePager::requestDiscarded(PagedLOD* plod)
{
    //std::scoped_lock<std::mutex> lock(pendingPagedLODMutex);
    //plod->pending = nullptr;
    plod->requestCount.exchange(0);
    plod->requestStatus.exchange(PagedLOD::NoRequest);
    // plod->pending = {};
    plod->frameNextLoadAttempt = frameCount.load() + delayBeforeNextLoadAttempt;
    --numActiveRequests;
}

19.10.1 CAS 与计数的单点自增

request(:638)只在 NoRequest → ReadRequest 成功时入队并 ++numActiveRequests(:642),与 RecordTraversal.cpp:227 的 requestCount.fetch_add(1) 首值判断构成两级去重:遍历层保证「同一批只调一次 request」,pager 层保证「状态机只在空闲时接受」,numActiveRequests 因此只在 :642 有一处自增。

// src/vsg/io/DatabasePager.cpp:638-638
    if (compare_exchange(plod->requestStatus, PagedLOD::NoRequest, PagedLOD::ReadRequest))
    {

CAS 成功才 add 并 ++numActiveRequests。 它是 std::atomic_uint(DatabasePager.h:143),无符号 32 位。

19.10.2 三行被注释的 pending 清理

requestDiscarded(:646–658)里 :648、:649、:653 三行 pending 清理全部被注释::648 注释掉的 scoped_lock、:649 的 plod->pending = nullptr、:653 的 plod->pending = {}。实际生效的只有 :650 requestCount=0、:651 requestStatus=NoRequest、:655 frameNextLoadAttempt = frameCount + 60、:657 --numActiveRequests。

后果要连着 :569 看:读线程在 :568–570 持 pendingPagedLODMutex 把 plod->pending = subgraph,之后若 :584 编译失败或 :590 抛异常,requestDiscarded 不清 pending,已加载的子图一直被 PagedLOD 强引用。规避办法是恢复 :649 的清理并给所有 pending 读写统一加锁。

19.10.3 numActiveRequests 的下溢

:657 的 --numActiveRequests、updateSceneGraph:667 的 -= prune(...)、:784 的 -= nodes.size() 是三处扣减,只有 :642 一处自增。:784 无条件按 nodes.size() 扣,而 :769–783 的 merge 循环里只有 compare_exchange(MergeRequest, Merging) 成功者才被真正合并;若 _toMergeQueue 里某个 plod 的状态已被 prune(:465)或别的路径改成 NoRequest,CAS 失败,它不 merge 却仍计入 nodes.size() 被扣一次。这是第 5 条硬结论。


19.11 updateSceneGraph:帧号、活跃迁移、回收与合并

这是主线程每帧调用一次的唯一入口,也是所有硬缺陷汇合的地方。

// src/vsg/io/DatabasePager.cpp:660-669
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());
    auto nodes = _toMergeQueue->take_all(cr);
// src/vsg/io/DatabasePager.cpp:687-698 / 728-743
        auto& activeList = pagedLODContainer->activeList;
        for (uint32_t index = activeList.head; index != 0;)
        {
            auto& element = elements[index];
            index = element.next;
            if (!element.plod->highResActive(frameCount))
            {
                pagedLODContainer->inactive(element.plod.get());
            }
        }
        ...
            for (uint32_t index = pagedLODContainer->inactiveList.head; (index != 0) && (pagedLODContainer->inactiveList.count > targetNumInactive);)
            {
                auto& element = elements[index];
                index = element.next;
                if (compare_exchange(element.plod->requestStatus, PagedLOD::NoRequest, PagedLOD::DeleteRequest))
                {
                    ref_ptr<PagedLOD> plod = element.plod;
                    plod->children[0].node = nullptr;
                    plod->requestCount.exchange(0);
                    plod->requestStatus.exchange(PagedLOD::NoRequest);
                    deleteList.push_back(plod->pending);
                    plod->pending = {};
                    deleteList.push_back(plod);
                    pagedLODContainer->remove(plod);
                    if (plod->options->sharedObjects)
// src/vsg/io/DatabasePager.cpp:769-784
        for (auto& plod : nodes)
        {
            if (compare_exchange(plod->requestStatus, PagedLOD::MergeRequest, PagedLOD::Merging))
            {
                debug("   Merged ", plod->filename, " after ", plod->requestCount.load(), " priority ", plod->priority.load(), " ", frameCount - plod->frameHighResLastUsed.load(), " plod = ", plod);
                {
#if LOCAL_MUTEX
                    std::scoped_lock<std::mutex> lock(pendingPagedLODMutex);
#endif
                    plod->children[0].node = plod->pending;
                }
                plod->requestStatus.exchange(PagedLOD::NoRequest);
            }
        }
        numActiveRequests -= static_cast<uint32_t>(nodes.size());

19.11.1 frameCount 置 0 与 advance 的判空不对称

:664 用 frameStamp ? frameStamp->frameCount : 0 做了判空防御,:665 紧跟的 deleteQueue->advance(frameStamp) 却把同一个可能为空的 frameStamp 直接传下去,而 DeleteQueue::advance(src/vsg/threading/DeleteQueue.cpp:36)第一句就是 frameCount = frameStamp->frameCount;,无判空。同一个函数里相邻两行对同一参数两种态度,是「状态保存/恢复不对称」的硬缺陷:frameStamp 为空时 :664 把分页器 frameCount 归 0,:665 空指针解引用崩溃;即便不崩,19.4.5 的无符号下溢链也会被触发。Viewer::update:804 传的是 _frameStamp(Viewer.cpp:36 起恒非空),正常路径不触发,但公共 API 的契约缺口客观存在。

// src/vsg/threading/DeleteQueue.cpp:32-32
void DeleteQueue::advance(ref_ptr<FrameStamp> frameStamp)
{

advance 第一句就解引用 frameStamp。

// src/vsg/io/DatabasePager.cpp:664-664
    frameCount.exchange(frameStamp ? frameStamp->frameCount : 0);
    deleteQueue->advance(frameStamp);

frameCount 有判空,advance 却没有。

:667 的 numActiveRequests -= prune(...) 与 :784 的 -= nodes.size() 是 19.10.3 两处扣减的现场;:669 的 take_all(cr) 把合并队列的 CompileResult 合进 cr,:Viewer::update:808 的 cr.requiresViewerUpdate(this) 再决定是否 updateViewer(19.12)。

19.11.2 边遍历边改链、回收分支与 options 空指针

:687–698 遍历 activeList 时,:691 先 index = element.next 缓存后继,再在 :696 调 inactive() → _move()。_move 的 :186–187 会改 elements[element.previous].next 与 elements[element.next].previous,:206–226 把当前元素挂到 inactiveList 尾部并把它的 next 置 0。因为后继下标已提前缓存,单链表遍历侥幸能继续,但这是「遍历过程中修改被遍历容器」的脆弱写法,且 check() 因宏为 0 不校验(19.5.5),一旦 _move 的链维护有任何偏差,就没有任何运行期告警。

回收分支 :733 的 CAS 把状态设成 DeleteRequest,:738 立刻 exchange(NoRequest) 清回,Deleting = 7 全库零使用(19.2.4)。:736 把 children[0].node 置空、:740 把 plod->pending 塞进 deleteList、:741 清 pending、:743 把 plod 自身也塞进 deleteList、:744 从容器移除。deleteList.push_back(plod) 也不会真正销毁节点——场景图父节点仍持有强引用,DeleteQueue 里的 ref_ptr 只是多一份引用,:744 的 remove() 才释放容器那份(19.5.2)。

// src/vsg/io/DatabasePager.cpp:733-733
                if (compare_exchange(element.plod->requestStatus, PagedLOD::NoRequest, PagedLOD::DeleteRequest))
                {

DeleteRequest 设入后立刻被 NoRequest 覆盖。

19.11.3 merge 分支与 pending 只增不清

:771 的 CAS MergeRequest → Merging 成功后,:778 把 plod->pending 赋给 children[0].node,:781 立刻把状态清回 NoRequest。LOCAL_MUTEX(:762 定义为 1)让 :776 的写持 pendingPagedLODMutex,但 :551、:740 的读写不持锁(19.10.2),锁只覆盖了 merge 这一处,属于局部补丁。

// src/vsg/io/DatabasePager.cpp:771-771
            if (compare_exchange(plod->requestStatus, PagedLOD::MergeRequest, PagedLOD::Merging))
            {

LOCAL_MUTEX 只覆盖 merge 这一处写 pending。

:791 的 if (!deleteList.empty() || !sharedObjectsToPrune.empty()) deleteQueue->add_prune(...) 是第四装配点。注意条件是「或」,允许「只有 sharedObjects 要 prune、没有对象要删」的调用;而 DeleteQueue::wait_then_clear(DeleteQueue.cpp:72)只在 numObjectsToDelete > 0 时才 sharedObjects->prune(),这种纯 prune 请求会被静默跳过(19.16.3)。


19.12 CompileResult::add 的 break 在分页下的放大

第十四章 H6 已经定位 src/vsg/app/CompileManager.cpp:50 的 break 应为 continue:当 src_binDetails 的 indices 与 bins 同时为空时它提前跳出 cr.views 循环,continue 只会跳过当前 view。本章补它在分页批量合并场景下的第二重后果。

// 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);
}
// 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;
    }
    // viewer / maxSlots 逐层检查省略
    return false;
}

19.12.1 add 的逐行语义

:39–42 的 if (result == VK_INCOMPLETE || result == VK_SUCCESS) result = cr.result; 让「最后一个被 add 的结果」决定总体 result:多个子图编译,若前几个成功、最后一个失败,总结果变失败;若前几个失败、最后成功,总结果变成功,前面的失败被覆盖。:44 的 maxSlots.update 与 :46 的 containsPagedLOD 是单调合并(只增不减),:57 的 dynamicData.add 累加。第十四章 14.13.2 已给修复方案(改 continue),本章不重复。

19.12.2 批量合并把单点缺陷放大成系统性漏判

分页链路里 CompileResult::add 被嵌套调用三次:读线程 :582 经 DatabaseQueue::add(plod, cr) 的 _compileResult.add(cr)(:394)累加本帧结果;主线程 take_all(cr) 的 cr.add(_compileResult)(:481)再合进 Viewer::update:797 的局部 cr;Viewer::compile:401 是另一条多 task 汇总。三次共用同一个带 break 的实现,「一个空 view 截断后续」的概率随本帧 tile 数线性上升。

后果链:views 缺项 → requiresViewerUpdate:66–69 看不到后续 view → cr.requiresViewerUpdate(this)(:808)不成立 → updateViewer(Viewer.cpp:887–891)不执行 → commandGraph 的 bin 与 maxSlots 不补齐 → 帧期按缺失的 binNumber 索引 bins 越界。单文件加载空 view 概率低;分页一帧合并几十个 tile 几乎必然踩中,这是硬缺陷被多路复用放大的标本。

19.12.3 与第十四章 H6 的叠加

第十四章从「Viewer::compile 多 task 汇总」角度论证,本章从「_toMergeQueue 多 tile 汇总」角度补第二条触发路径,两者的被调函数完全相同(:37–58)。CompileResult::reset()(CompileManager.cpp:28–35)在 take_all:482 里被调用,把队列的 _compileResult 清空,result 回到 VK_INCOMPLETE,views.clear()——所以缺陷不会跨帧累积,只在本帧批量合并内生效,这解释了它为何长期没被发现:多 View 且某 View 恰好无 bin 需求、又恰好排在有需求 View 之前,是低概率组合,分页的几十个结果把它变成高概率。

19.13 编译链:CompileManager、ResourceScavenger 与 TransferTask

// src/vsg/app/Viewer.cpp:382-386
    // assign CompileManager to DatabasePager
    if (databasePager && !databasePager->compileManager)
    {
        databasePager->compileManager = compileManager;
        compileManager->resourceScavenger = ResourceScavenger::create(databasePager);
    }
// src/vsg/app/CompileManager.cpp:95-112
bool ResourceScavenger::scavenge(ResourceRequirements& /*resourceRequirements*/)
{
    bool scavenged = false;
    // get raw C pointer to avoid a database pager thread invoking scavenger and keeping the database pager alive and pausing destruction
    if (auto ref_databasePager = databasePager.get())
    {
        if (!ref_databasePager->status->active()) return false;
        uint32_t targetPagedLOD = ref_databasePager->pagedLODContainer->activeList.count;
        if (ref_databasePager->pagedLODContainer->inactiveList.count > ref_databasePager->numActiveRequests) targetPagedLOD += ref_databasePager->pagedLODContainer->inactiveList.count - ref_databasePager->numActiveRequests;
        if (targetPagedLOD < ref_databasePager->targetMaxNumPagedLODWithHighResSubgraphs)
        {
            debug("ResourceScavenger::scavenge(..) resetting databasePager->targetMaxNumPagedLODWithHighResSubgraphs to ", targetPagedLOD);
            ref_databasePager->targetMaxNumPagedLODWithHighResSubgraphs = targetPagedLOD;
        }

19.13.1 装配点与 scavenge 的下调逻辑

Viewer::compile:383–386 是全库唯一给 DatabasePager::compileManager 赋值的地方,同时把 ResourceScavenger::create(databasePager) 挂到 compileManager->resourceScavenger(CompileManager.h:103)。ResourceScavenger 用 observer_ptr<DatabasePager>(CompileManager.h:52),:100 的 databasePager.get() 取裸指针,注释明写目的是「避免 pager 线程调用 scavenger 时把 pager 保活、拖住析构」。sleepDuration = 16 * 5(CompileManager.h:51,80ms)在 :116 用来等删除线程干活,:120 用 deletedCount 前后差判断是否真清掉了东西。

19.13.2 targetMax 的数据竞争与传输落点

targetMaxNumPagedLODWithHighResSubgraphs(DatabasePager.h:149)是普通 uint32_t,scavenge:111 在编译线程写它,updateSceneGraph:721 在主线程读它,两边无原子、无锁、无内存序,是明确的数据竞争。CompileManager::compile(src/vsg/app/CompileManager.cpp:257)内部通过 context->transferTask = task->transferTask(:413)把编译期数据上传交给 TransferTask(include/vsg/app/TransferTask.h),Viewer::compile:402 的 task->transferTask->assign(resourceRequirements.dynamicData) 再灌动态数据;ResourceHints(include/vsg/state/ResourceHints.h:63–88)提供 maxSlots、numDescriptorSets、minimumStagingBufferSize = 16 * 1024 * 1024(:70)、containsPagedLOD(:83)、allocatedMemoryLimit = 1.0(:88)。分页子图编译后走的是与首帧编译同一条 CompileManager::compile 路径,不另开传输通道,这是设计上省心的地方,代价是 CompileResult 的视图合并缺陷(19.12)会原样传导到上传阶段。


19.14 Viewer 的挂接点:pager 不在 updateOperations 里

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

19.14.1 硬编码挂接与四步顺序

第十四章把 Viewer::update() 拆成四步,本节复验顺序::800–806 遍历所有 recordAndSubmitTasks,对每个非空 task->databasePager 调 updateSceneGraph(_frameStamp, cr);:808 用 cr.requiresViewerUpdate(this) 决定 updateViewer;:814 updateOperations->run();:817 animationManager->run(_frameStamp)。第十八章预告把 pager 挂接归到「第十四章的 updateOperations」,实测应纠正为「Viewer::update 硬编码循环 + Viewer::compile 装配」。

19.14.2 装配、启动与线程数

Viewer::compile:349–353 在 containsPagedLOD && !databasePager 时自动 DatabasePager::create();:369–372 把 pager 赋给含 PagedLOD 的 task;:405–415 用 hints->numDatabasePagerReadThreads(ResourceHints.h:76,默认 4)或默认参数 4 调 start()。规避是让 pager 全局只挂一个 task,或在循环里去重。


19.15 读文件链:.vsgt / .vsgb / .tile 与 SharedObjects 缓存

// src/vsg/io/read.cpp:31-48 / 76-81
    auto read_file = [&]() -> ref_ptr<Object> {
        if (options && !options->readerWriters.empty())
        {
            for (auto& readerWriter : options->readerWriters)
            {
                auto object = readerWriter->read(filename, options);
                if (object) return object;
            }
            return {};
        }
        auto ext = vsg::lowerCaseFileExtension(filename);
        if (ext == ".vsga" || ext == ".vsgt" || ext == ".vsgb")
        {
            VSG rw;
            return rw.read(filename, options);
        }
    ...
    if (options && options->sharedObjects && options->sharedObjects->suitable(filename))
    {
        auto loadedObject = LoadedObject::create(filename, options);
        options->sharedObjects->share(loadedObject, [&](auto load) {
            load->object = read_file();
// src/vsg/utils/SharedObjects.cpp:218-227 / 238-241
int LoadedObject::compare(const Object& rhs_object) const
{
    int result = Object::compare(rhs_object);
    if (result != 0) return result;
    auto& rhs = static_cast<decltype(*this)>(rhs_object);
    if ((result = filename.compare(rhs.filename))) return result;
    return compare_pointer(options, rhs.options);
}
void SuitableForSharing::apply(const PagedLOD&)
{
    suitableForSharing = false;
}

19.15.1 分派二选一与 ReadError 的传播终点

vsg::read(src/vsg/io/read.cpp:27–120)先判 options->readerWriters 非空则只遍历插件(:32–40),否则才按扩展名走内置 VSG/spirv/json/glsl/txt(:42–73)。二者互斥,不回退(第十七章硬缺陷 2)。第十八章预告第二问的答案因此是::598 是分页线程里唯一识别点,其余 if (object) 短路点(read.cpp:37、:181、ReaderWriter.cpp:47)确实会把 ReadError 当作已加载对象继续传递,只是分页链路靠 cast<Node>() 意外兜住了。

// src/vsg/io/read.cpp:76-76
    if (options && options->sharedObjects && options->sharedObjects->suitable(filename))
    {

suitable 为真时走 share 包住的 read_file。

19.15.2 缓存键漏字段与 PagedLOD 让缓存整体失效

实际缓存是 SharedObjects + LoadedObject(19.1.3)。LoadedObject::compare(:218–227)用 filename 加 compare_pointer(options, rhs.options) 作键;compare_pointer(include/vsg/core/compare.h:23–27,该头文件只依赖 #include <cstring>)在指针不等时调 lhs->compare(*rhs),即 Options::compare(src/vsg/io/Options.cpp:68–84,它逐字段比 readerWriters)。于是「同一 filename、两个不同 options」只要那九个字段相同就命中同一份缓存,第十八章预告第六问成立。

19.15.3 .tile 虚拟文件名与 vsgXchange 边界

.tile 不在 read.cpp:42–73 的内置表里。vsg::tile 是 ReaderWriter 子类(include/vsg/io/tile.h:26),tile::read(src/vsg/io/tile.cpp:118–143)首句 if (extension != ".tile") return {};,按 "root" 或 "x y lod" 解析文件名。vsgXchange(README.md:21)是外部仓库,本仓库只有 include/vsg/state/ViewDependentState.h:104 一条注释提及,提供第三方图像/模型/HTTP 的 ReaderWriter,本章不臆造它的任何实现。

// src/vsg/io/tile.cpp:122-122
    auto extension = vsg::lowerCaseFileExtension(filename);
    if (extension != ".tile") return {};

extension 不符时 tile::read 立即返回空。


19.16 DeleteQueue / Latch:延迟删除与异常路径漏 count_down

// src/vsg/threading/DeleteQueue.cpp:32-42 / 68-83
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();
    }
}
...
    size_t numObjectsToDelete = objectsToDelete.size();
    objectsToDelete.clear();
    if (numObjectsToDelete > 0)
    {
        for (auto& sharedObjects : sharedObjectsToPrune)
        {
            sharedObjects->prune();
        }
        sharedObjectsToPrune.clear();
    }
    deletedCount += numObjectsToDelete;
    return numObjectsToDelete;
// src/vsg/io/read.cpp:139-157 / 160-172
        struct ReadOperation : public Operation
        {
            void run() override
            {
                object = vsg::read(filename, options);
                latch->count_down();
            }
        };
        auto latch = Latch::create(static_cast<int>(filenames.size()));
        for (auto& [filename, object] : entries)
        {
            operationThreads->add(ref_ptr<Operation>(new ReadOperation(filename, options, object, latch)));
        }
        operationThreads->run();
        latch->wait();

19.16.1 advance 空指针与 prune 静默跳过

DeleteQueue::advance(:36)对 frameStamp 无判空,与 DatabasePager.cpp:664 的判空防御、:665 的直接传参构成 19.11.1 已列的不对称。retainForFrameCount = 3(DeleteQueue.h:39)与 numBuffers = 3、imageCount = 3 之间没有共享变量,16.9.3 已判定,本章复验不变。

19.16.2 Latch::count_down 的异常路径

vsg::read(const Paths&)(src/vsg/io/read.cpp:122–191)里的局部 struct ReadOperation(:139–157)是第十七章预告第一问的对象:run() 在 :149 调 vsg::read,:150 无条件 latch->count_down()。若 vsg::read 抛异常(插件抛、std::bad_alloc),:150 不执行,latch = Latch::create(filenames.size())(:160)的计数永不归零,:172 的 latch->wait()(Latch.h:69–76 的 while (_count > 0) _cv.wait(lock))永久阻塞。Latch::count_down()(Latch.h:51–62)的 if (_count.fetch_sub(1) <= 1) 在计数已为 0 或负时仍 release() 并返回 true,本身也允许「多减」,只是无人检查返回值。


19.17 一条请求的全局账本

19.17.1 从「被看见」到「被回收」的时序表

先看撑起整张账本的两个基础原语,它们此前只被引用、没有被完整摘录。

// include/vsg/nodes/PagedLOD.h:55-58
        bool highResActive(uint64_t frameCount, uint64_t inactiveAge = 3) const
        {
            return (frameCount - frameHighResLastUsed.load()) <= inactiveAge;
        }
// include/vsg/threading/atomics.h:46-50
    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);
    };

逐字段推导:highResActive 的两个操作数都是 uint64_t,frameCount - frameHighResLastUsed.load() 是无符号减法,这正是 19.4.5 六处下溢、updateSceneGraph:681/693 活跃迁移判定的共同来源;compare_exchange 用 compare_exchange_strong,成功条件是「当前值恰好等于 from」,失败不修改任何值也不自旋,:638、:542、:565、:733、:771 五处 CAS 全部依赖这一语义。八步账本里任何一步的计数或状态失真,都能回溯到这两个函数之一:前者管「是否过期」,后者管「能否迁移」。

步完整位置动作状态/计数
1src/vsg/app/RecordTraversal.cpp:209/226/230写 frameHighResLastUsed、requestCount++、首次 request()NoRequest → ReadRequest
2src/vsg/io/DatabasePager.cpp:638-643CAS 成功入 _requestQueue、numActiveRequests++ReadRequest
3src/vsg/io/DatabasePager.cpp:535/542读线程取出、frameDelta 判定、CASReadRequest → Reading
4src/vsg/io/DatabasePager.cpp:557/565vsg::read、cast<Node>()、CASReading → Compiling
5src/vsg/io/DatabasePager.cpp:575/577/582compileManager->compile、置 MergeRequest、入 _toMergeQueue→ MergeRequest
6src/vsg/io/DatabasePager.cpp:669/771/778/781take_all、CAS、挂 children[0].node、清状态→ Merging → NoRequest
7src/vsg/io/DatabasePager.cpp:679-698/728-756冷却进 inactiveList、预算超限时 trim→ DeleteRequest → NoRequest
8src/vsg/io/DatabasePager.cpp:791deleteQueue->add_prune 交接DeleteQueue 持有强引用

八步里状态机的有效持久态只有四个(19.2.4),numActiveRequests 在步 2 自增、却在步 3/5/6/7 的多条失败与合并路径上被反复扣减(19.10.3),pending 在步 4 写入、步 6 不清、步 7 才清(19.10.2、19.11.3),options 在步 7 被无判空解引用(19.11.2)。这张表把前十节的所有硬缺陷串成一条可核对的链。

19.17.2 死代码、零调用 API 与无上界清单

把本章定位到的「写好没接上」集中列一次:PRINT_CONTAINER/CHECK_CONTAINER 两个宏恒 0(:23–24)使 PagedLODContainer::check()(:280–365)默认零调用;size_t skipped(:423)写入后从不读取;:440 注释写「lowest priority」而代码取最高;Deleting = 7(PagedLOD.h:104)全库零引用;DeleteRequest/Merging 设入即清(:733/738、:771/781);assignInstrumentation(:515–518)注释承诺「给所有 CompileTraversal 赋值」而实现只存一个字段;maxNumPagedLOD = 10000(DatabasePager.h:53)被 create(4000) 覆盖(:500);cmake/cppcheck-suppression-list.txt:98 的抑制项指向已删除的 include/vsg/io/ObjectCache.h。八项里前六项是源码内的死路径,后两项是构建配置与文档残留。

数字表与源码索引

按文件分组,每条给出完整路径与行区间及可复核结论。

补充逐行索引(每条只引一处,行号可由 grep -n 复核):

  • src/vsg/io/DatabasePager.cpp:544 — frameDelta 与 CAS 失败合并进同一条过期日志。
  • src/vsg/io/DatabasePager.cpp:549 — compare_exchange 失败后立即走 requestDiscarded。
  • src/vsg/io/DatabasePager.cpp:558 — frameHighResLastUsed 未随 subgraph 更新。
  • src/vsg/io/DatabasePager.cpp:640 — numActiveRequests 的自增点紧随 _requestQueue->add。
  • src/vsg/io/DatabasePager.cpp:651 — frameNextLoadAttempt 在失败路径被写成帧号加 60。
  • src/vsg/io/DatabasePager.cpp:748 — sharedObjectsToPrune 与 deleteList 在此交接。
  • src/vsg/app/RecordTraversal.cpp:224 — exchange_if_greater 把 priority 钉在更大值。
  • src/vsg/io/tile.cpp:213 — create_if 把主文件的 options 传给虚拟 tile 文件。
  • src/vsg/io/DatabasePager.cpp:660 — CPU_INSTRUMENTATION_L1 是 updateSceneGraph 首条语句。
  • src/vsg/io/DatabasePager.cpp:669 — _toMergeQueue 的结果合进 CompileResult。
  • include/vsg/nodes/PagedLOD.h:108 — RequestStatus 中的 DeleteRequest 是死状态。
  • src/vsg/io/Options.cpp:75 — readerWriters 参与缓存键比较。
  • src/vsg/utils/SharedObjects.cpp:240 — suitableForSharing 被置 false。
  • include/vsg/nodes/LOD.h:40 — Child 的 minimumScreenHeightRatio 默认为 0.0。

io//nodes/ 主场四文件:

  • include/vsg/io/DatabasePager.h:31-49 — CulledPagedLODs 两个 vector,reserve(512)/reserve(8),clear() 不缩容。
  • include/vsg/io/DatabasePager.h:51-90 — PagedLODContainer 三条侵入式 List 与 Element{previous,next,plod,list}。
  • include/vsg/io/DatabasePager.h:92-123 — DatabaseQueue 五个方法、一个 _compileResult、一个 _cv。
  • include/vsg/io/DatabasePager.h:127-177 — DatabasePager 真实公开接口四个方法,无 stopThread/cull/signal。
  • include/vsg/io/DatabasePager.h:53/135/143-156 — 10000/4/numActiveRequests/1500/60 五个默认与公开常量。
  • src/vsg/io/DatabasePager.cpp:23-24 — PRINT_CONTAINER/CHECK_CONTAINER 两个宏恒 0。
  • src/vsg/io/DatabasePager.cpp:30-88 — 构造 elements(1)、resize(new_size+1)、翻倍 resize()。
  • src/vsg/io/DatabasePager.cpp:110-230 — _move 两个分支,plod->index 与 const_cast。
  • src/vsg/io/DatabasePager.cpp:280-365 — check() 全套一致性校验,默认零调用。
  • src/vsg/io/DatabasePager.cpp:380-395 — 两个 add 重载,双参版先 notify_one() 后 _compileResult.add(cr)。
  • src/vsg/io/DatabasePager.cpp:397-451 — take_when_available 四分支、skipped 死变量、priority 扫描。
  • src/vsg/io/DatabasePager.cpp:453-484 — prune 强制复位状态、take_all 累加并 reset()。
  • src/vsg/io/DatabasePager.cpp:490-518 — 构造 create(4000)、析构 set(false)+join、assignInstrumentation 只存字段。
  • src/vsg/io/DatabasePager.cpp:520-634 — start() 读线程与删除线程两个 lambda。
  • src/vsg/io/DatabasePager.cpp:636-658 — request 单点自增、requestDiscarded 三行 pending 清理被注释。
  • src/vsg/io/DatabasePager.cpp:660-792 — updateSceneGraph 帧号、迁移、回收、合并四段。
  • include/vsg/nodes/PagedLOD.h:35-111 — 两个 Child、六个原子量、八态枚举、pending、index。
  • src/vsg/nodes/PagedLOD.cpp:22-31/37-55/57-93 — 拷贝不复制 options、compare 四组字段、read/write 三方不对称。

遍历与节点:

  • src/vsg/app/RecordTraversal.cpp:103-109 — setDatabasePager 把 culledPagedLODs.get() 交给遍历器。
  • src/vsg/app/RecordTraversal.cpp:153-178 — apply(const LOD&) 的 lodDistance、LODScale、无判空 accept。
  • src/vsg/app/RecordTraversal.cpp:180-260 — apply(const PagedLOD&) 六分支、priority = sphere.r / cutoff。
  • src/vsg/app/RecordTraversal.cpp:269-289 — apply(const CullGroup&)/apply(const CullNode&) 的 intersect 路径。
  • include/vsg/nodes/LOD.h:44-63 — LOD 的 vector 孩子(minimumScreenHeightRatio、dsphere bound)与无判空 t_traverse。
  • include/vsg/nodes/CullNode.h:21-47 — 注释明写「无内部检查」,三个 traverse 直接 child->accept。
  • include/vsg/app/RecordTraversal.h:111-181 — frameStamp、databasePager、culledPagedLODs 三成员。

编译与挂接:

  • src/vsg/app/CompileManager.cpp:28-58 — reset/add,:50 的 break 截断 views 合并。
  • src/vsg/app/CompileManager.cpp:60-83 — requiresViewerUpdate 三条判据。
  • src/vsg/app/CompileManager.cpp:95-124 — ResourceScavenger::scavenge 只降不升改写 targetMax...。
  • src/vsg/app/CompileManager.cpp:257/392/413 — compile/compileTask/context->transferTask 落点。
  • include/vsg/app/CompileManager.h:27-41/44-53/56-116 — CompileResult/ResourceScavenger/CompileManager 接口与 compile 不抛异常契约。
  • src/vsg/app/Viewer.cpp:278-417 — Viewer::compile 的分页装配、start(hints->numDatabasePagerReadThreads)。
  • src/vsg/app/Viewer.cpp:793-818 — Viewer::update 硬编码 updateSceneGraph 循环,pager 不在 updateOperations。
  • include/vsg/app/UpdateOperations.h:24-63 — enum RunBehavior 的 ONE_TIME/ALL_FRAMES 与 run(),全库零 addUpdateOperation 调用。
  • include/vsg/state/ResourceHints.h:63-88 — numDatabasePagerReadThreads=4、containsPagedLOD、allocatedMemoryLimit=1.0。
  • include/vsg/app/TransferTask.h:28-50 — TransferTask 的 transferData/containsDataToTransfer 接口,分页子图复用同一条上传链。

同步原语:

  • include/vsg/threading/DeleteQueue.h:30-40/45-114 — ObjectToDelete、retainForFrameCount=3、四个 add/prune 入口。
  • src/vsg/threading/DeleteQueue.cpp:32-42/44-84/86-121 — advance 空指针、wait_then_clear 的 numObjectsToDelete > 0 门槛。
  • include/vsg/threading/Latch.h:51-62/69-82 — count_down() 的 <= 1 与 wait() 无谓词循环。
  • include/vsg/threading/ActivityStatus.h:24-38 — set/active/cancel,set 用 exchange。
  • include/vsg/threading/atomics.h:29-34/46-50 — exchange_if_greater 与 compare_exchange 的 CAS 语义。

IO、缓存与 tile:

  • src/vsg/io/read.cpp:27-120 — vsg::read 插件与内置分派互斥、sharedObjects 缓存路径。
  • src/vsg/io/read.cpp:122-191 — 局部 ReadOperation、Latch::create(filenames.size())、:150 的 count_down()。
  • src/vsg/io/Options.cpp:68-84/86-156 — compare 九字段、read/write 序列化 sharedObjects 与 operationThreads。
  • include/vsg/io/Options.h:56-115 — sharedObjects、readerWriters、operationThreads 等字段全集。
  • include/vsg/io/ReaderWriter.h:22-31/64-74 — ReadError 是 Object 子类、六个虚函数空默认。
  • include/vsg/utils/SharedObjects.h:86-100/176-201 — LoadedObject 键、share(..., Func) 锁外 init。
  • src/vsg/utils/SharedObjects.cpp:201-207/218-227/238-241 — 构造清 sharedObjects、compare 键、apply(const PagedLOD&) 置不可共享。
  • include/vsg/core/compare.h:23-27 — compare_pointer 深比较语义。
  • src/vsg/io/tile.cpp:118-143/209-214/384-389 — .tile 扩展名判定、生成 PagedLOD 并回填 options。
  • src/vsg/nodes/TileDatabase.cpp:188-203 — tileReader 插入 readerWriters 头部、vsg::read("root.tile", ...)、第二处 cast<ReadError>()。
  • cmake/cppcheck-suppression-list.txt:98 — 指向已删除 include/vsg/io/ObjectCache.h 的残留抑制项。

可复现验证

# 期望:四行分别为 180 / 792 / 114 / 93
wc -l include/vsg/io/DatabasePager.h src/vsg/io/DatabasePager.cpp include/vsg/nodes/PagedLOD.h src/vsg/nodes/PagedLOD.cpp
# 期望:前七个计数全为 0,signal 为 1(且只落在 :404 的注释里)
for kw in ReadOperation CompileOperation requiresUpdate "void cull" startThread stopThread "void update(" signal; do printf "%s=%s\n" "$kw" "$(grep -c "$kw" include/vsg/io/DatabasePager.h src/vsg/io/DatabasePager.cpp | awk -F: '{s+=$2} END{print s}')"; done
# 期望:源码目录零命中,cppcheck 抑制项恰好 1 行
printf "src命中="; grep -rn "ObjectCache" include/ src/ | wc -l
printf "抑制项="; grep -n "ObjectCache" cmake/cppcheck-suppression-list.txt
# 期望:1500 / 60 / = 4 / 10000 / create(4000) 各命中其唯一位置
grep -n "targetMaxNumPagedLODWithHighResSubgraphs = 1500\|delayBeforeNextLoadAttempt = 60\|numReadThreads = 4" include/vsg/io/DatabasePager.h
grep -n "maxNumPagedLOD = 10000" include/vsg/io/DatabasePager.h
grep -n "create(4000)" src/vsg/io/DatabasePager.cpp
grep -n "numDatabasePagerReadThreads = 4" include/vsg/state/ResourceHints.h
# 期望:命中 CompileManager.cpp:50 的 break,下一行是 views[src_view]
sed -n '48,55p' src/vsg/app/CompileManager.cpp
# 期望:三个 CompileResult::add 调用点 394 / 481 / 401 都在
grep -n "_compileResult.add\|cr.add(_compileResult)\|result.add(compileManager" src/vsg/io/DatabasePager.cpp src/vsg/app/Viewer.cpp
# 期望:四个装配点行号恰为 498 / 623 / 665 / 791,Deleting 在源码零使用
grep -n "DeleteQueue::create\|wait_then_clear()\|deleteQueue->advance\|add_prune(deleteList" src/vsg/io/DatabasePager.cpp
printf "Deleting使用="; grep -rn "Deleting" include/ src/ | grep -v "PagedLOD.h:104" | wc -l
# 期望:numActiveRequests 一处自增、三处扣减
grep -n "numActiveRequests" src/vsg/io/DatabasePager.cpp src/vsg/app/CompileManager.cpp
# 期望:六处无符号帧号减法全部列出,frameCount 置 0 的防御在 :664
grep -n "frameCount - .*frameHighResLastUsed\|frameStamp ? frameStamp->frameCount : 0" include/vsg/nodes/PagedLOD.h src/vsg/io/DatabasePager.cpp src/vsg/app/RecordTraversal.cpp
# 期望::746 的 options 解引用无判空,PagedLOD 拷贝构造不复制 options
grep -n "plod->options->sharedObjects" src/vsg/io/DatabasePager.cpp
sed -n '22,31p' src/vsg/nodes/PagedLOD.cpp
# 期望:read.cpp 内置分派不含 .tile;.tile 只由 tile.cpp:123 判定;vsgXchange 本仓库仅注释提及
grep -n '\.vsga\|\.vsgt\|\.vsgb' src/vsg/io/read.cpp
grep -n 'extension != ".tile"' src/vsg/io/tile.cpp
grep -rn "vsgXchange" include/ src/
# 期望:输出本机编译下的实际字节数(以本机 SDK/ABI 为准,本文档不预填数字)
cat > /tmp/sizeof_element.cpp <<'EOF'
#include <cstdio>
#include <cstdint>
#include <string>
struct Element { uint32_t previous=0, next=0; void* plod=nullptr; void* list=nullptr; };
int main(){ printf("Element=%zu ref_ptr_like=%zu Element4001=%zu\n", sizeof(Element), sizeof(void*), sizeof(Element)*4001); }
EOF
g++ -std=c++17 /tmp/sizeof_element.cpp -o /tmp/sizeof_element && /tmp/sizeof_element

陷阱表与批判性结论

陷阱完整位置触发条件后果规避
break 截断 views 合并src/vsg/app/CompileManager.cpp:50一帧合并多个结果且某空 view 排在前requiresViewerUpdate 漏判、bin 补齐缺失、帧期越界改 continue
pending 清理被注释src/vsg/io/DatabasePager.cpp:648-653编译失败或抛异常子图残留、重试复用未编译对象、读写无锁恢复清理并统一加锁
numActiveRequests 无符号下溢src/vsg/io/DatabasePager.cpp:657/667/784CAS 失败仍按 nodes.size() 扣减计数失真、scavenge 比较恒假改有符号或按成功数扣
options 空指针解引用src/vsg/io/DatabasePager.cpp:746手写/clone 的 PagedLOD 进入回收回收路径崩溃先判 if (plod->options)
frameStamp 判空不对称src/vsg/io/DatabasePager.cpp:664-665传入空 FrameStampadvance 空指针、帧号归零触发下溢两行统一判空
无符号帧号减法下溢include/vsg/nodes/PagedLOD.h:57、src/vsg/app/RecordTraversal.cpp:191/210/240帧号回退或被置 0全部节点判为过期、请求被丢弃带符号差值并判负
priority 除零得 +infsrc/vsg/app/RecordTraversal.cpp:223minimumScreenHeightRatio == 0.0优先级永久钉死、队列退化为插入序判 cutoff > 0.0
Deleting/DeleteRequest 死状态include/vsg/nodes/PagedLOD.h:103-104、src/vsg/io/DatabasePager.cpp:733/738任何回收状态机八态仅四态有效删除或接上消费方
ReadError 降级成日志src/vsg/io/DatabasePager.cpp:598-603读失败或 CAS 竞争失败上层不知失败、竞争失败误报读失败分两类分支并回传错误
插件与内置分派互斥src/vsg/io/read.cpp:32-40(先查 options->readerWriters)options 挂了不认该文件后缀的插件.vsgb 子图返回空、请求丢弃插件链内置 VSG 兜底
LoadedObject 缓存键漏字段src/vsg/utils/SharedObjects.cpp:218-227、src/vsg/io/Options.cpp:68-84同 filename 不同 options命中错误缓存对象compare 补齐字段
PagedLOD 使缓存整体失效src/vsg/utils/SharedObjects.cpp:238-241(suitableForSharing 被置 false)子图含任一 PagedLOD每个 tile 重复读盘改用弱引用键或专用缓存
share 锁外 init 重复加载include/vsg/utils/SharedObjects.h:188-198两线程同时未命中重复读盘、返回不同实例检查 insert 返回值并替换
wait_then_clear 跳过 prunesrc/vsg/threading/DeleteQueue.cpp:72-79只有 SharedObjects 要 pruneprune 请求永久丢失去掉 numObjectsToDelete > 0 门槛
Latch::count_down 异常漏调src/vsg/io/read.cpp:149-150vsg::read 抛异常latch->wait() 永久阻塞try/catch 后也 count_down
targetMax 跨线程无同步src/vsg/app/CompileManager.cpp:111、src/vsg/io/DatabasePager.cpp:721显存紧张触发 scavenge数据竞争、预算只降不升改原子并加恢复路径
check() 默认零调用src/vsg/io/DatabasePager.cpp:23-24/359-365链表被边遍历边改一致性错误无告警默认开启 CHECK_CONTAINER
maxNumPagedLOD 默认值失效include/vsg/io/DatabasePager.h:53、src/vsg/io/DatabasePager.cpp:500任何 DatabasePager 构造10000 从未生效、容量与阈值两套量纲统一常量
CAS 失败被误报成帧过期src/vsg/io/DatabasePager.cpp:542/544trim/prune 先改写了 requestStatus日志误导、真实竞争被掩盖拆两个分支各打一条日志
requestCount 三处各自复位src/vsg/io/DatabasePager.cpp:650/667失败、prune 与回收交错同批遍历可能重复发请求统一在 requestDiscarded 复位

三条批判性结论

第一,分页子系统把「失败」拆成四条互不通信的路径,却没有一条能把失败作为一等公民传回调用链。 vsg::read 返回 ReadError 对象(include/vsg/io/ReaderWriter.h:24-30)却只在 src/vsg/io/DatabasePager.cpp:598 被 cast<ReadError>() 打一条 warn;compileManager->compile 返回假(:584)、抛异常(:590)、状态 CAS 竞争失败(:597)三种情况与真正的读失败共用同一个 requestDiscarded(:646-658),而后者只复位 requestCount/requestStatus/frameNextLoadAttempt、扣一次 numActiveRequests,三行 pending 清理被注释,不写任何错误字段、不通知 CompileManager、不通知 Viewer。Viewer::update:808 只看 cr.requiresViewerUpdate(this),而 cr 来自 _toMergeQueue->take_all 的成功结果集合,失败请求根本不进这条聚合链。后果不是「少打一条日志」,而是系统在「文件不存在」「插件不认后缀」「显存不足编译失败」「两个线程抢同一个状态」四种截然不同的情况下表现完全一致:静默回到 NoRequest,等 60 帧后再试一次,且已读进内存的子图因为 pending 未清而继续占着引用。第十八章批判结论一讲的是序列化层「四种失败表达互不相通」,分页层把这个问题又复制了一遍,还额外叠加了「失败对象被 cast<Node>() 抹成空指针」这一层信息丢失。

第二,缓存机制与分页节点在结构上是互斥的,于是 SharedObjects 在分页场景下既可能返回错误对象,又几乎不会命中正确对象。 缓存键是 LoadedObject::compare(src/vsg/utils/SharedObjects.cpp:218-227)的 filename 加 compare_pointer(options, ...),后者落到 Options::compare(src/vsg/io/Options.cpp:68-84)只比九个字段,漏掉 sharedObjects、operationThreads、inheritedState 等八个字段,而 LoadedObject 构造(:206)又把 options->sharedObjects 清空;于是「同一文件、两套 options」在九个字段相同时会命中同一份缓存,第十八章预告第六问成立。可另一面,SuitableForSharing::apply(const PagedLOD&)(:238-241)直接把 suitableForSharing 置假,头文件注释(SharedObjects.h:103-109)给出的理由是 PagedLOD 含 options 成员、放进缓存会形成循环引用;share(ref_ptr<T>&, Func)(SharedObjects.h:196)因此在子图含任一 PagedLOD 时整份不插入缓存。分页子图必然含下一级 PagedLOD(src/vsg/io/tile.cpp:209/384),结果就是每个 tile 都重新读盘。再叠加 :188 释放锁后才 init、:198 不检查 set::insert 返回值的竞态,两个线程同时未命中会各自读盘、各自持有不同实例。为解循环引用而写的守卫,把缓存的正确性前提与命中率一起牺牲了,这两件事本可以用「弱引用缓存键 + 显式排除 options」分开解决。

第三,所谓「帧预算」在 1.1.16 里不是硬约束,而是一组没有共同时钟、可各自失效、且失效时静默的启发式计数。 numActiveRequests(include/vsg/io/DatabasePager.h:143)是无符号原子量,只有 request:642 一处自增,却在 :657、:667、:784 三处扣减,其中 :784 按 nodes.size() 无条件扣而 merge 循环只处理 CAS 成功者,计数可下溢到接近 2^32;frameCount(:144)在 updateSceneGraph:664 可能被置 0,六处 uint64_t 帧号减法(PagedLOD.h:57、RecordTraversal.cpp:191/210/240、DatabasePager.cpp:540/773)随即全部下溢,把所有节点判为过期;targetMaxNumPagedLODWithHighResSubgraphs(:149)是普通成员,被 ResourceScavenger::scavenge:111 在编译线程只降不升地改写,又被 :721 在主线程读,跨线程无同步;容器容量 create(4000)(:500)与阈值 1500 分属两套量纲,:721 的超额判定只从 inactiveList 摘,不保证单帧回落到阈值以下,inactiveList 为空时 :728 循环一次都不进。四组计数没有任何一个共享变量或统一时钟,第十六章 16.9.3 判定「三个 3 之间没有引用关系」在这里扩展为「五个预算数字之间没有引用关系」。后果是:显存紧张、帧号回退、多线程竞争任一条件出现,分页不会报错、不会降级的日志之外留下任何痕迹,只是 quietly 停止合并或把刚加载的高精层全部 trim 掉。要让预算成为真约束,至少需要把计数改成有符号、把帧号差改成带符号、给 targetMax 加原子与恢复路径、并在 updateSceneGraph 里强制单帧回收到位。

第四,两处 const_cast 与三种 pending 同步口径把「遍历期只读」的契约撕开,而锁只覆盖其中一条写路径。 RecordTraversal::apply(const PagedLOD&) 在 src/vsg/app/RecordTraversal.cpp:230 把 const 引用 cast 成 ref_ptr<PagedLOD> 交给跨线程队列,PagedLODContainer::_move 在 src/vsg/io/DatabasePager.cpp:161 把 const PagedLOD* cast 后存进 Element::plod;两处都靠父节点的强引用兜底,而非接口设计正确。更关键的是 pending(include/vsg/nodes/PagedLOD.h:110 的普通 ref_ptr<Node>)在 src/vsg/io/DatabasePager.cpp:569 写入时持锁,在 :740 入 deleteList 时不持锁,在 :778 移入 children[0].node 时只在 LOCAL_MUTEX 下持锁,三种口径并存。三条都可 grep -n 复核:cast 两处、写入三处、锁覆盖一处。后果是「编译成功即挂接」依赖三个线程对同一裸指针的时序默契,任一路径改了加锁习惯就可能重复删除或提前挂接。

下章预告

本章结束。下一章精确对齐 docs/series/README.md:80 的第 20 章标题「文本:Font、Text、TextGroup 与两种排版技术」,核心模块 text/,要回答本章留下的五个具体问题:

  • 第十九章 19.13 的 CompileManager::compile 把分页子图编译结果经 CompileResult::add(src/vsg/app/CompileManager.cpp:37-58)汇总;文本节点的 glyph 图集同样要在 text/ 里编译,它的 ResourceRequirements::Views(include/vsg/app/CompileManager.h:33)是否重演本章 19.12 的 break 截断,令多 View 下的字形 bin 漏补齐?
  • Font(include/vsg/text/Font.h:38)持有 ref_ptr<SharedObjects> sharedObjects,与本章 19.15.2 的 PagedLOD::options->sharedObjects(src/vsg/io/DatabasePager.cpp:746)同名同类型;字体图集的共享走的是 SharedObjects::share(ref_ptr<T>&, Func)(include/vsg/utils/SharedObjects.h:176-201)同一套锁外 init 模板,还是另建缓存?SuitableForSharing::apply(const PagedLOD&) 那类循环引用守卫在 Font 上是否也存在?
  • 第十七章 17.7 的「插件与内置分派互斥」(src/vsg/io/read.cpp:32-40)在字体文件上如何体现:.ttf/.otf 没有内置 ReaderWriter,是否必须靠 vsgXchange 之类的外部插件注册进 Options::readerWriters 才能 vsg::read,本仓库 text/ 里有没有对应的 ReadError(include/vsg/io/ReaderWriter.h:24-30)消费点?
  • 第十四章 Viewer::update:814 的 updateOperations->run()(include/vsg/app/UpdateOperations.h:55)与本章 19.14 证实的「pager 硬编码挂接」相反;TextGroup 的动态排版若需要每帧更新,是走 addUpdateOperation(include/vsg/app/Viewer.h:85-87,本章实测零调用点)还是走 AnimationManager::run(src/vsg/app/Viewer.cpp:817)?两种排版技术(CPU 排版与 GPU 排版)的分界是否正好落在「谁负责触发更新」上?
  • 第六章/第十二章的 ResourceHints(include/vsg/state/ResourceHints.h:63-88)里 numDescriptorSets、maxSlots 由 CollectResourceRequirements 收集;文本的字形图集是 DescriptorImage(本章 tile.cpp 的 _imageFallback 同族),它的 minimumStagingBufferSize = 16 * 1024 * 1024(:70)与 TransferTask(src/vsg/app/TransferTask.cpp)上传链,和分页 tile 的图层数据上传是否共用同一个 Context::transferTask(src/vsg/app/CompileManager.cpp:413)?

本章把 io/、nodes/、app/、threading/ 里 33 个文件、8,252 行拆到底,得到的结论是:分页不是「多线程读文件」这么简单,而是「可见性 → 请求 → 状态机 → 编译结果聚合 → 预算回收 → 延迟删除」六段各有自己的计数与失败表达、却没有一条统一错误通道与统一时钟的流水线。第十八章的隐式前提在单文件加载时只是「字段顺序要对齐」,到分页场景被放大成「状态、计数、帧号、缓存键四套分布式状态必须同时自洽」。下一章把镜头从「成千上万个文件」移到「一个字形如何变成屏幕上的像素」,看 text/ 怎样在同样的编译与共享约束下回答 CPU 与 GPU 排版的分界。