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();
}
三个要点:
- 重复加载去重:
DynLibManager::load对同名库返回既有条目,mPluginLibs再查一次,确保同一动态库只启动一次插件; - 符号缺失即异常:
getSymbol("dllStartPlugin")返回nullptr时,抛出ERR_ITEM_NOT_FOUND,指明「找不到 dllStartPlugin」; - 契约注释:
// 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 释放动态库。
源码定位
OgreMain/include/OgreDynLib.h:DynLib 类、DYNLIB_HANDLE、getSymbolOgreMain/src/OgreRoot.cpp:Root::loadPlugin(getSymbol("dllStartPlugin")+ERR_ITEM_NOT_FOUND)、Root::unloadPlugin(dllStopPlugin)- 符号契约:
dllStartPlugin/dllStopPlugin
上游引用固定到 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 插件安装、初始化与注册序 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。