10分钟带你了解轻量级插件框架x3py

吴尼玛

写在前面

  • 由于本人目前主要从事的是Windows客户端开发方面的工作,所以本文介绍x3py的侧重点也是从客户端程序开发者方面叙述的。本文主要参考整理自x3py的官方Wiki,修正了一些官方示例中的错误。有兴趣的同学可以直接阅读原文。

设计目的

  • x3py 作为一个轻量级的C++插件框架,面向C++开发人员,首要目标是能快速容易的开发出中小型的软件、软件以插件形式模块化设计。其插件既可灵活组合到各个系统,又能单独拆开使用和测试。
  • 另外,x3py 可在Win/Linux/MacOSX等平台上编译运行,可使用VS或GCC编译,具备基本的跨平台兼容性。框架力求最简化,核心设计目标为“实用、简洁”。

客户端开发引入此框架目的

  • 我们客户端方面引入x3py主要是因为他即可以实现类似COM组件开发效果,又具有跨平台兼容性。这样我们可以很方便的实现一个跨平台的组件化客户端开发框架。在引入x3py后,我们实现的核心框架层次从下到上可以如下所示。

    • FrameWork:最底层的基础框架层,提供最基本的公共函数,如日志、网络处理、基础ui框架等。x3py框架属于这一层。
    • MiddlePlugin:中间插件层,主要封装了提供给应用层使用的公共插件,提供公共的接口给应用层调用。在引入x3py使得客户端面向接口开发后,我们程序员的主要工作就在开发这些公共插件。
    • Application:应用层,应用层框架就比较简单了,主要负责插件的加载和接口调用,一些简单的ui处理等。

插件原理

  • 使用x3py所实现的C++插件,即可以是动态链接库文件(DLL/SO),也可以是可执行程序文件;通过在插件文件中实现统一的导出函数,使得其他模块可以自动通过这些导出函数访问其接口。

一、插件工作原理

插件原理图

  • 插件系统主要有两种使用形式,一是在C++的主程序或动态库中使用C++插件,另一种是在Python等其他编程语言中使用C++插件。
插件管理器(x3manager)
  • 首先,x3manager也是一个插件,按照统一标准实现了插件的导出函数。x3manager插件的主要作用是在多个插件之间进行中介联系,从而允许插件之间能够互相访问而不直接发生联系,各个插件动态库加载后自动向x3manager登记。例如要创建一个对象,通过插件管理器来查询是在哪个插件中实现了该类,从而创建出对象、访问接口功能。
  • 在x3py插件框架中,x3manager不负责插件动态库的加载管理,所以在C++的主程序或动态库中使用C++插件时,需要先加载各个插件动态库,然后就可使用插件接口。由于框架提供了多种加载方法,这样更灵活、职责更清晰。

二、插件调用过程

  • 在插件实现时,通过包含 pluginimpl.h 文件,自动实现了 x3InternalCreate、x3InitPlugin、x3FreePlugin、x3CreateObject 这四个导出函数,通过导出函数就可在插件之间建立联系。下面将说明这四个导出函数之间的联系。
1、加载插件过程

加载插件的序列图

  • 使用 x3LoadLibrary 函数加载动态库文件。使用此函数而不是WinAPI的 LoadLibraryA 函数,是为了能实现跨平台同时确保自动调用 x3InitPlugin 函数进行插件初始化。
  • x3InitPlugin 函数用于在插件加载时进行初始化、向管理器注册(x3RegisterPlugin)此插件的所有类ID(CLSID串)。通过在插件CPP文件中包含 pluginimpl.h 文件,自动实现了 x3InitPlugin。插件动态库被多次加载时不会多次重复初始化,这是在 x3InitPlugin 函数中通过计数来保证的。
  • x3InitializePlugin 函数由各个插件自行实现,用来完成附加的初始化操作,由 x3InitPlugin 函数调用。
2、卸载插件过程

卸载插件的序列图

  • 使用 x3FreeLibrary 函数卸载动态库文件。使用此函数而不是WinAPI的 FreeLibrary 函数,同样也是是为了能实现跨平台同时确保自动调用 x3FreePlugin 函数进行插件注销。
  • x3FreePlugin 函数用于在插件卸载时进行对象释放、向管理器注销(x3UnregisterPlugin)此插件的信息。通过在插件CPP文件中包含 pluginimpl.h 文件,自动实现了 x3FreePlugin。
  • x3UninitializePlugin 函数也是由各个插件自行实现,用来完成附加的资源释放操作,由 x3FreePlugin 函数调用。
3、创建插件接口指针过程

创建插件接口指针的序列图

  • 通过使用智能指针模板类 x3::Object 来创建插件接口指针,自动处理引用计数。
  • x3::Object模板类通过x3::createObject函数去调用 x3manager中的x3CreateObject 来创建对象。如果插件自身的 x3InternalCreate 不能创建对象,则再转给x3manager,由后者根据类ID查找对应插件,然后调用对应插件的 x3InternalCreate 函数。

如何使用插件接口

  • 使用接口比较简单,在C++代码中包含相应的接口头文件,然后使用智能指针模板类 x3::Object<Interface> 来创建对象或者从一个对象得到其他接口的对象。
  • 下面的例子说明了如何创建对象、从一个对象得到其他接口的对象、使用接口函数:
#include <plsimple/isimple.h>               // 包含接口文件
#include <plsimple/isimple2.h>              // 包含其他接口文件

int test()
{
    x3::Object<ISimple> obj(clsidSimple);     // 给定类ID创建对象

    if (obj)                  // 检查是否创建成功
    {
        obj->add(1, 2);       // 调用接口函数,就像普通指针一样
    }

    x3::Object<ISimple2> other(obj.p());  // 从已有对象得到其他接口的实例吗,p()是获取obj的接口类指针

    // other = obj.p();            // 除了拷贝构造,也可以使用赋值形式

    if (other.valid())  
    {
        std::vector<int> nums{1,2,3,4,5};
        other->add(nums);   // 调用新接口的函数
    }

    // 会自动释放对象
}
  • 对于函数返回值是接口对象或函数形参是接口对象的情况,为了避免在头文件中包含所用接口的头文件,可以使用 x3::AnyObject ,需要具体某个接口的对象时再转换。下面的例子就是插件的接口文件中 createSimple() 返回的是 x3::AnyObject,这样在此接口头文件中就可以不包含ISimple1的头文件:
#ifndef X3_EXAMPLE_ISIMPLE3_H
#define X3_EXAMPLE_ISIMPLE3_H

#include <objptr.h>

const char* const clsidSimple3 = "94071767-ba6b-4769-9eb4-2ebf469218f3";

class ISimple3 : public x3::IObject
{
    X3DEFINE_IID(ISimple3);

    // 形参用AnyObject可避免包含其他接口定义文件,可在注释中说明实际接口名
    virtual void useSimple(const x3::AnyObject& obj) = 0;

    // 返回值用AnyObject可避免包含其他接口定义文件,可在注释中说明实际接口名
    virtual x3::AnyObject createSimple() = 0;

    // 而不是 virtual x3::Object<ISimple1> createSimple() = 0;
};

#endif
  • 此函数的实现示例如下,其中包含了如何使用AnyObject得到特定接口对象的例子:
void CSimple::useSimple(const x3::AnyObject& obj)
{
    x3::Object<ISimple> myobj(obj);
    ASSERT(myobj);

    x3::Object<ISimple> sample(createSimple());
    ASSERT(sample);
}

x3::AnyObject CSimple::createSimple()
{
    return x3::Object<ISimple>(clsidSimple);
    // x3::Object<ISimple> simp(clsidSimple);
    // do something with simp
    // return simp;
}

如何加载插件

1、同时使用多个插件的简单加载方法

#include <portability/x3port.h>     // 相当于#include<windows.h>
#include <nonplugin/useplugins.h>   // 包含辅助加载类,一个工程内只能包含一次

int main()
{
    // 多个插件文件名,以NULL结尾
    const char* plugins[] = {
        "x3manager.pln", "plsimple.pln", "observerex.pln", NULL
    };
    // 自动加载和卸载插件,插件在程序文件的plugins子目录下
    x3::AutoLoadPlugins autoload(plugins, "plugins");

    // 可以使用接口了
    return test();
}

2、仅使用一个插件的简单加载方法

#include <portability/x3port.h>     // 相当于#include<windows.h>

// 插件在程序文件的plugins子目录下,如果不定义则插件与程序同目录
// 注意末尾有目录分隔符,在包含useplugin.h前定义,如果不定义则为默认的空串
#define PLUGIN_PATH  "plugins/"

// 要使用的插件文件名,没有目录和后缀名(.pln)
#define PLUGIN_NAME  "plsimple"

// 包含辅助加载类,一个工程内只能包含一次
#include <nonplugin/useplugin.h>

// 可以使用接口了
int main()
{
    return test();
}

3、遍历目录下的所有插件

#include <nonplugin/scanplugins.h>

int main()
{
    // 默认遍历 plugins 目录,加载其中的插件文件
    x3::loadPlugins();

    // 可以使用接口了
    int ret = test();

    // 卸载所有插件,后加载的先卸载
    x3::unloadPlugins();

    return ret;
}

4、原生加载方式

#include <portability/portimpl.h>

HMODULE modules[10] = { NULL };

int main()
{
    const char* plugins[] = { 
        "plugins/x3manager.pln", 
        "plugins/plsimple.pln", 
        "plugins/observerex.pln",
        NULL
    };
    int count = 0;

    for (int i = 0; plugins[i]; i++)
    {
        modules[count] = x3LoadLibrary(plugins[i]);
        if (modules[count])
            count++;
    }
    
    // 可以使用接口了
    int ret = test();

    while (--count >= 0)
    {
        x3FreeLibrary(modules[count]);
    }

    return ret;
}

namespace x3 {
class IObject;
bool createObject(const char* clsid, long iid, IObject** p)
{
    typedef bool (*F)(const char*, long, IObject**);
    F f = (F)GetProcAddress(modules[0], "x3CreateObject");
    return f && f(clsid, iid, p);
}
} // x3

5、静态链接库方式

这种方式使用的比较少,就不具体介绍了,官方有一个具体的Wiki介绍,有兴趣的同学可以自己看看看。

#include <portability/x3port.h>
#include <module/pluginimpl.h>
#define XUSE_LIB_PLUGIN
#include <module/modulemacro.h>
XDEFINE_EMPTY_MODULE()

#ifdef _MSC_VER
#pragma comment(lib, "libpln1.lib")
#endif

extern const x3::ClassEntry* const classes_libpln1;

const x3::ClassEntry* const x3::ClassEntry::classes[] = {
        s_classes, classes_libpln1, NULL
    };

// 可以使用接口了
int main()
{
    return test();
}
  • C++插件后缀名为 .pln ,而不是 .dll.so.plugin.dll ,其原因是在不同操作系统中用统一的后缀名,避免条件定义;同时避免与普通动态库混淆,这样遍历目录批量加载插件时可跳过普通动态库文件。
  • 在VS中,我们可以通过工程属性--链接器--输出文件来设置编译出的插件dll后缀名为 .pln

VS中后缀名设置

如何实现插件

一、定义接口

  • 首先定义接口类,此接口类从 x3::IObject 派生,包含纯虚函数,使用 X3DEFINE_IID(接口名) 定义接口ID。X3DEFINE_IIDx3::IObject 定义在 iobject.h 中,但通常我们包含 objptr.h 更方便些,下面是一个接口头文件isimple.h:
#ifndef X3_EXAMPLE_ISIMPLE_H
#define X3_EXAMPLE_ISIMPLE_H

#include <objptr.h>

class ISimple : public x3::IObject
{
    X3DEFINE_IID(ISimple);
    virtual int add(int a, int b) const = 0;
    virtual int subtract(int a, int b) const = 0;
};

#endif

二、定义类UID

  • 一个插件类如果要让外部模块能创建对象实例,需要指定插件类的全局唯一标识信息,一般采用GUID串来标识插件类。通常一个插件类UID常量可以定义成如下形式:
const char* const clsidSimple = "94071767-ba6b-4769-9eb4-2ebf469289f3";
  • 类UID既可以定义在单独的头文件中,也可以就定义在接口的头文件中。我们的习惯做法是:如果一个插件类定义了多个接口文件,则将类UID定义在单独的头文件中,之后每个接口文件包含此头文件;如果一个插件类仅定义了一个接口,为方便起见则将类UID就定义在接口的头文件中。

注意:类UID不可重复,否则将会覆盖已向管理器注册的类,导致其他模块无法创建原来类的接口对象。

三、实现接口

  • 接下来,我们来实现isimple.h中定义的接口,使用 X3BEGIN_CLASS_DECLARE 等宏来指定一个类实现了哪些接口。这里的CSimple是一个实现类的例子。其中构造函数和析构函数申明为保护函数,所有实现的接口函数申明为私有函数,这是推荐方式,但不是必须的。这样做是为了明确表明不允许直接实例化和delete销毁,也不允许直接调用实现类的接口函数。
#ifndef X3_EXAMPLE_SIMPLE_IMPL_H
#define X3_EXAMPLE_SIMPLE_IMPL_H

#include <plsimple/isimple.h>   // 包含接口定义

class CSimple : public ISimple  // 从接口派生
{
    X3BEGIN_CLASS_DECLARE(CSimple, clsidSimple) // 指定类ID
        X3DEFINE_INTERFACE_ENTRY(ISimple)       // 指定实现的接口
    X3END_CLASS_DECLARE()
protected:
    CSimple();
    virtual ~CSimple();

private:
    virtual int add(int a, int b) const;
    virtual int subtract(int a, int b) const;
};

#endif
  • 一个实现类可以实现一个或多个接口,还可以从已有的实现类派生以便继承所有的接口实现(实现继承),或者重载已实现的接口函数。下面是实现继承的一个例子:
#ifndef X3_EXAMPLE_SIMPLE_IMPL2_H
#define X3_EXAMPLE_SIMPLE_IMPL2_H

#include "plsimple.h"           // 包含基实现类
#include <plsimple/isimple2.h>  // 包含附加接口
#include <plsimple/isimple3.h>

class CSimple2
    : public CSimple            // 从基实现类派生
    , public ISimple2           // 从附加接口派生
    , public ISimple3
{
    X3BEGIN_CLASS_DECLARE(CSimple2, clsidSimple)
        X3DEFINE_INTERFACE_ENTRY(ISimple2) // 指定实现的接口
        X3DEFINE_INTERFACE_ENTRY(ISimple3)
        X3USE_INTERFACE_ENTRY(CSimple)     // 继承已实现的所有接口
    X3END_CLASS_DECLARE()
protected:
    CSimple2() {}

private:
    virtual int add(const std::vector<int>& nums) const;
    virtual x3::AnyObject createSimple();
};

#endif

四、注册实现类

  • 因为插件中的实现类一般不直接用于实例化对象,而是通过 x3::Object 智能指针模板类来创建对象的。所以,我们需要在插件中注册可供实例化的类以及说明此类是否是单例。
  • 注册实现类的通常做法是在工程的一个.cpp文件(通常为 module.cpp)中,包含 pluginimpl.h 和 modulemacro.h 文件,然后使用 XBEGIN_DEFINE_MODULE 等宏来申明注册哪些实现类。下面是示例:
#include <module/plugininc.h>
#include <module/pluginimpl.h>      // 实现插件的导出函数
#include <module/modulemacro.h>     // 注册实现类的宏定义

#include "plsimple.h"               // 包含实现类

XBEGIN_DEFINE_MODULE()
    XDEFINE_CLASSMAP_ENTRY(CSimple) // 注册普通实现类或单实例类
    XDEFINE_CLASSMAP_ENTRY_Singleton(YourSingletonClass)
XEND_DEFINE_MODULE_DLL()            // 插件动态库

OUTAPI bool x3InitializePlugin()    // 插件加载时执行,用于额外初始化
{
    return true;
}

OUTAPI void x3UninitializePlugin()  // 插件卸载时执行,用于释放额外数据
{
}
  • 其中 x3InitializePlugin()x3UninitializePlugin() 函数由自己实现,用于额外的初始化和释放操作。这两个函数可以在module.cpp或其他.cpp文件中实现,但是在同一个插件中只能实现一次。
  • 如果某个插件不实现任何接口,只使用其他插件的接口,则可以在module.cpp中使用下面更简单的形式:
#include <module/pluginimpl.h>
#include <module/modulemacro.h>
XDEFINE_EMPTY_MODULE()
  • 由于在VS的.cpp文件中一般都会包含stdafx.h,因此 module/plugininc.h 文件无论包含与否都可。使用VS时可以不需要 module/plugininc.h 和 interfacecoreportability 目录。

事件驱动机制(Observer)

x3py官方也提供了事件驱动机制,其的主要用途是在不同模块之间实现松耦合(相互隔离)、将复杂的调用流程分离为多个独立操作片断、实现功能扩展点。但其实现比较简单,只支持最多两个参数。所以,我们可以引入信号槽或者其他方法来替换。

阅读 808

吴尼玛的技术后花园
学技术简单记,吴尼玛带你记笔记。

学技术简单记,吴尼玛带你记笔记。

15 声望
2 粉丝
0 条评论
你知道吗?

学技术简单记,吴尼玛带你记笔记。

15 声望
2 粉丝
宣传栏