《OGRE 3D 渲染引擎原理与架构》10.2 工作队列

10.2 讲 v14.6.3 的任务式 WorkQueue。addTask 入后台 FIFO deque、addMainThreadTask 入主线程 deque;_processNextRequest 取出后执行;processMainThreadTasks 受 10ms 时间预算约束。lab 复现双队列、FIFO、时间预算与丢弃语义,16 项断言。

10.2 工作队列

WorkQueue 是 OGRE 的并行枢纽:后台线程从一条队列取任务执行,主线程通过另一条队列接收结果。v14.6.3 的 WorkQueue 是任务式 API——直接投递 std::function<void()>,而老的 Request/Response 只作为兼容壳保留(头文件注释明说 “Request/Response are not needed and are not used by %Ogre internally”)。DefaultWorkQueueBase 的实现用两条 FIFO deque(mTasks 与 mMainThreadTasks)加各自互斥锁;主线程队列的处理受 mResposeTimeLimitMS(默认 10ms)时间预算约束。

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

10.1 用 WorkQueue 提交资源任务;本节反过来看 WorkQueue 本身的契约与实现:双队列、FIFO 顺序、时间预算、丢弃语义,以及 legacy Request/Response 的归属关系。lab 复现 DefaultWorkQueueBase 的全部关键行为。

任务式 API:addTask 与 addMainThreadTask

WorkQueue::addTask 的契约要点全在头文件注释里:可从任意线程调用、按提交顺序执行(多 worker 时完成顺序不定)、队列关闭或 setRequestsAccepted(false) 时静默丢弃、异常逃逸会终止进程、OGRE_THREAD_SUPPORT == 0 时内联执行:

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

DefaultWorkQueueBase::addTask 的实现先锁请求队列,检查接受/关闭标志,然后:有线程支持就 push 并唤醒 worker;没线程支持就直接同步执行。它还用 LML_TRIVIAL 日志记录入队:

// OgreMain/src/OgreWorkQueue.cpp:DefaultWorkQueueBase::addTask(v14.6.3 源码摘录,已删减)
    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
        LogManager::getSingleton().stream(LML_TRIVIAL)
            << "DefaultWorkQueueBase('" << mName << "') - QUEUED(thread:" << OGRE_THREAD_CURRENT_ID << ")";
    }

addMainThreadTask 走 mResponseMutex 与 mMainThreadTasks,同样受接受标志约束。lab 的 WorkQueueBaseRepro 复现这两条入队路径,并断言后台 FIFO 顺序 "ABC" 与主线程队列独立计数。

_processNextRequest:锁内只取,取出后执行

后台 worker 每次处理一个任务:在锁保护的短作用域里 pop_front,释放锁后再执行。这把「取任务」的临界区压到最小,执行长任务不阻塞其他线程入队:

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

std::move 把任务移出队列,避免拷贝闭包。lab 的 processOneTask 复现「取 → 执行」两步。

processMainThreadTasks:10ms 时间预算

主线程队列由 Root 在每帧 _fireFrameEnded 末尾调用 processMainThreadTasks() 泵出。它有个重要保护:mResposeTimeLimitMS(默认 10ms)——每完成一个任务就检查已耗时间,超预算立即停下,把剩余任务留给下一帧。注释明确说明「单次长任务可能超预算,每次调用有独立预算」:

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

lab 用带 costMS 的任务模拟耗时:三个各 6ms 的任务在 10ms 预算下只完成两个(累计 12 > 10),第三个留在队列;下一次 processMainThreadTasks 是新预算,把它清掉。

legacy Request/Response:Response 拥有 Request

任务式 API 不需要 Request/Response,但它们保留给旧代码。值得注意的是所有权:Response 析构时 OGRE_DELETE mRequest——Response 拥有它的 Request,销毁 Response 会自动销毁 Request,不要两边都 delete:

// OgreMain/src/OgreWorkQueue.cpp:WorkQueue::Response::~Response(v14.6.3 源码摘录,已删减)
    WorkQueue::Response::~Response()
    {
        OGRE_DELETE mRequest;
    }

lab 用一个静态删除计数器验证:new LegacyRequest → 包进 LegacyResponse → delete resp 后 gRequestDeletes 恰好 +1。

队列预算与任务持有者

后台任务与主线程任务分别排队。预算在任务之间检查,单条耗时任务仍可能超过预算。退出时要处理任务持有的对象、回调和相应线程,不能只读取任务是否提交。

以长短两个主线程任务观察泵送和预算。Paging 探针将 worker 数设为一,通过队尾标记确认后台阶段结束,再显式处理主线程响应。

两条队列与结果提交

flowchart TD
  A["调用方"] --> Q["后台任务队列"]
  Q --> W["worker 取任务"]
  W --> P["CPU 准备资源或 PageData"]
  P --> C["主线程任务队列"]
  F["帧尾或宿主显式任务泵"] --> C
  C --> L["主线程提交资源或派发通知"]
  S["Root 关停"] --> J["停止并等待 worker"]
  J -.->|"资源回调由宿主在释放前处理"| C

源码定位

  • OgreMain/include/OgreWorkQueue.h:WorkQueue::addTask/addMainThreadTask(201-294 行)
  • OgreMain/src/OgreWorkQueue.cpp:DefaultWorkQueueBase::addTask(103-117 行)
  • OgreMain/src/OgreWorkQueue.cpp:DefaultWorkQueueBase::_processNextRequest(143-158 行)
  • OgreMain/src/OgreWorkQueue.cpp:DefaultWorkQueueBase::processMainThreadTasks(160-186 行)
  • OgreMain/src/OgreWorkQueue.cpp:WorkQueue::Response::~Response(58-61 行)

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

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

WorkQueueBaseRepro 复现双 FIFO deque、processOneTask 的取-执行两步、带时间预算的主线程泵出,以及 setRequestsAccepted(false) 丢弃语义;LegacyResponse 复现 Response 析构删除 Request。它与 src/10-2-work-queue.cpp 逐字节一致:

// file: src/10-2-work-queue.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/10-2-work-queue.cpp -o bin/10-2-work-queue && ./bin/10-2-work-queue
//
// 复现 DefaultWorkQueueBase 的任务式 API(OgreMain/src/OgreWorkQueue.cpp
//   95-186 的 addTask/addMainThreadTask/_processNextRequest/
//   processMainThreadTasks):后台与主线程各一条 FIFO deque;addTask 在
//   OGRE_THREAD_SUPPORT==0 时直接执行;主线程队列处理受 mResposeTimeLimitMS
//   时间预算约束;Request/Response 仅为 legacy(Response 析构删除 Request)。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cstdint>
#include <deque>
#include <functional>
#include <string>
#include <utility>

namespace ogre_repro {

// 对应 DefaultWorkQueueBase 的双队列 + 时间预算(瘦身版)
class WorkQueueBaseRepro {
public:
    explicit WorkQueueBaseRepro(uint64_t timeLimitMS = 10) : mLimitMS(timeLimitMS) {}

    void addTask(std::function<void()> task) {
        if (!mAcceptRequests || mShuttingDown)
            return;
        mTasks.push_back(std::move(task));
    }

    void addMainThreadTask(std::function<void()> task, uint64_t costMS = 1) {
        if (!mAcceptRequests || mShuttingDown)
            return;
        mMainThreadTasks.push_back({std::move(task), costMS});
    }

    // 对应 _processNextRequest:锁内只取,取出后执行
    void processOneTask() {
        if (mTasks.empty())
            return;
        std::function<void()> task = std::move(mTasks.front());
        mTasks.pop_front();
        task();
    }

    // 对应 processMainThreadTasks:每完成一个任务检查时间预算
    void processMainThreadTasks() {
        uint64_t elapsed = 0;
        while (!mMainThreadTasks.empty()) {
            MainTask item = std::move(mMainThreadTasks.front());
            mMainThreadTasks.pop_front();
            item.fn();
            elapsed += item.costMS;
            if (mLimitMS && elapsed > mLimitMS)
                break;  // 超预算,其余留在队列
        }
    }

    size_t pendingBackground() const { return mTasks.size(); }
    size_t pendingMain() const { return mMainThreadTasks.size(); }
    void setRequestsAccepted(bool a) { mAcceptRequests = a; }
    bool getRequestsAccepted() const { return mAcceptRequests; }

private:
    struct MainTask {
        std::function<void()> fn;
        uint64_t costMS;
    };

    std::deque<std::function<void()>> mTasks;
    std::deque<MainTask> mMainThreadTasks;
    uint64_t mLimitMS;
    bool mAcceptRequests = true;
    bool mShuttingDown = false;
};

// 对应 OgreWorkQueue.h 105-177 的 legacy Request/Response:
// Response 拥有 Request,析构时删除(OgreWorkQueue.cpp 59 行 OGRE_DELETE)
inline int gRequestDeletes = 0;

struct LegacyRequest {
    uint16_t mChannel;
    uint16_t mType;
    explicit LegacyRequest(uint16_t ch, uint16_t ty) : mChannel(ch), mType(ty) {}
    ~LegacyRequest() { ++gRequestDeletes; }
    uint16_t getChannel() const { return mChannel; }
    uint16_t getType() const { return mType; }
};

struct LegacyResponse {
    const LegacyRequest* mRequest;
    bool mSuccess;
    explicit LegacyResponse(const LegacyRequest* rq, bool ok)
        : mRequest(rq), mSuccess(ok) {}
    ~LegacyResponse() { delete mRequest; }  // 对应 OgreWorkQueue.cpp 59-60 行
    bool succeeded() const { return mSuccess; }
    const LegacyRequest* getRequest() const { return mRequest; }
};

}  // namespace ogre_repro

int main() {
    using namespace ogre_repro;

    WorkQueueBaseRepro wq(10);  // 默认 10ms 时间预算
    std::string order;

    // 后台队列 FIFO:A、B、C 按入队顺序取出
    wq.addTask([&order]() { order += "A"; });
    wq.addTask([&order]() { order += "B"; });
    wq.addTask([&order]() { order += "C"; });
    CHECK_EQ(wq.pendingBackground(), 3u);
    wq.processOneTask();
    wq.processOneTask();
    wq.processOneTask();
    CHECK_EQ(wq.pendingBackground(), 0u);
    CHECK(order == "ABC");

    // 主线程队列:x、y 各 6ms,完成后累计 12 > 预算 10,z 留在队列
    order.clear();
    wq.addMainThreadTask([&order]() { order += "x"; }, 6);
    wq.addMainThreadTask([&order]() { order += "y"; }, 6);
    wq.addMainThreadTask([&order]() { order += "z"; }, 6);
    CHECK_EQ(wq.pendingMain(), 3u);
    wq.processMainThreadTasks();
    CHECK(order == "xy");              // 第三个因超预算未执行
    CHECK_EQ(wq.pendingMain(), 1u);    // z 仍在队列
    wq.processMainThreadTasks();       // 新的一次调用有独立预算
    CHECK(order == "xyz");
    CHECK_EQ(wq.pendingMain(), 0u);

    // setRequestsAccepted(false):新任务被静默丢弃
    wq.setRequestsAccepted(false);
    CHECK(!wq.getRequestsAccepted());
    wq.addTask([&order]() { order += "D"; });
    wq.addMainThreadTask([&order]() { order += "w"; }, 1);
    CHECK_EQ(wq.pendingBackground(), 0u);
    CHECK_EQ(wq.pendingMain(), 0u);
    CHECK(order == "xyz");

    // legacy Request/Response:Response 析构删除其 Request
    const int deletesBefore = gRequestDeletes;
    auto* req = new LegacyRequest(1, 42);
    auto* resp = new LegacyResponse(req, true);
    CHECK(resp->succeeded());
    CHECK_EQ(resp->getRequest()->getChannel(), 1u);
    CHECK_EQ(resp->getRequest()->getType(), 42u);
    delete resp;
    CHECK_EQ(gRequestDeletes, deletesBefore + 1);

    return lab::report("10.2 工作队列");
}

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

小结

  • v14.6.3 的 WorkQueue 是任务式 API,std::function<void()> 直接入队;Request/Response 仅为兼容壳。
  • 后台与主线程各一条 FIFO deque,_processNextRequest 在锁内 pop_front、锁外执行。
  • 主线程队列由 processMainThreadTasks 泵出,受 mResposeTimeLimitMS(默认 10ms)时间预算约束。
  • setRequestsAccepted(false) 或关闭期间新任务被静默丢弃,队列不增长。
  • legacy Response 析构删除其 Request,所有权语义是「销毁 Response 即销毁 Request」。

阅读导航:上一节:10.1 后台资源队列 · 下一节:10.3 资源流式加载 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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