10.1 后台资源队列
资源加载有两条原则:耗时工作不应卡住渲染帧,但「真正调用渲染 API 把缓冲填上」的动作又必须留在主线程。ResourceBackgroundQueue 把这两条原则封装成一组以 std::future<void> 返回的接口——initialiseResourceGroup、prepareResourceGroup、loadResourceGroup、load、unload。它自己不管理线程:所有并行都收敛到 WorkQueue,类本身单线程(OgreResourceBackgroundQueue.cpp 开头注释:“no locks are required here anymore because all of the parallelisation is now contained in WorkQueue”)。
本章与站内既有内容的分工
3.1/3.2 讲过自定义资源类型与存档的加载路径;本节看的是资源组级编排:如何把 ResourceGroupManager 的工作丢到后台,并让主线程安全地接收完成事件。lab 复现 packaged_task 提交与两个 OGRE_THREAD_SUPPORT 分支。
packaged_task + future:把工作包提交给 WorkQueue
每个接口的骨架完全一致:把真实工作放进 std::make_shared<std::packaged_task<void()>>,通过 getWorkQueue()->addTask([task]() { (*task)(); }) 提交,然后立刻把 task->get_future() 返回给调用方。共享指针保证队列里的 lambda 在任务执行前一直持有 packaged_task:
// OgreMain/src/OgreResourceBackgroundQueue.cpp:ResourceBackgroundQueue::initialiseResourceGroup(v14.6.3 源码摘录,已删减)
std::future<void> ResourceBackgroundQueue::initialiseResourceGroup(const String& name)
{
auto task = std::make_shared<std::packaged_task<void()>>(
[name]() { ResourceGroupManager::getSingleton().initialiseResourceGroup(name); });
Root::getSingleton().getWorkQueue()->addTask([task]() { (*task)(); });
return task->get_future();
}
prepare 在后台线程调 res->prepare(true),但把 _firePreparingComplete() 排进主线程队列——因为通知监听器(并可能触发 onPrepareResources)属于主线程职责:
// OgreMain/src/OgreResourceBackgroundQueue.cpp:ResourceBackgroundQueue::prepare(v14.6.3 源码摘录,已删减)
std::future<void> ResourceBackgroundQueue::prepare(const ResourcePtr& res)
{
auto task = std::make_shared<std::packaged_task<void()>>(
[res]()
{
res->prepare(true);
Root::getSingleton().getWorkQueue()->addMainThreadTask([res]() { res->_firePreparingComplete(); });
});
Root::getSingleton().getWorkQueue()->addTask([task]() { (*task)(); });
return task->get_future();
}
lab 里 bgLoadThreaded 与 bgLoadCompat 分别对应下面两个分支;WorkQueueRepro 的 addTask 在 OGRE_THREAD_SUPPORT==0 语义下同步执行(对应 OgreWorkQueue.cpp 的 task(); // no threading, just run it),addMainThreadTask 进主线程 deque。
load 的两个分支:线程支持决定谁 load
load 是接口里最微妙的一个,它按 OGRE_THREAD_SUPPORT 拆成两条路。编译期 OGRE_THREAD_SUPPORT == 1 表示后台线程允许调 load(true)(在后台完成 GPU 缓冲上传的准备工作),随后只需主线程补 _fireLoadingComplete():
// OgreMain/src/OgreResourceBackgroundQueue.cpp:ResourceBackgroundQueue::load(v14.6.3 源码摘录,已删减)
std::future<void> ResourceBackgroundQueue::load(const ResourcePtr& res)
{
auto task = std::make_shared<std::packaged_task<void()>>(
[res]()
{
#if OGRE_THREAD_SUPPORT == 1
res->load(true);
Root::getSingleton().getWorkQueue()->addMainThreadTask([res]() { res->_fireLoadingComplete(); });
#else
res->prepare(true);
Root::getSingleton().getWorkQueue()->addMainThreadTask(
[res]()
{
res->load(true);
res->_fireLoadingComplete();
});
#endif
});
Root::getSingleton().getWorkQueue()->addTask([task]() { (*task)(); });
return task->get_future();
}
默认(非 ==1)的分支保守得多:后台只 prepare(true),把真正的 load(true) 和 _fireLoadingComplete() 一起塞进主线程队列——保证渲染 API 相关动作全部在主线程。loadResourceGroup 的分支同理,默认分支甚至整个组的 load 都留在主线程:
// OgreMain/src/OgreResourceBackgroundQueue.cpp:ResourceBackgroundQueue::loadResourceGroup(v14.6.3 源码摘录,已删减)
std::future<void> ResourceBackgroundQueue::loadResourceGroup(const String& name)
{
auto task = std::make_shared<std::packaged_task<void()>>([name]()
{
# if OGRE_THREAD_SUPPORT == 1
ResourceGroupManager::getSingleton().loadResourceGroup(name);
# else
ResourceGroupManager::getSingleton().prepareResourceGroup(name);
Root::getSingleton().getWorkQueue()->addMainThreadTask(
[name]() { ResourceGroupManager::getSingleton().loadResourceGroup(name); });
# endif
});
Root::getSingleton().getWorkQueue()->addTask([task]() { (*task)(); });
return task->get_future();
}
lab 用两个独立资源对象分别验证两条路:res1 走「后台 load + 主线程补完成事件」,res2 走「后台 prepare + 主线程 load 与完成事件」,并断言中间态的 pendingMain() 计数与 processMainThreadTasks() 之后的最终状态。
后台 future 与资源可用时刻
sequenceDiagram
participant A as 调用方
participant W as WorkQueue worker
participant M as 主线程队列
participant R as Resource
A->>W: 提交 packaged_task
Note over A,W: 调用方立即获得 future
alt OGRE_THREAD_SUPPORT 等于 1
W->>R: load(true)
W->>M: 投递完成通知
else 默认模式
W->>R: prepare(true)
W->>M: 投递 load(true) 和完成通知
end
W-->>A: 后台任务结束,future 就绪
Note over A,M: 默认模式下,主线程可能尚未 load
M->>R: 默认模式执行 load(true)
M->>R: 派发 _fireLoadingComplete
验证 future 与主线程提交
用磁盘网格检验默认线程模式。调用方先等 future,特意延后主线程队列处理。worker 已将文件缓冲进内存,Mesh 处于 PREPARED,尚未 decode,也没有收到加载完成通知。随后泵送主线程任务,load(true) 解析网格,完成通知在主线程触发。把缺失文件作为对照,prepare 抛出的异常由 packaged task 传给 future,程序观察到资源没有准备或加载成功。 后台加载源码
· 后台加载手册
这个 future 只观察其关联的后台任务。默认模式下,主线程回调阶段的失败沿任务泵处理路径传播。将这两处异常分别记录。关闭时 Root 停止工作队列并等待 worker 退出,随后释放场景和资源。原生样例先处理仍持有 Mesh 的任务,移除监听器并卸载资源,再用一条只写标志位的待处理回调验证关停本身没有泵送它。若把持有 Mesh 的回调留到队列析构,资源引用可能晚于渲染后端释放。 Root 关停源码 · 原生场景样例 。
源码定位
OgreMain/src/OgreResourceBackgroundQueue.cpp:ResourceBackgroundQueue::initialiseResourceGroup(50-56 行)OgreMain/src/OgreResourceBackgroundQueue.cpp:ResourceBackgroundQueue::prepare(90-100 行)OgreMain/src/OgreResourceBackgroundQueue.cpp:ResourceBackgroundQueue::load(102-122 行)OgreMain/src/OgreResourceBackgroundQueue.cpp:ResourceBackgroundQueue::loadResourceGroup(74-88 行)
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
WorkQueueRepro 复现 addTask 同步执行 + addMainThreadTask 入主线程队列;bgLoadThreaded/bgLoadCompat 复现两个分支;setAccept(false) 复现 setRequestsAccepted(false) 时新任务被静默丢弃。它与 src/10-1-background-resource-queue.cpp 逐字节一致:
// file: src/10-1-background-resource-queue.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/10-1-background-resource-queue.cpp -o bin/10-1-background-resource-queue && ./bin/10-1-background-resource-queue
//
// 复现 ResourceBackgroundQueue 的任务提交模式(OgreMain/src/
// OgreResourceBackgroundQueue.cpp 50-122 的 initialiseResourceGroup/load/
// loadResourceGroup):用 std::packaged_task 包装真实工作并通过
// WorkQueue::addTask 提交,调用方立即拿 future 收结果;load 的分支:
// OGRE_THREAD_SUPPORT==1 时后台直接 res->load(true),再把"加载完成事件"
// 排回主线程队列;否则后台只 prepare,load 与完成事件都放主线程队列。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <chrono>
#include <cstdint>
#include <deque>
#include <functional>
#include <future>
#include <memory>
#include <string>
#include <utility>
namespace ogre_repro {
// 对应 DefaultWorkQueueBase 的 addTask/addMainThreadTask/processMainThreadTasks
// 的"无线程"最小形态(OGRE_THREAD_SUPPORT==0 时 addTask 在调用线程直接跑)
class WorkQueueRepro {
public:
void addTask(std::function<void()> task) {
if (!mAccept)
return;
task(); // no threading, just run it(对应 OgreWorkQueue.cpp 113 行)
}
void addMainThreadTask(std::function<void()> task) {
if (!mAccept)
return;
mMain.push_back(std::move(task));
}
void processMainThreadTasks() {
while (!mMain.empty()) {
std::function<void()> t = std::move(mMain.front());
mMain.pop_front();
t();
}
}
size_t pendingMain() const { return mMain.size(); }
void setAccept(bool a) { mAccept = a; }
private:
std::deque<std::function<void()>> mMain;
bool mAccept = true;
};
// 对应一个可后台加载的 Resource 的轻量状态
struct ResourceRepro {
std::string name;
bool prepared = false;
bool loaded = false;
uint32_t prepareCalls = 0;
uint32_t loadCalls = 0;
uint32_t firePrepareCalls = 0;
uint32_t fireLoadCalls = 0;
void prepare(bool background) {
(void)background;
++prepareCalls;
prepared = true;
}
void load(bool background) {
(void)background;
++loadCalls;
loaded = true;
}
void firePreparingComplete() { ++firePrepareCalls; }
void fireLoadingComplete() { ++fireLoadCalls; }
};
// 对应 ResourceBackgroundQueue::load 的 OGRE_THREAD_SUPPORT==1 分支:
// 后台 load,主线程只负责完成事件
std::future<void> bgLoadThreaded(WorkQueueRepro& wq, ResourceRepro& res) {
auto task = std::make_shared<std::packaged_task<void()>>(
[&wq, &res]() {
res.load(true);
wq.addMainThreadTask([&res]() { res.fireLoadingComplete(); });
});
wq.addTask([task]() { (*task)(); });
return task->get_future();
}
// 对应 ResourceBackgroundQueue::load 的 OGRE_THREAD_SUPPORT==0 分支:
// 后台只 prepare,load 与完成事件都留给主线程
std::future<void> bgLoadCompat(WorkQueueRepro& wq, ResourceRepro& res) {
auto task = std::make_shared<std::packaged_task<void()>>(
[&wq, &res]() {
res.prepare(true);
wq.addMainThreadTask(
[&res]() {
res.load(true);
res.fireLoadingComplete();
});
});
wq.addTask([task]() { (*task)(); });
return task->get_future();
}
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
WorkQueueRepro wq;
ResourceRepro res1;
res1.name = "Terrain.pack";
ResourceRepro res2;
res2.name = "SkyBox.pack";
CHECK(!res1.prepared && !res1.loaded);
// OGRE_THREAD_SUPPORT==1 分支:后台立即 load,完成事件进主线程队列
std::future<void> f1 = bgLoadThreaded(wq, res1);
CHECK(res1.loaded); // 后台 load(true) 已同步执行
CHECK(!res1.prepared); // 该分支不 prepare
CHECK_EQ(wq.pendingMain(), 1u); // _fireLoadingComplete 已排队
CHECK(f1.valid());
CHECK(f1.wait_for(std::chrono::milliseconds(0)) == std::future_status::ready);
wq.processMainThreadTasks();
CHECK_EQ(wq.pendingMain(), 0u);
CHECK_EQ(res1.fireLoadCalls, 1u);
// 默认分支:后台 prepare,load 仍留在主线程队列
std::future<void> f2 = bgLoadCompat(wq, res2);
CHECK(res2.prepared);
CHECK_EQ(res2.prepareCalls, 1u);
CHECK(!res2.loaded); // load 尚未执行
CHECK_EQ(wq.pendingMain(), 1u);
CHECK(f2.valid());
wq.processMainThreadTasks();
CHECK(res2.loaded);
CHECK_EQ(res2.loadCalls, 1u); // 仅默认分支这次 load
CHECK_EQ(res2.fireLoadCalls, 1u);
// setRequestsAccepted(false):后续 addMainThreadTask 被静默丢弃
wq.setAccept(false);
wq.addMainThreadTask([&res1]() { res1.fireLoadCalls += 99; });
CHECK_EQ(wq.pendingMain(), 0u);
CHECK_EQ(res1.fireLoadCalls, 1u);
return lab::report("10.1 后台资源队列");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 18/18 通过。
future 就绪与资源可用
默认线程模式下,future 跟踪后台 packaged task。worker 准备资源并将 load(true) 投递到主线程后,future 就可能就绪。调用方需要等主线程处理加载和完成通知,才能按加载完成使用该资源。
小结
- 每个后台接口用
std::packaged_task包装工作、addTask提交、get_future返回,调用方与任务生命周期解耦。 - 「准备」可安全地在后台做;「加载」与「完成事件」是否留主线程由
OGRE_THREAD_SUPPORT == 1决定。 - 完成事件(
_firePreparingComplete/_fireLoadingComplete)永远通过addMainThreadTask回到主线程。 ResourceBackgroundQueue自身无锁——并行全部收敛到 WorkQueue。setRequestsAccepted(false)后新增任务被静默丢弃,调用方靠 future 感知不到、但队列不再增长。
阅读导航:上一节:9.3 合批与顶点缓存 · 下一节:10.2 工作队列 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。