《OGRE 3D 渲染引擎原理与架构》1.2 动态库加载

DynLib 封装动态库的跨平台加载:三个 DYNLIB 宏把 dlopen/LoadLibrary 收敛成统一接口,load() 先按平台补全后缀(.dll/.so.X.Y/.dylib/.js)再加载,getSymbol 用 dlsym/GetProcAddress 取函数地址。lab 复现后缀补全决策与加载/取符号/卸载。

1.2 动态库加载

1.1 讲了插件要实现的接口,但插件通常编译成 DLL / Shared Object,Root::loadPlugin 拿到的是一个库文件名。OGRE 用 DynLib 这一层薄薄的封装把「在不同操作系统上打开一个动态库」收敛成三个宏加三个方法。这一节看 OgreDynLib 的真实实现:跨平台宏、按平台补后缀、load/unload/getSymbol。

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

卷一 3.x 提到 DynLibManager 负责缓存与销毁 DynLib;这里剖析 DynLib 本身——OgreDynLib.h 的类契约与 OgreDynLib.cpp 的跨平台实现,是 1.3 写自定义插件骨架的前置。

DynLib:一个名字 + 一个句柄

头文件里的类很小,成员只有两个:名字 mName 和句柄 mInst。句柄类型也按平台定义:

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

        /** Load the library
        */
        void load();
        /** Unload the library
        */
        void unload();
        /// Get the name of the library
        const String& getName(void) const { return mName; }

        void* getSymbol( const String& strName ) const throw();

    private:
        /// Handle to the loaded library.
        DYNLIB_HANDLE mInst;
    };

Windows 上句柄是 HINSTANCE__*(LoadLibrary 返回的库句柄),POSIX 上是裸 void*(dlopen 的句柄)。类把平台差异藏起来,外部只看到 load/unload/getSymbol。

跨平台宏:三个宏收敛所有差异

OgreDynLib.cpp 开头用条件编译把四个平台家族的加载原语收敛成三个宏:

// OgreMain/src/OgreDynLib.cpp:DYNLIB 宏(v14.6.3 源码摘录,已删减)
#if OGRE_PLATFORM == OGRE_PLATFORM_WIN32
#    define DYNLIB_LOAD( a ) dynLibLoad( a ) // we can not use LOAD_WITH_ALTERED_SEARCH_PATH with relative paths
#    define DYNLIB_GETSYM( a, b ) GetProcAddress( a, b )
#    define DYNLIB_UNLOAD( a ) !FreeLibrary( a )
#elif OGRE_PLATFORM == OGRE_PLATFORM_WINRT
#    define DYNLIB_LOAD( a ) LoadPackagedLibrary( stringToWstring(a).c_str(), 0 )
#    define DYNLIB_GETSYM( a, b ) GetProcAddress( a, b )
#    define DYNLIB_UNLOAD( a ) !FreeLibrary( a )
#elif OGRE_PLATFORM == OGRE_PLATFORM_LINUX || OGRE_PLATFORM == OGRE_PLATFORM_ANDROID || OGRE_PLATFORM == OGRE_PLATFORM_EMSCRIPTEN
#    define DYNLIB_LOAD( a ) dlopen( a, RTLD_LAZY | RTLD_GLOBAL)
#    define DYNLIB_GETSYM( a, b ) dlsym( a, b )
#    define DYNLIB_UNLOAD( a ) dlclose( a )
#elif OGRE_PLATFORM == OGRE_PLATFORM_APPLE || OGRE_PLATFORM == OGRE_PLATFORM_APPLE_IOS
#    define DYNLIB_LOAD( a ) mac_loadDylib( a )
#    define FRAMEWORK_LOAD( a ) mac_loadFramework( a )
#    define DYNLIB_GETSYM( a, b ) dlsym( a, b )
#    define DYNLIB_UNLOAD( a ) dlclose( a )
#endif

每个平台只改这三个宏,DynLib 的实现体就完全统一。注意 Linux 系 dlopen(a, RTLD_LAZY | RTLD_GLOBAL)——惰性解析符号、全局符号可见;Apple 系额外有 FRAMEWORK_LOAD(.framework 包)。

load():先补后缀,再加载

load() 的实现分两步:先把平台专属后缀补到文件名上,再调用 DYNLIB_LOAD:

// OgreMain/src/OgreDynLib.cpp:DynLib::load(v14.6.3 源码摘录,已删减)
    void DynLib::load()
    {
        String name = mName;
#if OGRE_PLATFORM == OGRE_PLATFORM_EMSCRIPTEN
        if (name.find(".js") == String::npos)
            name += ".js";
#elif OGRE_PLATFORM == OGRE_PLATFORM_LINUX
        // dlopen() does not add .so to the filename, like windows does for .dll
        if (name.find(".so") == String::npos)
        {
            name += StringUtil::format(".so.%d.%d", OGRE_VERSION_MAJOR, OGRE_VERSION_MINOR);
        }
#elif OGRE_PLATFORM == OGRE_PLATFORM_APPLE
        // dlopen() does not add .dylib to the filename, like windows does for .dll
        if(name.substr(name.find_last_of(".") + 1) != "dylib")
            name += ".dylib";
#elif OGRE_PLATFORM == OGRE_PLATFORM_WIN32 || OGRE_PLATFORM == OGRE_PLATFORM_WINRT

        // Although LoadLibraryEx will add .dll itself when you only specify the library name,
        // if you include a relative path then it does not. So, add it to be sure.
        if(name.substr(name.find_last_of(".") + 1) != "dll")
            name += OGRE_BUILD_SUFFIX ".dll";
#endif
        // Log library load
        LogManager::getSingleton().logMessage("Loading library " + name);

        mInst = (DYNLIB_HANDLE)DYNLIB_LOAD( name.c_str() );
#if OGRE_PLATFORM == OGRE_PLATFORM_APPLE
        if(!mInst)
        {
            name = mName;
            if(name.substr(name.find_last_of(".") + 1) != "framework")
                name += ".framework";
            // Try again as a framework
            mInst = (DYNLIB_HANDLE)FRAMEWORK_LOAD( name );
        }
#endif
        if( !mInst )
            OGRE_EXCEPT(
                Exception::ERR_INTERNAL_ERROR, 
                "Could not load dynamic library " + mName + 
                ".  System Error: " + dynlibError(),
                "DynLib::load" );
    }

后缀决策表:

平台补上的后缀说明
Emscripten.jsWebAssembly 模块
Linux/Android.so.<MAJOR>.<MINOR>dlopen 不会像 Windows 那样自动加后缀,还要带上版本号(14.6)
Apple.dylib,失败再试 .frameworkdlopen 不自动加后缀
Windows<OGRE_BUILD_SUFFIX>.dllLoadLibraryEx 对相对路径不加 .dll

规则统一是「先判断后缀是否已在,没有才补」。加载失败抛出 ERR_INTERNAL_ERROR 异常,消息里带上 dynlibError()(dlerror() / GetLastError() 的系统错误文本)。

unload 对称地调用 DYNLIB_UNLOAD,失败同样抛异常;getSymbol 用 DYNLIB_GETSYM(mInst, strName) 取符号地址,找不到返回 NULL:

// OgreMain/src/OgreDynLib.cpp:DynLib::unload / getSymbol(v14.6.3 教学示意,参照上游同名实现,已删减)
    void DynLib::unload()
    {
        // Log library unload
        LogManager::getSingleton().logMessage("Unloading library " + mName);

        if( DYNLIB_UNLOAD( mInst ) )
        {
            OGRE_EXCEPT(...);
        }

    }
    ...
    void* DynLib::getSymbol( const String& strName ) const throw()
    {
        return (void*)DYNLIB_GETSYM( mInst, strName.c_str() );
    }

源码定位

  • OgreMain/include/OgreDynLib.h :DYNLIB_HANDLE(46-50)、DynLib 类(59-102)、getName(83)、getSymbol(96)
  • OgreMain/src/OgreDynLib.cpp :DYNLIB 宏(32-49)、DynLib::load(107-150)、DynLib::unload(153-167)、getSymbol(170-173)、dynlibError(175-227)

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

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

下面用纯 C++ 复现后缀补全决策与加载/取符号/卸载的调用语义。它与 src/01-2-dynlib-loading.cpp 逐字节一致:

// file: src/01-2-dynlib-loading.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/01-2-dynlib-loading.cpp -o bin/01-2-dynlib-loading && ./bin/01-2-dynlib-loading
//
// 复现动态库加载的后缀补全与 load/unload/getSymbol 语义
//   (对应 OgreMain/src/OgreDynLib.cpp 107-173 的 DynLib::load/unload/getSymbol,
//    32-49 的 DYNLIB 平台宏):
//   各平台先补后缀再加载:Emscripten .js / Linux .so.MAJ.MIN / Apple .dylib / Windows .dll;
//   已有后缀不补;加载失败抛异常;getSymbol 找不到返回空。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cstdint>
#include <stdexcept>
#include <string>

namespace ogre_repro {

enum class Platform { Windows, Linux, Apple, Emscripten };

// 对应 OgreDynLib.cpp 107-129:按平台补全后缀,已有则不补
std::string addLibrarySuffix(const std::string& name, Platform plat, uint32_t major,
                             uint32_t minor) {
  std::string out = name;
  switch (plat) {
    case Platform::Emscripten:
      if (out.find(".js") == std::string::npos) out += ".js";
      break;
    case Platform::Linux:
      if (out.find(".so") == std::string::npos) {
        out += ".so." + std::to_string(major) + "." + std::to_string(minor);
      }
      break;
    case Platform::Apple:
      if (out.substr(out.find_last_of(".") + 1) != "dylib") out += ".dylib";
      break;
    case Platform::Windows:
      if (out.substr(out.find_last_of(".") + 1) != "dll") out += ".dll";
      break;
  }
  return out;
}

// 对应 OgreDynLib.h 59-:模拟动态库(记录调用,模拟失败)
class SimDynLib {
 public:
  explicit SimDynLib(std::string name) : mName(std::move(name)) {}
  void load() {
    if (mLoadFails) throw std::runtime_error("could not load: " + mName);
    mLoaded = true;
    mLoadCount++;
  }
  void unload() {
    mLoaded = false;
    mUnloadCount++;
  }
  // 对应 getSymbol:已知符号返回非空,未知返回空
  void* getSymbol(const std::string& sym) const {
    if (!mLoaded || sym != "dllStartPlugin") return nullptr;
    return reinterpret_cast<void*>(1);
  }
  const std::string& getName() const { return mName; }

  bool mLoaded = false;
  int mLoadCount = 0;
  int mUnloadCount = 0;
  bool mLoadFails = false;
  std::string mName;
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  // 后缀补全:Windows 补 .dll
  CHECK_EQ(addLibrarySuffix("RenderSystem_GL", Platform::Windows, 14, 6),
           "RenderSystem_GL.dll");
  // 已有 .dll 不重复补
  CHECK_EQ(addLibrarySuffix("Ogre.dll", Platform::Windows, 14, 6), "Ogre.dll");
  // Linux 补 .so.14.6
  CHECK_EQ(addLibrarySuffix("Plugin_Assimp", Platform::Linux, 14, 6),
           "Plugin_Assimp.so.14.6");
  // 已有 .so 不补
  CHECK_EQ(addLibrarySuffix("Plugin.so", Platform::Linux, 14, 6), "Plugin.so");
  // Apple 补 .dylib
  CHECK_EQ(addLibrarySuffix("Sample", Platform::Apple, 14, 6), "Sample.dylib");
  // 已有 .dylib 不补
  CHECK_EQ(addLibrarySuffix("libOgre.dylib", Platform::Apple, 14, 6), "libOgre.dylib");
  // Emscripten 补 .js
  CHECK_EQ(addLibrarySuffix("Ogre", Platform::Emscripten, 14, 6), "Ogre.js");

  // load/unload/getSymbol 语义
  SimDynLib lib("Plugin_Assimp");
  CHECK(!lib.mLoaded);
  lib.load();
  CHECK(lib.mLoaded);
  CHECK_EQ(lib.mLoadCount, 1);
  // 取到符号(模拟 dllStartPlugin)
  CHECK(lib.getSymbol("dllStartPlugin") != nullptr);
  // 未知符号返回空
  CHECK(lib.getSymbol("nope") == nullptr);
  lib.unload();
  CHECK(!lib.mLoaded);
  CHECK_EQ(lib.mUnloadCount, 1);
  // 卸载后符号不可取
  CHECK(lib.getSymbol("dllStartPlugin") == nullptr);

  // 加载失败抛异常(对应 OGRE_EXCEPT)
  SimDynLib bad("Missing.so");
  bad.mLoadFails = true;
  bool threw = false;
  try {
    bad.load();
  } catch (const std::runtime_error&) {
    threw = true;
  }
  CHECK(threw);
  CHECK(!bad.mLoaded);

  return lab::report("1.2 动态库加载");
}

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

小结

  • DynLib 用 mName + mInst(DYNLIB_HANDLE)两个成员封装一个动态库。
  • 三个 DYNLIB_* 宏把 dlopen/LoadLibrary 等平台原语收敛成统一接口。
  • load() 先按平台补后缀(.js/.so.MAJ.MIN/.dylib/.dll)再加载,已有后缀不补。
  • 加载失败抛 ERR_INTERNAL_ERROR,消息带系统错误文本;getSymbol 找不到返回 NULL。
  • Apple 系加载失败会回退尝试 .framework。

阅读导航:上一节:1.1 插件接口 · 下一节:1.3 自定义插件骨架 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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