《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.h | 180 | CulledPagedLODs、PagedLODContainer、DatabaseQueue、DatabasePager 四个类的字段与公开接口全表 |
src/vsg/io/DatabasePager.cpp | 792 | 容器侵入式链表、两个队列、读线程、删除线程、request、requestDiscarded、updateSceneGraph 全量实现 |
include/vsg/nodes/PagedLOD.h | 114 | children、filename、priority、requestStatus、八态枚举、pending、index |
src/vsg/nodes/PagedLOD.cpp | 93 | 拷贝构造、compare、read、write 四处字段不对称 |
include/vsg/nodes/LOD.h | 73 | 非分页 LOD 的 Children、t_traverse 与「必须始终有合法子节点」契约 |
src/vsg/nodes/LOD.cpp | 87 | LOD::compare 的长度保护、read/write 的 children 计数 |
include/vsg/nodes/CullNode.h | 50 | 单孩子视锥剔除节点、注释里明写「无内部检查」 |
include/vsg/app/RecordTraversal.h | 191 | frameStamp、databasePager、culledPagedLODs 三个成员与 setDatabasePager |
src/vsg/app/RecordTraversal.cpp | 704 | apply(const LOD&)、apply(const PagedLOD&)、apply(const CullNode&) 三条遍历路径 |
include/vsg/app/CompileManager.h | 119 | CompileResult、ResourceScavenger、CompileManager 的接口与 compile 契约 |
src/vsg/app/CompileManager.cpp | 447 | CompileResult::add/reset/requiresViewerUpdate、ResourceScavenger::scavenge、compile |
include/vsg/app/Viewer.h | 174 | updateOperations、animationManager、compileManager、status、_frameStamp 字段 |
src/vsg/app/Viewer.cpp | 892 | Viewer::compile 的分页装配、Viewer::update 的硬编码挂接、stopThreading |
include/vsg/app/UpdateOperations.h | 66 | ONE_TIME/ALL_FRAMES、run(),用于证明 pager 不走这条路 |
include/vsg/threading/DeleteQueue.h | 136 | ObjectToDelete、retainForFrameCount=3、四个 add/prune 入口 |
src/vsg/threading/DeleteQueue.cpp | 121 | advance、wait_then_clear、clear 三条删除路径 |
include/vsg/threading/Latch.h | 95 | count_down() 的 <= 1 判据、wait()、release() |
include/vsg/threading/ActivityStatus.h | 42 | set/active/cancel 三个原子位操作 |
include/vsg/threading/atomics.h | 52 | compare_exchange、exchange_if_greater 两个模板的实现 |
include/vsg/io/Options.h | 147 | sharedObjects、readerWriters、paths、extensionHint 等字段全集 |
src/vsg/io/Options.cpp | 191 | Options::compare 的九个字段、read/write 的插件表往返 |
src/vsg/io/read.cpp | 223 | vsg::read 单文件分派、sharedObjects 缓存路径、ReadOperation 与 Latch |
include/vsg/io/ReaderWriter.h | 134 | ReadError 定义、ReaderWriter 六个虚函数的空默认实现 |
include/vsg/utils/SharedObjects.h | 213 | LoadedObject、SuitableForSharing、share(ref_ptr<T>&, Func) 模板 |
src/vsg/utils/SharedObjects.cpp | 241 | suitable、prune、LoadedObject::compare、apply(const PagedLOD&) |
include/vsg/core/compare.h | 115 | compare_pointer 的深比较语义,决定缓存键是否按内容判定 |
include/vsg/io/tile.h | 80 | vsg::tile 是一个 ReaderWriter,不是扩展名 |
src/vsg/io/tile.cpp | 927 | .tile 虚拟文件名、read_root/read_subtile、生成 PagedLOD 并回填 options |
include/vsg/nodes/TileDatabase.h | 126 | TileDatabaseSettings、TileDatabase、readDatabase |
src/vsg/nodes/TileDatabase.cpp | 324 | readDatabase 把 tileReader 插到 readerWriters 头部、第二处 cast<ReadError>() |
include/vsg/state/ResourceHints.h | 99 | numDatabasePagerReadThreads=4、containsPagedLOD、allocatedMemoryLimit |
include/vsg/app/TransferTask.h | 124 | 编译期传输任务的接口 |
src/vsg/app/TransferTask.cpp | 880 | 分页子图编译后的数据上传落点 |
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 答案骨架
先把结论列在这里,后面逐条用源码展开,读者可以带着结论去核对:
| # | 结论 | 主要证据 | 性质 |
|---|---|---|---|
| 1 | 1.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 + LoadedObject | src/vsg/io/read.cpp:76–115、include/vsg/utils/SharedObjects.h:86–100 | 命名边界 / 硬缺陷(抑制项失效) |
| 3 | CompileResult::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 | 硬缺陷 |
| 4 | requestDiscarded 里 plod->pending = nullptr 的三行清理全部被注释,失败/异常/过期路径残留已加载子图,与 trim 分支的 plod->pending = {} 不对称 | src/vsg/io/DatabasePager.cpp:646–658、:740–741 | 硬缺陷 |
| 5 | numActiveRequests 是无符号 atomic_uint,在 :642 自增,却在 :657、:667、:784 三处扣减,其中 :784 无条件减 nodes.size() 而 merge 循环只处理 CAS 成功者,计数可下溢到接近 2^32 | include/vsg/io/DatabasePager.h:143、src/vsg/io/DatabasePager.cpp:642/657/667/784 | 硬缺陷 |
| 6 | updateSceneGraph 的 :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 | 硬缺陷 |
| 7 | Deleting = 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 | 硬缺陷(死状态)/ 设计取舍 |
| 8 | maxNumPagedLOD = 10000 只是 PagedLODContainer 构造的默认参数,实际 DatabasePager 用 create(4000);帧预算用的 targetMaxNumPagedLODWithHighResSubgraphs = 1500 是另一套量纲,容器上限与预算上限互不相干 | include/vsg/io/DatabasePager.h:53/149、src/vsg/io/DatabasePager.cpp:500/721 | 设计取舍 / 静默降级 |
| 9 | apply(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 | 硬缺陷 |
| 10 | frameCount、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 里所有状态迁移列出来,实际发生的只有六条:
:638NoRequest → ReadRequest(request()):542ReadRequest → Reading(读线程compare_exchange):565Reading → Compiling(读线程compare_exchange):577→ MergeRequest(exchange,编译成功):733NoRequest → DeleteRequest(trim 的 CAS):771MergeRequest → 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 五个数字的归属表
| 数字 | 完整位置 | 类型 | 实际用途 |
|---|---|---|---|
10000 | include/vsg/io/DatabasePager.h:53 | 构造默认参数 | PagedLODContainer 不传参时的初始容量,DatabasePager 从未用这个默认值 |
4000 | src/vsg/io/DatabasePager.cpp:500 | 实际实参 | DatabasePager 构造的容器上限,resize(std::max(4000, 10u)) 得 4001 个元素 |
1500 | include/vsg/io/DatabasePager.h:149 | 公开可调成员 | updateSceneGraph:721 的回收阈值,单位「带高精子图的 PagedLOD 个数」 |
60 | include/vsg/io/DatabasePager.h:152 | 公开可调成员 | requestDiscarded:655 的 frameNextLoadAttempt 增量,单位「帧」 |
3 | include/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 四个装配点复验
| 行号 | 代码 | 角色 |
|---|---|---|
:498 | deleteQueue = DeleteQueue::create(status) | 装配:构造时创建删除队列并共享 status |
:623 | databasePager.deleteQueue->wait_then_clear() | 使用:删除线程循环里阻塞等待并执行删除 |
:665 | deleteQueue->advance(frameStamp) | 使用:主线程每帧灌入帧号、按到期条件 notify_one() |
:791 | deleteQueue->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 全部依赖这一语义。八步账本里任何一步的计数或状态失真,都能回溯到这两个函数之一:前者管「是否过期」,后者管「能否迁移」。
| 步 | 完整位置 | 动作 | 状态/计数 |
|---|---|---|---|
| 1 | src/vsg/app/RecordTraversal.cpp:209/226/230 | 写 frameHighResLastUsed、requestCount++、首次 request() | NoRequest → ReadRequest |
| 2 | src/vsg/io/DatabasePager.cpp:638-643 | CAS 成功入 _requestQueue、numActiveRequests++ | ReadRequest |
| 3 | src/vsg/io/DatabasePager.cpp:535/542 | 读线程取出、frameDelta 判定、CAS | ReadRequest → Reading |
| 4 | src/vsg/io/DatabasePager.cpp:557/565 | vsg::read、cast<Node>()、CAS | Reading → Compiling |
| 5 | src/vsg/io/DatabasePager.cpp:575/577/582 | compileManager->compile、置 MergeRequest、入 _toMergeQueue | → MergeRequest |
| 6 | src/vsg/io/DatabasePager.cpp:669/771/778/781 | take_all、CAS、挂 children[0].node、清状态 | → Merging → NoRequest |
| 7 | src/vsg/io/DatabasePager.cpp:679-698/728-756 | 冷却进 inactiveList、预算超限时 trim | → DeleteRequest → NoRequest |
| 8 | src/vsg/io/DatabasePager.cpp:791 | deleteQueue->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/784 | CAS 失败仍按 nodes.size() 扣减 | 计数失真、scavenge 比较恒假 | 改有符号或按成功数扣 |
options 空指针解引用 | src/vsg/io/DatabasePager.cpp:746 | 手写/clone 的 PagedLOD 进入回收 | 回收路径崩溃 | 先判 if (plod->options) |
frameStamp 判空不对称 | src/vsg/io/DatabasePager.cpp:664-665 | 传入空 FrameStamp | advance 空指针、帧号归零触发下溢 | 两行统一判空 |
| 无符号帧号减法下溢 | include/vsg/nodes/PagedLOD.h:57、src/vsg/app/RecordTraversal.cpp:191/210/240 | 帧号回退或被置 0 | 全部节点判为过期、请求被丢弃 | 带符号差值并判负 |
priority 除零得 +inf | src/vsg/app/RecordTraversal.cpp:223 | minimumScreenHeightRatio == 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 跳过 prune | src/vsg/threading/DeleteQueue.cpp:72-79 | 只有 SharedObjects 要 prune | prune 请求永久丢失 | 去掉 numObjectsToDelete > 0 门槛 |
Latch::count_down 异常漏调 | src/vsg/io/read.cpp:149-150 | vsg::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/544 | trim/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 排版的分界。