《OGRE 3D 渲染引擎原理与架构》13.2 共享指针

OGRE v14.6.3 的 SharedPtr 已退化为 std::shared_ptr 的向后兼容薄包装:OgreSharedPtr.h 中 useCount/getPointer/staticCast 全部转发标准库并标记 deprecated,Prerequisites.h 用 typedef 为资源类型建立别名。lab 复现引用计数、reset 与析构时机。

13.2 共享指针

上一节的对齐分配器解决「内存往哪儿放」,这一节解决「对象何时销毁」。OGRE 的场景对象(网格、材质、数据流、合成器)会被渲染队列、资源管理器、脚本解析器多方同时引用,任何一个环节擅自 delete 都会悬空。OGRE 的答案经历了从自研引用计数到标准库共享指针的演变:v14.6.3 中 SharedPtr<T> 已经退化为 std::shared_ptr<T> 的向后兼容薄包装——实现完全交给标准库,OGRE 只保留历史 API 别名与资源类型语义。

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

《游戏引擎实现原理》(helio 四卷)在资源层直接使用现代 C++ 的 std::shared_ptr;这里解析真实 OGRE 在漫长生命周期里的取舍:老版本 OGRE 自持 referenceCount 字段,v14.6.3 选择继承并转发标准库,把 useCount、getPointer、staticCast 等旧 API 标记 deprecated 保留给存量代码。看懂这套「包装层」,才能理解为什么 OGRE 的资源接口至今仍以 DataStreamPtr、CompositorPtr 这类 typedef 形式出现。

SharedPtr:继承标准库的薄包装

OgreSharedPtr.h 的类声明非常直白——它不再维护自己的引用计数,而是公开继承 std::shared_ptr:

// OgreMain/include/OgreSharedPtr.h:class SharedPtr(v14.6.3 源码摘录,已删减)
    /// @deprecated for backwards compatibility only, rather use shared_ptr directly
    template<class T> class SharedPtr : public shared_ptr<T>
    {
    public:
        SharedPtr(std::nullptr_t) {}
        SharedPtr() {}
        template< class Y>
        explicit SharedPtr(Y* ptr) : shared_ptr<T>(ptr) {}
        template< class Y, class Deleter >
        SharedPtr( Y* ptr, Deleter d ) : shared_ptr<T>(ptr, d) {}
        SharedPtr(const SharedPtr& r) : shared_ptr<T>(r) {}
        template<class Y>
        SharedPtr(const SharedPtr<Y>& r) : shared_ptr<T>(r) {}

        // implicit conversion from and to shared_ptr
        template<class Y>
        SharedPtr(const shared_ptr<Y>& r) : shared_ptr<T>(r) {}
        operator const shared_ptr<T>&() { return static_cast<shared_ptr<T>&>(*this); }
        SharedPtr<T>& operator=(const Ogre::SharedPtr<T>& rhs) {shared_ptr<T>::operator=(rhs); return *this;}
        // so swig recognizes it should forward the operators
        T* operator->() const { return shared_ptr<T>::operator->(); }
        ...
        /// @deprecated use Ogre::static_pointer_cast instead
        template<typename Y>
        OGRE_DEPRECATED SharedPtr<Y> staticCast() const { return static_pointer_cast<Y>(*this); }
        /// @deprecated use Ogre::dynamic_pointer_cast instead
        template<typename Y>
        OGRE_DEPRECATED SharedPtr<Y> dynamicCast() const { return dynamic_pointer_cast<Y>(*this); }
        /// @deprecated this api will be dropped. use reset(T*) instead
        OGRE_DEPRECATED void bind(T* rep) { shared_ptr<T>::reset(rep); }
        /// @deprecated use use_count() instead
        OGRE_DEPRECATED unsigned int useCount() const { return shared_ptr<T>::use_count(); }
        /// @deprecated use get() instead
        OGRE_DEPRECATED T* getPointer() const { return shared_ptr<T>::get(); }
        /// @deprecated use SharedPtr::operator bool instead
        OGRE_DEPRECATED bool isNull(void) const { return !shared_ptr<T>::operator bool(); }
        /// @deprecated use reset() instead
        OGRE_DEPRECATED void setNull() { shared_ptr<T>::reset(); }
    };

这份包装层透露了清晰的演进策略:新代码请直接用 std::shared_ptr,旧代码在编译期内平滑迁移。每个历史方法都有一一对应的现代替身:

历史 API(deprecated)现代替身语义
useCount()use_count()返回当前引用计数
getPointer()get()返回裸指针
isNull() / setNull()operator bool / reset()判空 / 置空
bind(T*)reset(T*)绑定新对象
staticCast / dynamicCastOgre::static_pointer_cast / dynamic_pointer_cast类型转换

注意类名前面的注释写着「for backwards compatibility only」——这是 OGRE 对自己历史包袱的公开承认,也是规模化的必然:引擎活了二十年,兼容旧 API 的成本远低于让所有存量代码一夜重写。

资源类型的别名体系

SharedPtr 只是骨架,真正让它在引擎里流通的是 OgrePrerequisites.h 里的类型别名:

// OgreMain/include/OgrePrerequisites.h:shared_ptr 与 SharedPtr 别名(v14.6.3 源码摘录,已删减)
    using std::shared_ptr;
    using std::unique_ptr;
    template<typename T> class SharedPtr;

    typedef SharedPtr<AnimableValue> AnimableValuePtr;
    typedef SharedPtr<Compositor> CompositorPtr;
    typedef SharedPtr<DataStream> DataStreamPtr;
    typedef SharedPtr<GpuProgram> GpuProgramPtr;
    typedef SharedPtr<GpuNamedConstants> GpuNamedConstantsPtr;
    typedef SharedPtr<GpuLogicalBufferStruct> GpuLogicalBufferStructPtr;
    typedef SharedPtr<GpuSharedParameters> GpuSharedParametersPtr;

DataStreamPtr 之于 DataStream,就像 CompositorPtr 之于 Compositor——指针类型和对象类型成对出现。返回值写 DataStreamPtr 比写 std::shared_ptr<DataStream> 短得多,更重要的是:当 OGRE 未来某天真的换成其他智能指针(比如带对齐分配器的定制 shared_ptr),只需改这一处 typedef。

引用计数的实际语义

继承 std::shared_ptr 意味着引用计数完全遵循标准库语义:

  • 构造:SharedPtr(Y* ptr) 建立第一个引用,use_count() == 1。
  • 拷贝:SharedPtr(const SharedPtr& r) 共享同一控制块,计数递增。
  • 赋值:operator= 释放旧引用、共享新引用,源对象引用归零时自动析构。
  • 析构:引用归零后控制块销毁对象——这就是 OGRE 资源自动卸载的底层机制。

OGRE 的老版本曾用自持 referenceCount 字段实现这套逻辑,如今这些字段已被标准库接管。v14.6.3 的 SharedPtr 里没有任何数据成员——类体积就是标准库 shared_ptr 的体积(两个裸指针),引用计数数据全部放在堆上的控制块里,多线程安全由标准库保证。

源码定位

  • OgreMain/include/OgreSharedPtr.h :template<class T> class SharedPtr : public shared_ptr<T>(44)、SharedPtr(const SharedPtr& r) : shared_ptr<T>(r)(53)、operator const shared_ptr<T>&()(60)、unsigned int useCount() const(74)、T* getPointer() const(76)、void setNull()(80)
  • OgreMain/include/OgrePrerequisites.h :using std::shared_ptr;(288)、template<typename T> class SharedPtr;(290)、typedef SharedPtr<DataStream> DataStreamPtr;(294)等系列别名(292-298)

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

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

下面用纯 C++ 复现 SharedPtr 包装层及其引用计数语义。它与 src/ogre-ext-13-2-shared-pointer.cpp 逐字节一致:

// file: src/ogre-ext-13-2-shared-pointer.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/ogre-ext-13-2-shared-pointer.cpp -o bin/ogre-ext-13-2-shared-pointer && ./bin/ogre-ext-13-2-shared-pointer
//
// 复现 OgreSharedPtr.h 的 SharedPtr 薄包装(44-81):
//   继承 std::shared_ptr 转发 use_count/get/reset/operator->,
//   用 useCount()/getPointer()/setNull() 保留历史 API;
//   验证引用计数随拷贝/出作用域/ reset 变化,引用归零时自动析构。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cstdint>
#include <memory>

namespace ogre_repro {

template <class T>
class SharedPtr : public std::shared_ptr<T> {
 public:
  SharedPtr() {}
  explicit SharedPtr(T* ptr) : std::shared_ptr<T>(ptr) {}
  SharedPtr(const SharedPtr& r) : std::shared_ptr<T>(r) {}

  // 历史 API:转发标准库
  uint32_t useCount() const { return static_cast<uint32_t>(std::shared_ptr<T>::use_count()); }
  T* getPointer() const { return std::shared_ptr<T>::get(); }
  bool isNull() const { return !std::shared_ptr<T>::operator bool(); }
  void setNull() { std::shared_ptr<T>::reset(); }
};

struct Widget {
  explicit Widget(uint32_t v) : value(v) {}
  uint32_t value;
};

// 析构计数器:验证引用归零时对象确实被销毁
static uint32_t g_destroyed = 0;
struct Tracked {
  Tracked() {}
  ~Tracked() { ++g_destroyed; }
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  // 单引用:useCount == 1
  SharedPtr<Widget> a(new Widget(7));
  CHECK(a.useCount() == 1);
  CHECK(a->value == 7);

  // 拷贝共享同一控制块
  SharedPtr<Widget> b = a;
  CHECK(a.useCount() == 2);
  CHECK(b.useCount() == 2);
  CHECK(a.getPointer() == b.getPointer());

  // 出作用域拷贝减少计数
  {
    SharedPtr<Widget> c = b;
    CHECK(c.useCount() == 3);
  }
  CHECK(a.useCount() == 2);

  // reset 释放一个引用
  b.setNull();
  CHECK(b.isNull());
  CHECK(a.useCount() == 1);

  // 引用归零自动析构
  {
    SharedPtr<Tracked> t1(new Tracked());
    SharedPtr<Tracked> t2 = t1;
    CHECK(g_destroyed == 0);
    t1.setNull();
    CHECK(g_destroyed == 0);  // t2 仍持有
    t2.setNull();
    CHECK(g_destroyed == 1);  // 最后一个引用释放
  }
  CHECK(g_destroyed == 1);

  // 空构造与赋值共享
  SharedPtr<Widget> e;
  CHECK(e.isNull());
  e = a;
  CHECK(!e.isNull());
  CHECK(e.useCount() == 2);
  CHECK_EQ(e->value, static_cast<uint32_t>(7));
  e.reset();
  CHECK(a.useCount() == 1);

  return lab::report("13.2 共享指针");
}

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

小结

  • v14.6.3 的 SharedPtr<T> 公开继承 std::shared_ptr<T>,实现完全交给标准库,类内无自持数据成员。
  • 历史 API(useCount、getPointer、isNull、setNull、bind、staticCast/dynamicCast)全部转发标准库并标记 deprecated。
  • OgrePrerequisites.h 用 typedef SharedPtr<X> XPtr 系列别名让资源指针类型成对出现,未来可整体替换实现。
  • 引用计数遵循标准库语义:拷贝递增、出作用域递减、归零自动析构,多线程安全由标准库控制块保证。

阅读导航:上一节:13.1 对齐分配器 · 下一节:13.3 对象数据布局 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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