写在前面

• 由于本人目前主要从事的是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;
}

如何加载插件

• 官方提供了详细示例：source/example/consoledemo/main.cpp，其中有五种加载插件的方式。例子中在test函数中调用了插件接口。

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_IID 和 x3::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 和 interface\core\portability 目录。

事件驱动机制（Observer）

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