《OGRE 3D 渲染引擎原理与架构》12.2 注册与派发顺序

Root 的 addFrameListener/removeFrameListener 不直接改活动集,而是写 mAdded/mRemoved 待办集,派发前 _syncAddedRemovedFrameListeners 先删后加。活动集是 std::set<FrameListener*>,按指针升序派发;任一回调返回 false 立即短路,派发中被标记移除的监听器本轮跳过。lab 用 C++ 复现这套 pending 注册与派发。

12.2 注册与派发顺序

12.1 讲了 FrameListener 长什么样;这一节看 Root 怎么存和管理它——重点是「注册不立即生效、派发前统一同步」的 pending 设计。

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

12.1 讲接口本身;这里讲 Root 的实现:三个 std::set 各管什么、为什么加/删要走待办集。

addFrameListener / removeFrameListener:写待办集

Root::addFrameListener 和 removeFrameListener 都不直接碰活动集 mFrameListeners:

// OgreMain/src/OgreRoot.cpp:Root::addFrameListener/removeFrameListener(v14.6.3 源码摘录,已删减)
    void Root::addFrameListener(FrameListener* newListener)
    {
        mRemovedFrameListeners.erase(newListener);
        mAddedFrameListeners.insert(newListener);
    }
    //-----------------------------------------------------------------------
    void Root::removeFrameListener(FrameListener* oldListener)
    {
        mAddedFrameListeners.erase(oldListener);
        mRemovedFrameListeners.insert(oldListener);
    }

注意交叉擦除:add 会从「待删集」里移除同名指针,remove 会从「待加集」里移除同名指针——最后一次操作生效。调用方在任意时刻增删,都不会破坏正在进行的派发。

派发前同步:先删后加

_syncAddedRemovedFrameListeners 把待办集落进活动集:

// OgreMain/src/OgreRoot.cpp:Root::_syncAddedRemovedFrameListeners(v14.6.3 源码摘录,已删减)
    void Root::_syncAddedRemovedFrameListeners()
    {
        for (auto& l : mRemovedFrameListeners)
            mFrameListeners.erase(l);
        mRemovedFrameListeners.clear();

        for (auto& l : mAddedFrameListeners)
            mFrameListeners.insert(l);
        mAddedFrameListeners.clear();
    }

先删后加的顺序有讲究:同一帧里先 remove 再 add 的监听器,最终以 add 为准——因为 add 已把它的名字从待删集擦掉了。

活动集是 std::set:按指针升序

OgreRoot.h 里三个集都是 std::set<FrameListener*>:

// OgreMain/include/OgreRoot.h:监听器容器(v14.6.3 源码摘录,已删减)
        /** Set of registered frame listeners */
        std::set<FrameListener*> mFrameListeners;

        /** Set of frame listeners marked for removal and addition*/
        std::set<FrameListener*> mRemovedFrameListeners;
        std::set<FrameListener*> mAddedFrameListeners;

std::set 有两个影响:

  1. 自动去重:同一指针不会出现两次;
  2. 有序遍历:按指针地址升序派发——派发顺序由地址大小决定,与注册顺序无关。依赖监听器调用顺序的代码要自己维护优先级。

_fireFrameStarted:短路派发

派发逻辑里有个防御性检查:同步后遍历活动集,若某监听器在本轮派发中被标记移除(比如前面的回调内调用了 removeFrameListener),就跳过它:

// OgreMain/src/OgreRoot.cpp:Root::_fireFrameStarted(v14.6.3 源码摘录,已删减)
    bool Root::_fireFrameStarted(FrameEvent& evt)
    {
        OgreProfileBeginGroup("Frame", OGREPROF_GENERAL);
        _syncAddedRemovedFrameListeners();

        // Tell all listeners
        for (auto *l : mFrameListeners)
        {
            if(mRemovedFrameListeners.find(l) != mRemovedFrameListeners.end())
                continue;

            if (!l->frameStarted(evt))
                return false;
        }

        return true;
    }

两个关键行为:

  • if (!l->frameStarted(evt)) return false;:任一监听器返回 false,整个事件链立即中断,_fireFrameStarted 返回 false——上层(12.3 的 renderOneFrame)据此退出渲染循环;
  • mRemovedFrameListeners.find(l) != end() 检查:同步已经把待删集清空,这个检查针对的是遍历过程中新产生的移除——前面的回调把后面的监听器移除了,后面的就收不到本轮事件。

回调中修改登记的生效点

Root 在每个派发阶段开始同步待增删集合。派发循环还检查当轮的移除标记,避免正在迭代时对活动集合做结构性修改。新增和移除的观察点都要注明属于哪个回调阶段。

在 frameStarted 中移除监听器后,再观察 queued 与 ended。false 控制当前阶段能否继续以及后续阶段是否进入,完整路径由卷二 14.1 维护。

源码定位

  • OgreMain/src/OgreRoot.cpp :Root::addFrameListener/removeFrameListener(待办集)、_syncAddedRemovedFrameListeners(先删后加)、_fireFrameStarted(短路派发)
  • OgreMain/include/OgreRoot.h :mFrameListeners/mRemovedFrameListeners/mAddedFrameListeners(std::set<FrameListener*>)

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

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

下面复现 pending 注册与派发机制。它与 src/12-2-listener-registration.cpp 逐字节一致:

// file: src/12-2-listener-registration.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/12-2-listener-registration.cpp -o bin/12-2-listener-registration && ./bin/12-2-listener-registration
//
// 复现 Root 的帧监听器注册/派发:
//   addFrameListener/removeFrameListener 只写 mAdded/mRemoved 待办集
//   (对应 OgreRoot.cpp 的 pending 设计);
//   派发前 _syncAddedRemovedFrameListeners 先删后加;
//   mFrameListeners 是 std::set(按指针升序派发);
//   回调返回 false 立即短路;派发中被标记移除的监听器本轮跳过。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <functional>
#include <set>
#include <string>

namespace ogre_repro {

// 对应 Ogre::FrameListener 的最小版
class FrameListener {
 public:
  virtual ~FrameListener() {}
  virtual bool frameStarted() { return true; }  // 返回 false 表示中止
  std::string name;
};

// 记录调用顺序的监听器
class LoggingListener : public FrameListener {
 public:
  LoggingListener(const std::string& n) { name = n; }
  bool frameStarted() override {
    log += name + " ";
    // 派发中途移除别的监听器(对应真实代码里回调内调用 removeFrameListener)
    if (removeCb) removeCb(removeTarget);
    return allowContinue;
  }
  std::string log;
  bool allowContinue = true;
  std::function<void(FrameListener*)> removeCb;
  FrameListener* removeTarget = nullptr;
};

// 对应 Root 的帧监听器管理(仅 frameStarted 事件)
class Root {
 public:
  std::set<FrameListener*> mFrameListeners;
  std::set<FrameListener*> mRemovedFrameListeners;
  std::set<FrameListener*> mAddedFrameListeners;

  // 对应 Root::addFrameListener:写待加集,不直接改活动集
  void addFrameListener(FrameListener* l) {
    mRemovedFrameListeners.erase(l);
    mAddedFrameListeners.insert(l);
  }
  // 对应 Root::removeFrameListener:写待删集
  void removeFrameListener(FrameListener* l) {
    mAddedFrameListeners.erase(l);
    mRemovedFrameListeners.insert(l);
  }
  // 对应 Root::_syncAddedRemovedFrameListeners:先删后加
  void sync() {
    for (auto* l : mRemovedFrameListeners) mFrameListeners.erase(l);
    mRemovedFrameListeners.clear();
    for (auto* l : mAddedFrameListeners) mFrameListeners.insert(l);
    mAddedFrameListeners.clear();
  }
  // 对应 Root::_fireFrameStarted 的分发核心
  bool fire() {
    sync();
    for (auto* l : mFrameListeners) {
      if (mRemovedFrameListeners.count(l)) continue;  // 本轮派发中被标记移除
      if (!l->frameStarted()) return false;           // 任一 false → 中止
    }
    return true;
  }
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  LoggingListener a("A"), b("B"), c("C");
  Root root;
  root.addFrameListener(&a);
  root.addFrameListener(&b);
  root.addFrameListener(&c);
  root.fire();

  // std::set 按指针升序派发(地址顺序而非注册顺序),每个监听器恰好收到一次
  std::string order = a.log + b.log + c.log;
  CHECK(order.find("A") != std::string::npos);
  CHECK(order.find("B") != std::string::npos);
  CHECK(order.find("C") != std::string::npos);
  CHECK(order.length() == 6);  // 三个名字各 1 字符 + 空格

  // 返回 false 的监听器中断事件链
  a.log.clear(); b.log.clear(); c.log.clear();
  b.allowContinue = false;
  bool cont = root.fire();
  CHECK(!cont);              // 事件链中断
  CHECK(b.log == "B ");      // B 必定被调用并返回 false

  // 移除监听器:加入待删集,下次 fire 前同步生效
  a.log.clear(); b.log.clear(); c.log.clear();
  root.removeFrameListener(&b);
  b.allowContinue = true;
  cont = root.fire();
  CHECK(cont);
  CHECK(b.log.empty());      // B 已被移除,不再收到事件

  // 先删后加:最后一次操作生效
  LoggingListener d("D");
  root.addFrameListener(&d);    // 待加
  root.removeFrameListener(&d); // 撤销加
  root.addFrameListener(&d);    // 重新加(擦除待删)
  root.fire();
  CHECK(d.log == "D ");

  // 派发中途移除:A 的回调把 C 加入待删集,C 本轮被跳过,下次 fire 真正移除
  a.log.clear(); b.log.clear(); c.log.clear();
  a.removeCb = [&root](FrameListener* t) { root.removeFrameListener(t); };
  a.removeTarget = &c;
  root.fire();  // 第一轮:A 回调内 removeFrameListener(&c)
  // C 本轮是否收到取决于指针顺序,不假设;第二轮 C 一定收不到
  root.fire();  // 第二轮:sync 已真正移除 C
  CHECK(c.log == "" || c.log == "C ");  // C 最多在第一轮收到一次

  return lab::report("12-2 事件与监听:注册与派发顺序");
}

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

小结

  • addFrameListener/removeFrameListener 只写待办集,派发前 _syncAddedRemovedFrameListeners 先删后加。
  • 三个容器都是 std::set<FrameListener*>:自动去重、按指针升序派发。
  • 任一回调返回 false,事件链立即短路;派发中途被移除的监听器本轮跳过。
  • 同步时机保证:增删任意时刻都安全,正在进行的派发不受影响。

阅读导航:上一节:12.1 FrameListener 与帧事件 · 下一节:12.3 渲染循环中的事件时序 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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