plugin.h 文件参考

Strongly-typed shared-library plugin loader with ID and version verification. 更多...

#include <cstdint>
#include <deque>
#include <memory>
#include <string>
#include <string_view>
#include "./logger.h"
#include "./macros.h"
#include "./name_detector.h"

plugin.h 的引用(Include)关系图:

此图展示该文件直接或间接的被哪些文件引用了:

浏览源代码.

类
class	vlink::Plugin
	Manager that loads, tracks and unloads shared-library plugins by interface type. 更多...

命名空间
	vlink

宏定义
#define	VLINK_PLUGIN_CREATE_FUNC_NAME   vlink_plugin_create
	Symbol name of the plugin construction entry point exported by VLINK_PLUGIN_DECLARE. 更多...
#define	VLINK_PLUGIN_DESTROY_FUNC_NAME   vlink_plugin_destroy
	Symbol name of the plugin destruction entry point exported by VLINK_PLUGIN_DECLARE. 更多...
#define	VLINK_PLUGIN_EXPORT   __attribute__((visibility("default")))
	Macro Definitions 更多...
#define	VLINK_PLUGIN_REGISTER(InterfaceType)
	Declares a plugin's identity from the demangled name of its abstract interface. 更多...
#define	VLINK_PLUGIN_REGISTER_BY_ID(InterfaceType, PluginID)
	Declares a plugin's identity from an explicit literal string. 更多...
#define	VLINK_PLUGIN_DECLARE(ImplementType, VersionMajor, VersionMinor)
	Emits the extern "C" construction and destruction entry points exported by a plugin module. 更多...

详细描述

Strongly-typed shared-library plugin loader with ID and version verification.

vlink::Plugin wraps the host platform's dynamic-library API (dlopen / LoadLibrary) and resolves the vlink_plugin_create / vlink_plugin_destroy entry points exported by every plugin built with VLINK_PLUGIN_DECLARE. Plugin implementations are bound to an abstract interface type so the loader can verify the ABI contract before any virtual call crosses the library boundary.

Plugin lifecycle observed by the loader:

*     load() ---> open() ---> create() ---> in use ---+
*       ^                                             |
*       |                                             v
*     clear() <--- close() <--- destroy() <--- unload()
* 

Interface / implementation contract:

Side	Required macro	Result
Abstract interface	VLINK_PLUGIN_REGISTER	Plugin ID = demangled name
Abstract interface	VLINK_PLUGIN_REGISTER_BY_ID(_, "id")	Plugin ID = literal string
Concrete impl .cc	VLINK_PLUGIN_DECLARE(Impl, major, minor)	Exports create/destroy ABI

Version verification

process_plugin_internal() runs inside the plugin entry point and verifies that the plugin ID matches and that the plugin's major version equals the host's required major and the plugin's minor is no lower than the host's required minor. Mismatches return nullptr from vlink_plugin_create() so an incompatible binary never crosses the vtable boundary.

Example

// Interface (header):
class MyPlugin {
  VLINK_PLUGIN_REGISTER(MyPlugin)
 public:
  virtual ~MyPlugin() = default;
  virtual void do_work() = 0;
};
 
// Implementation (.cc):
class MyPluginImpl : public MyPlugin {
  VLINK_PLUGIN_REGISTER(MyPlugin)
 public:
  void do_work() override { ... }
};
VLINK_PLUGIN_DECLARE(MyPluginImpl, 1, 0)
 
// Host:
vlink::Plugin plugin;
if (auto impl = plugin.load<MyPlugin>("my_plugin_impl", 1, 0)) {
  impl->do_work();
}

宏定义说明

VLINK_PLUGIN_CREATE_FUNC_NAME

#define VLINK_PLUGIN_CREATE_FUNC_NAME   vlink_plugin_create

Symbol name of the plugin construction entry point exported by VLINK_PLUGIN_DECLARE.

VLINK_PLUGIN_DECLARE

#define VLINK_PLUGIN_DECLARE	(		ImplementType,
			VersionMajor,
			VersionMinor
	)

Emits the extern "C" construction and destruction entry points exported by a plugin module.

The construction entry point validates the plugin ID and major/minor version against the caller's expectations via Plugin::process_plugin_internal() and returns a new instance of ImplementType only when the contract holds. The destruction entry point deletes the implementation pointer.

参数

ImplementType	Concrete class implementing the abstract interface.
VersionMajor	Major version exposed by this plugin binary.
VersionMinor	Minor version exposed by this plugin binary.

VLINK_PLUGIN_DESTROY_FUNC_NAME

#define VLINK_PLUGIN_DESTROY_FUNC_NAME   vlink_plugin_destroy

Symbol name of the plugin destruction entry point exported by VLINK_PLUGIN_DECLARE.

VLINK_PLUGIN_EXPORT

#define VLINK_PLUGIN_EXPORT   __attribute__((visibility("default")))

Macro Definitions

VLINK_PLUGIN_REGISTER

#define VLINK_PLUGIN_REGISTER

(

InterfaceType

)

值:

 public:                                                                                                             \
  static constexpr std::string_view get_plugin_id() {                                                                \
    static_assert(std::is_abstract_v<InterfaceType>, "Plugin interface must be abstract class.");                    \
    static_assert(std::has_virtual_destructor_v<InterfaceType>, "Plugin interface must have a virtual destructor."); \
    return vlink::NameDetector::get<InterfaceType>();                                                                \
  }

Declares a plugin's identity from the demangled name of its abstract interface.

Injects a static constexpr get_plugin_id() member that returns the demangled name of InterfaceType. Static assertions enforce that the interface is abstract and exposes a virtual destructor so polymorphic delete across the library boundary is well defined.

参数

InterfaceType

Abstract interface class the plugin implements.

VLINK_PLUGIN_REGISTER_BY_ID

#define VLINK_PLUGIN_REGISTER_BY_ID	(		InterfaceType,
			PluginID
	)

值:

 public:                                                                                                             \
  static constexpr std::string_view get_plugin_id() {                                                                \
    static_assert(std::is_abstract_v<InterfaceType>, "Plugin interface must be abstract class.");                    \
    static_assert(std::has_virtual_destructor_v<InterfaceType>, "Plugin interface must have a virtual destructor."); \
    return PluginID;                                                                                                 \
  }

Declares a plugin's identity from an explicit literal string.

Same contract as VLINK_PLUGIN_REGISTER but get_plugin_id() returns PluginID instead of the demangled type name, which is useful when the plugin ID must remain stable across refactors that rename the interface class.

参数

InterfaceType	Abstract interface class the plugin implements.
PluginID	Literal string used as the plugin identity.