《OGRE 3D 渲染引擎原理与架构》3.2 OgreDynLib 动态加载与解析

插件以动态库形式存在,OgreDynLib 是加载动态库的封装:保存句柄,按符号名取地址。Root::loadPlugin 从库里找 dllStartPlugin 符号并调用,找不到则抛 ERR_ITEM_NOT_FOUND。符号解析失败、重复加载去重是这套机制的两个关键点。lab 用 C++ 符号表复现查找与缺失语义。

3.2 OgreDynLib 动态加载与解析

插件文件是 .so、.dll、.dylib,运行期用 dlopen/dlsym(或 Windows 的 LoadLibrary/GetProcAddress)打开。OGRE 把这一层封装成 OgreDynLib,类不大但语义完整:

// OgreMain/include/OgreDynLib.h:DynLib 类(v14.6.3 源码摘录,已删减)
#if OGRE_PLATFORM == OGRE_PLATFORM_WIN32 || OGRE_PLATFORM == OGRE_PLATFORM_WINRT
    typedef struct HINSTANCE__* DYNLIB_HANDLE;
#else
    typedef void* DYNLIB_HANDLE;
#endif

    class _OgreExport DynLib : public DynLibAlloc
    {
    private:
        String mName;
        /// Gets the last loading error
        String dynlibError(void);
    public:
        DynLib( const String& name );
        ~DynLib();

        void load();
        void unload();
        const String& getName(void) const { return mName; }

        void* getSymbol( const String& strName ) const throw();
    private:
        /// Handle to the loaded library.
        DYNLIB_HANDLE mInst;
    };

DYNLIB_HANDLE 是跨平台句柄:Windows 下是 HINSTANCE*,其余平台是 void*(对应 dlopen 返回的 void*)。mName 记录库名,getSymbol 做符号查找,找不到返回 nullptr。

符号解析:从名字到函数地址

DynLib::getSymbol 底层按平台调用 GetProcAddress 或 dlsym。对 OGRE 而言,每个插件动态库必须导出两个固定符号:

  • dllStartPlugin——加载时调用,内部必须调 Root::installPlugin;
  • dllStopPlugin——卸载时调用,内部必须调 Root::uninstallPlugin。

这两个符号的名字是约定契约。OgreRoot.cpp 的 loadPlugin 演示了查找与调用:

// OgreMain/src/OgreRoot.cpp:Root::loadPlugin(v14.6.3 源码摘录,已删减)
        // Load plugin library
        DynLib* lib = DynLibManager::getSingleton().load( pluginName );
        // Store for later unload
        // Check for existence, because if called 2+ times DynLibManager returns existing entry
        if (std::find(mPluginLibs.begin(), mPluginLibs.end(), lib) == mPluginLibs.end())
        {
            mPluginLibs.push_back(lib);

            // Call startup function
            DLL_START_PLUGIN pFunc = (DLL_START_PLUGIN)lib->getSymbol("dllStartPlugin");

            if (!pFunc)
                OGRE_EXCEPT(Exception::ERR_ITEM_NOT_FOUND, "Cannot find symbol dllStartPlugin in library " + pluginName,
                    "Root::loadPlugin");

            // This must call installPlugin
            pFunc();
        }

三个要点:

  1. 重复加载去重:DynLibManager::load 对同名库返回既有条目,mPluginLibs 再查一次,确保同一动态库只启动一次插件;
  2. 符号缺失即异常:getSymbol("dllStartPlugin") 返回 nullptr 时,抛出 ERR_ITEM_NOT_FOUND,指明「找不到 dllStartPlugin」;
  3. 契约注释:// This must call installPlugin——pFunc() 是插件自己的入口,它内部负责调 Root::installPlugin。

DLL_START_PLUGIN 是一个函数指针类型,指向无参无返回的函数。插件实现方要写:

extern "C" void dllStartPlugin(void) {
    // 创建插件对象并交给 Root 管理
    Root::getSingleton().installPlugin(new MyPlugin);
}

extern "C" 保证符号不被 C++ 名称修饰(mangling),这样 dlsym("dllStartPlugin") 才能精确匹配。

加载流程总览

loadPlugin("RenderSystem_Vulkan")
  └→ DynLibManager::load(name)      —— dlopen/LoadLibrary
       └→ getSymbol("dllStartPlugin") —— dlsym/GetProcAddress
            └→ pFunc()                —— 插件内调 installPlugin
                 └→ installPlugin(plugin) —— 进 mPlugins,调 install()

卸载是镜像流程:unloadPlugin 找 dllStopPlugin 调用,再 DynLibManager::unload 释放动态库。

源码定位

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

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

下面用符号表复现「名字 → 地址」的查找机制与缺失语义。它与 src/03-2-dynlib-load.cpp 逐字节一致:

// file: src/03-2-dynlib-load.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/03-2-dynlib-load.cpp -o bin/03-2-dynlib-load && ./bin/03-2-dynlib-load
//
// 复现 OgreDynLib 的符号查找机制与 Root::loadPlugin 的 dllStartPlugin 流程。
// 真实实现用 dlopen/dlsym;这里用符号表模拟「名字 → 地址」查找,机制等价。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cstdio>
#include <map>
#include <string>
#include <vector>

namespace ogre_repro {

typedef void* DYNLIB_HANDLE;

// 对应 OgrePlugin.h 的导出函数类型
typedef void (*DLL_START_PLUGIN)(void);
typedef void (*DLL_STOP_PLUGIN)(void);

// 对应 OgreDynLib:持有一个名字与句柄,按符号名取地址
class DynLib {
 public:
  explicit DynLib(const std::string& name)
      : mName(name), mInst(reinterpret_cast<DYNLIB_HANDLE>(this)) {
    symbols["dllStartPlugin"] = reinterpret_cast<void*>(&startThunk);
    symbols["dllStopPlugin"] = reinterpret_cast<void*>(&stopThunk);
  }
  const std::string& getName() const { return mName; }
  // 对应 DynLib::getSymbol:找不到返回 nullptr
  void* getSymbol(const std::string& strName) const {
    auto it = symbols.find(strName);
    return it == symbols.end() ? nullptr : it->second;
  }

  static void startThunk() { called.push_back("dllStartPlugin"); }
  static void stopThunk() { called.push_back("dllStopPlugin"); }
  static std::vector<std::string> called;

 private:
  std::string mName;
  DYNLIB_HANDLE mInst;
  std::map<std::string, void*> symbols;
};
std::vector<std::string> DynLib::called;

// 对应 Root::loadPlugin 的核心动作:找 dllStartPlugin 并调用
bool startPlugin(DynLib& lib) {
  DLL_START_PLUGIN pFunc = (DLL_START_PLUGIN)lib.getSymbol("dllStartPlugin");
  if (!pFunc) return false;  // 对应 OGRE_EXCEPT ERR_ITEM_NOT_FOUND
  pFunc();
  return true;
}

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  DynLib lib("RenderSystem_Vulkan");
  CHECK(lib.getName() == "RenderSystem_Vulkan");

  // dllStartPlugin / dllStopPlugin 一定存在
  CHECK(lib.getSymbol("dllStartPlugin") != nullptr);
  CHECK(lib.getSymbol("dllStopPlugin") != nullptr);
  // 不存在的符号返回 nullptr
  CHECK(lib.getSymbol("no_such_symbol") == nullptr);

  CHECK(startPlugin(lib));
  CHECK(DynLib::called.back() == "dllStartPlugin");

  std::printf("loaded %s, symbols: dllStartPlugin/dllStopPlugin\n",
              lib.getName().c_str());
  return lab::report("03-2 插件系统:DynLib 动态加载");
}

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

小结

  • DynLib 封装动态库句柄,getSymbol 按名取地址,跨平台统一 DYNLIB_HANDLE。
  • 每个插件必须导出 dllStartPlugin/dllStopPlugin,extern "C" 避免名称修饰。
  • loadPlugin 查 dllStartPlugin,缺失抛 ERR_ITEM_NOT_FOUND;重复加载去重。
  • 符号查找机制等价于 dlopen/dlsym,lab 用符号表复现。

阅读导航:上一节:3.1 OgrePlugin 接口与插件职责 · 下一节:3.3 插件安装、初始化与注册序 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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