《OGRE 3D 渲染引擎原理与架构》14.2 WorkQueue 与后台加载

WorkQueue 抽象把后台任务统一管起来:Request/Response 作为遗留兼容结构保留,新 API 用 addTask/std::function 直接投递;DefaultWorkQueueBase 用双队列(后台 + 主线程)加请求门控,worker 线程数默认 1,主线程预算 10ms。lab 复现 FIFO 与门控。

14.2 WorkQueue 与后台加载

资源加载不该卡住主线程:网格、贴图、地形都可以在后台线程准备,主线程每帧「泵」一次结果。OGRE 把这类需求收进 WorkQueue 抽象——一个跨线程的任务队列。v14.6.3 的 WorkQueue 已从「请求/响应 + 回调处理器」演进成任务式 API(addTask),旧的 Request/Response 结构只作源码兼容保留。这一节看接口骨架与 DefaultWorkQueueBase 的双队列实现。

本章与站内既有内容的分工

卷一 ogre-core 的 ResourceGroupManager 管资源组的声明周期,这一节的 WorkQueue 是执行后台工作的线程池;14.3 的 ResourceBackgroundQueue 正是在 WorkQueue 之上封装资源操作。与 cg 三卷无关,此节是纯并发架构。

WorkQueue 接口:任务式 API

WorkQueue 是纯抽象,核心是两条投递通道:addTask(后台 worker 执行)与 addMainThreadTask(主线程泵)。任务类型就是 std::function<void()>,捕获必须可拷贝:

// OgreMain/include/OgreWorkQueue.h:WorkQueue::addTask(v14.6.3 源码摘录,已删减)
        /** Add a new task to the background queue.

            May be called from any thread. Tasks are executed in submission order,
            but with more than one worker thread the completion order is unspecified.

            The task is silently dropped if the queue is shutting down or if
            @ref setRequestsAccepted has been called with `false`.

            Tasks are `std::function<void()>`, so the captures must be copyable.
            With `OGRE_THREAD_SUPPORT == 0` the task is executed inline on the
            calling thread instead of being queued.

            @warning An exception escaping the task terminates the process.
            Wrap potentially throwing work in a `std::packaged_task`.
        */
        virtual void addTask(std::function<void()> task) = 0;
要点说明
任意线程可投递后台线程、主线程都能 addTask
静默丢弃关停期或 setRequestsAccepted(false) 时新任务不入队
无线程支持时内联OGRE_THREAD_SUPPORT == 0 时直接在调用线程执行
异常即终止进程任务抛异常逃逸会终止程序,危险工作用 packaged_task

旧的 Request/Response 结构仍在头文件里(Request 带 mChannel/mType/mData/mRetryCount/mID/mAborted,Response 持有 mRequest 且析构时 OGRE_DELETE 它),但 OGRE 内部已不用,注释明确写着「kept for source compatibility」。阅读老代码时看到 addRequestHandler 不要困惑——那是更早版本的 API。

DefaultWorkQueueBase:双队列与门控

默认实现用两条 std::deque<std::function<void()>>:mTasks(后台)与 mMainThreadTasks(主线程)。构造函数把默认值写死:

// OgreMain/src/OgreWorkQueue.cpp:DefaultWorkQueueBase 构造与 addTask(v14.6.3 源码摘录,已删减)
    DefaultWorkQueueBase::DefaultWorkQueueBase(const String& name)
        : mName(name)
        , mWorkerThreadCount(1)
        , mWorkerRenderSystemAccess(false)
        , mIsRunning(false)
        , mResposeTimeLimitMS(10)
        , mPaused(false)
        , mAcceptRequests(true)
        , mShuttingDown(false)
    {
    }
    ...
    void DefaultWorkQueueBase::addTask(std::function<void()> task)
    {
        OGRE_WQ_LOCK_MUTEX(mRequestMutex);
        if (!mAcceptRequests || mShuttingDown)
            return;

#if OGRE_THREAD_SUPPORT
        mTasks.push_back(task);
        notifyWorkers();
#else
        task(); // no threading, just run it
#endif
    }

默认配置与门控:

成员默认角色
mWorkerThreadCount1worker 线程数
mResposeTimeLimitMS10主线程队列每次泵的毫秒预算
mAcceptRequeststrue是否接受新任务
mShuttingDownfalse是否关停中

addTask 先加锁再检查门控;有线程支持时 push_back 并 notifyWorkers() 唤醒一个等待线程,无线程支持时直接内联执行。_processNextRequest 是 worker 与外部驱动共用的取任务入口:

// OgreMain/src/OgreWorkQueue.cpp:DefaultWorkQueueBase::_processNextRequest(v14.6.3 源码摘录,已删减)
    void DefaultWorkQueueBase::_processNextRequest()
    {
        std::function<void()> task;
        {
            // scoped to only lock while retrieving the next request
            OGRE_WQ_LOCK_MUTEX(mRequestMutex);
            if (mTasks.empty())
                return;
            LogManager::getSingleton().stream(LML_TRIVIAL)
                << "DefaultWorkQueueBase('" << mName << "') - PROCESS_TASK(thread:" << OGRE_THREAD_CURRENT_ID
                << ")";
            task = std::move(mTasks.front());
            mTasks.pop_front();
        }
        task();
    }

锁只在「取任务」的作用域里持有,拿到任务后立刻解锁再执行——这是队首取、队外跑的典型生产者-消费者写法,避免长时间持锁阻塞其他投递者。

主线程泵与 worker 线程

processMainThreadTasks 由 Root::renderOneFrame 在 frameEnded 后自动调用。它循环处理 mMainThreadTasks,每条之间检查毫秒预算:

// OgreMain/src/OgreWorkQueue.cpp:DefaultWorkQueueBase::processMainThreadTasks(v14.6.3 源码摘录,已删减)
    void DefaultWorkQueueBase::processMainThreadTasks()
    {
        unsigned long msStart = Root::getSingleton().getTimer()->getMilliseconds();
        unsigned long msCurrent = 0;

        // keep going until we run out of responses or out of time
        while(!mMainThreadTasks.empty())
        {
            std::function<void()> task;
            {
                OGRE_WQ_LOCK_MUTEX(mResponseMutex);
                LogManager::getSingleton().stream(LML_TRIVIAL)
                    << "DefaultWorkQueueBase('" << mName << "') - PROCESS_MAIN_TASK";
                task = std::move(mMainThreadTasks.front());
                mMainThreadTasks.pop_front();
            }
            task();

            // time limit
            if (mResposeTimeLimitMS)
            {
                msCurrent = Root::getSingleton().getTimer()->getMilliseconds();
                if (msCurrent - msStart > mResposeTimeLimitMS)
                    break;
            }
        }
    }

主线程泵有一个 10ms 预算:每条任务完成才检查一次,所以单条长任务可能超预算,但每条调用各拿自己的预算。真正的 worker 线程由 DefaultWorkQueue::startup 按 mWorkerThreadCount 逐个创建,每个线程跑 _threadMain(先 waitForNextRequest 挂起,被 notifyWorkers 唤醒后 _processNextRequest);shutdown 置 mShuttingDown、唤醒全部线程并 join。

源码定位

  • OgreMain/include/OgreWorkQueue.h :WorkQueue 接口(102-304)、Request(115-146)、Response(155-177)、_processNextRequest(360)、mTasks/mMainThreadTasks(394-395)
  • OgreMain/src/OgreWorkQueue.cpp :DefaultWorkQueueBase 构造(64-74)、addTask(103-117)、addMainThreadTask(95-101)、_processNextRequest(143-158)、processMainThreadTasks(160-186)
  • OgreMain/src/OgreDefaultWorkQueueStandard.cpp :startup(89-130)、shutdown(143-169)、waitForNextRequest(178-194)、_threadMain(196-204)

上游引用固定到 OGRE v14.6.3 源码 。

可运行产物:C++ 最小验证

下面复现双队列 FIFO、主线程泵的预算限制与请求门控。它与 src/14-2-work-queue.cpp 逐字节一致:

// file: src/14-2-work-queue.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/14-2-work-queue.cpp -o bin/14-2-work-queue && ./bin/14-2-work-queue
//
// 复现 DefaultWorkQueueBase 的双队列与请求门控(对应 OgreWorkQueue.cpp 64-186):
//   addTask/addMainThreadTask 在 !mAcceptRequests || mShuttingDown 时静默丢弃;
//   _processNextRequest 从 mTasks 队首取任务并执行(FIFO);
//   processMainThreadTasks 泵 mMainThreadTasks,每泵一次受时间预算限制;
//   默认 1 个 worker 线程、主线程预算 10ms、接受请求。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cstddef>
#include <deque>
#include <functional>
#include <vector>

namespace ogre_repro {

class DefaultWorkQueueBaseRepro {
 public:
  DefaultWorkQueueBaseRepro()
      : mWorkerThreadCount(1), mResposeTimeLimitMS(10), mAcceptRequests(true),
        mShuttingDown(false) {}

  size_t getWorkerThreadCount() const { return mWorkerThreadCount; }
  void setWorkerThreadCount(size_t c) { mWorkerThreadCount = c; }
  unsigned long getResponseProcessingTimeLimit() const { return mResposeTimeLimitMS; }
  void setResponseProcessingTimeLimit(unsigned long ms) { mResposeTimeLimitMS = ms; }
  bool getRequestsAccepted() const { return mAcceptRequests; }
  bool isShuttingDown() const { return mShuttingDown; }
  void setRequestsAccepted(bool accept) { mAcceptRequests = accept; }
  void shutdown() { mShuttingDown = true; }

  // 对应 addTask:拒绝期或关停期静默丢弃
  void addTask(std::function<void()> task) {
    if (!mAcceptRequests || mShuttingDown) return;
    mTasks.push_back(std::move(task));
  }
  // 对应 addMainThreadTask
  void addMainThreadTask(std::function<void()> task) {
    if (!mAcceptRequests || mShuttingDown) return;
    mMainThreadTasks.push_back(std::move(task));
  }
  // 对应 _processNextRequest:取队首任务执行
  void _processNextRequest() {
    if (mTasks.empty()) return;
    std::function<void()> task = std::move(mTasks.front());
    mTasks.pop_front();
    task();
  }
  // 对应 processMainThreadTasks:泵主线程队列,受时间预算限制
  void processMainThreadTasks() {
    size_t processed = 0;
    while (!mMainThreadTasks.empty()) {
      std::function<void()> task = std::move(mMainThreadTasks.front());
      mMainThreadTasks.pop_front();
      task();
      ++processed;
      // 简化预算:mResposeTimeLimitMS > 0 时每次调用最多处理该条数(真实实现按毫秒计时)
      if (mResposeTimeLimitMS && processed >= mResposeTimeLimitMS) break;
    }
  }

  size_t pendingBackground() const { return mTasks.size(); }
  size_t pendingMain() const { return mMainThreadTasks.size(); }

 private:
  size_t mWorkerThreadCount;
  unsigned long mResposeTimeLimitMS;
  bool mAcceptRequests;
  bool mShuttingDown;
  std::deque<std::function<void()>> mTasks;         // 对应 mTasks
  std::deque<std::function<void()>> mMainThreadTasks;  // 对应 mMainThreadTasks
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  DefaultWorkQueueBaseRepro q;

  // 默认配置:1 个 worker、主线程预算 10ms、接受请求
  CHECK_EQ(q.getWorkerThreadCount(), size_t(1));
  CHECK_EQ(q.getResponseProcessingTimeLimit(), 10ul);
  CHECK(q.getRequestsAccepted());
  CHECK(!q.isShuttingDown());

  std::vector<int> order;

  // 双队列入队:后台 2 条 + 主线程 1 条
  q.addTask([&]() { order.push_back(1); });
  q.addTask([&]() { order.push_back(2); });
  q.addMainThreadTask([&]() { order.push_back(10); });
  CHECK_EQ(q.pendingBackground(), size_t(2));
  CHECK_EQ(q.pendingMain(), size_t(1));

  // 后台 FIFO:_processNextRequest 逐个执行
  q._processNextRequest();
  q._processNextRequest();
  CHECK_EQ(q.pendingBackground(), size_t(0));
  CHECK_EQ(order.size(), size_t(2));
  CHECK_EQ(order[0], 1);
  CHECK_EQ(order[1], 2);

  // 主线程队列由 processMainThreadTasks 泵
  q.processMainThreadTasks();
  CHECK_EQ(q.pendingMain(), size_t(0));
  CHECK_EQ(order.size(), size_t(3));
  CHECK_EQ(order.back(), 10);

  // 预算限制:每泵一次最多处理 1 条
  q.setResponseProcessingTimeLimit(1);
  q.addMainThreadTask([&]() { order.push_back(21); });
  q.addMainThreadTask([&]() { order.push_back(22); });
  q.addMainThreadTask([&]() { order.push_back(23); });
  q.processMainThreadTasks();
  CHECK_EQ(q.pendingMain(), size_t(2));
  q.processMainThreadTasks();
  CHECK_EQ(q.pendingMain(), size_t(1));
  q.processMainThreadTasks();
  CHECK_EQ(q.pendingMain(), size_t(0));

  // setRequestsAccepted(false):新任务静默丢弃
  q.setResponseProcessingTimeLimit(10);
  q.setRequestsAccepted(false);
  q.addTask([&]() { order.push_back(3); });
  q.addMainThreadTask([&]() { order.push_back(11); });
  CHECK_EQ(q.pendingBackground(), size_t(0));
  CHECK_EQ(q.pendingMain(), size_t(0));

  // 重新接受:任务又能入队
  q.setRequestsAccepted(true);
  q.addTask([&]() { order.push_back(4); });
  CHECK_EQ(q.pendingBackground(), size_t(1));

  // shutdown:继续丢弃
  q.shutdown();
  CHECK(q.isShuttingDown());
  q.addTask([&]() { order.push_back(5); });
  CHECK_EQ(q.pendingBackground(), size_t(1));
  q.addMainThreadTask([&]() { order.push_back(12); });
  CHECK_EQ(q.pendingMain(), size_t(0));

  return lab::report("14-2 WorkQueue 与后台加载");
}

本机实测(Apple clang 16,clang++ -std=c++20):编译通过(-Wall 零警告),断言 22/22 通过。

小结

  • WorkQueue 是任务式接口:addTask 后台执行、addMainThreadTask 主线程泵,旧的 Request/Response 仅作源码兼容。
  • DefaultWorkQueueBase 用两条 deque 装后台与主线程任务,门控条件 !mAcceptRequests || mShuttingDown 时静默丢弃。
  • _processNextRequest 锁内取任务、锁外执行,避免长期持锁。
  • processMainThreadTasks 每泵一次受 mResposeTimeLimitMS(默认 10ms)预算约束。
  • worker 线程由 startup 按 mWorkerThreadCount(默认 1)创建,waitForNextRequest/notifyWorkers 负责挂起与唤醒。

阅读导航:上一节:14.1 渲染目标管理 · 下一节:14.3 多线程渲染 。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图