Manager that loads, tracks and unloads shared-library plugins by interface type. More...

#include <plugin.h>

Collaboration diagram for vlink::Plugin:

Public Types
using	Handle = void *
	Opaque handle to a loaded shared library; treated as a token by the public API. More...

Public Member Functions
	Plugin ()
	Constructs an empty plugin manager with no libraries loaded. More...

	~Plugin ()
	Destroys the plugin manager and unloads every still-resident library via `clear()`. More...

void	set_log_level (Logger::Level level)
	Sets the verbosity level used for plugin diagnostic messages. More...

Logger::Level	get_log_level () const
	Returns the verbosity level currently used for plugin diagnostics. More...

template<class T >
std::shared_ptr< T >	load (const std::string &lib_name, uint16_t version_major, uint16_t version_minor, const std::string &dir_name="", const std::deque< std::string > &search_paths=default_search_path(), const std::string &function_name=VLINK_MACRO_STRING_GET(VLINK_PLUGIN_CREATE_FUNC_NAME))
	Loads a shared library that implements interface `T` and returns a tracked handle. More...

template<class T >
bool	unload (const std::string &lib_name)
	Removes a previously loaded plugin from the registry. More...

template<class T >
bool	has_loaded (const std::string &lib_name)
	Reports whether a plugin for interface `T` is currently registered. More...

template<class T >
std::string	get_plugin_complex_id (const std::string &lib_name)
	Builds the composite key used internally to identify a (library, interface) pair. More...

void	clear ()
	Unloads every library currently tracked by this manager. More...

Static Public Member Functions
static std::deque< std::string >	default_search_path ()
	Returns the default ordered search path used when locating plugin libraries. More...

static bool	process_plugin_internal (const std::string &lib_name, const std::string &local_plugin_id, uint16_t local_version_major, uint16_t local_version_minor, const std::string &target_plugin_id, uint16_t target_version_major, uint16_t target_version_minor, uint8_t log_level)
	Internal version/ID gate invoked from the `VLINK_PLUGIN_DECLARE` entry point. More...

Detailed Description

Manager that loads, tracks and unloads shared-library plugins by interface type.

A single Plugin instance can host multiple distinct interface types simultaneously and tracks each loaded library so repeated load() calls share the underlying dlopen handle. All operations are thread safe through the internal implementation.

Member Typedef Documentation

◆ Handle

using vlink::Plugin::Handle = void*

Opaque handle to a loaded shared library; treated as a token by the public API.

Constructor & Destructor Documentation

◆ Plugin()

vlink::Plugin::Plugin ( )

Constructs an empty plugin manager with no libraries loaded.

◆ ~Plugin()

vlink::Plugin::~Plugin ( )

Destroys the plugin manager and unloads every still-resident library via clear().

Member Function Documentation

◆ clear()

void vlink::Plugin::clear ( )

Unloads every library currently tracked by this manager.

◆ default_search_path()

static std::deque<std::string> vlink::Plugin::default_search_path ( )

static

Returns the default ordered search path used when locating plugin libraries.

The list contains, in priority order, directories from VLINK_PLUGIN_DIR (comma or whitespace separated), the current working directory, the executable directory, and the system library directories appropriate for the platform.

Returns: Deque of directory paths searched left to right.

◆ get_log_level()

Logger::Level vlink::Plugin::get_log_level ( ) const

Returns the verbosity level currently used for plugin diagnostics.

Returns: Current logger level.

◆ get_plugin_complex_id()

template<class T >

std::string vlink::Plugin::get_plugin_complex_id ( const std::string & lib_name )

inline

Builds the composite key used internally to identify a (library, interface) pair.

The key has the form lib_name + "@" + T::get_plugin_id() so the same shared library can be loaded twice when consumed via two different interfaces.

Template Parameters

T	Interface type.

Parameters

lib_name Library file name.

Returns: Composite identifier string.

◆ has_loaded()

template<class T >

bool vlink::Plugin::has_loaded ( const std::string & lib_name )

inline

Reports whether a plugin for interface T is currently registered.

Template Parameters

T	Interface type used during the original `load()` call.

Parameters

lib_name Library file name passed to load().

Returns: true when the registry entry is present.

◆ load()

template<class T >

std::shared_ptr< T > vlink::Plugin::load	(	const std::string &	lib_name,
		uint16_t	version_major,
		uint16_t	version_minor,
		const std::string &	dir_name = `""`,
		const std::deque< std::string > &	search_paths = `default_search_path()`,
		const std::string &	function_name = `VLINK_MACRO_STRING_GET(VLINK_PLUGIN_CREATE_FUNC_NAME)`
	)

inline

Loads a shared library that implements interface T and returns a tracked handle.

Details.

The loader appends the platform's library prefix/suffix to lib_name, scans search_paths, opens the first matching file, invokes the function_name entry point with the caller's ID and version, and finally wraps the returned object pointer in a shared_ptr<T> whose deleter invokes vlink_plugin_destroy.

Template Parameters

T	Interface type carrying `get_plugin_id()` (added by `VLINK_PLUGIN_REGISTER` or `VLINK_PLUGIN_REGISTER_BY_ID`).

Parameters

lib_name	Library file name without prefix/suffix.
version_major	Required interface major version.
version_minor	Required interface minor version.
dir_name	Optional directory searched before `search_paths`.
search_paths	Ordered fallback search list. Default: `default_search_path()`.
function_name	Symbol name of the construction entry point.

Returns: shared_ptr<T> owning the plugin instance, or nullptr on failure.

Here is the call graph for this function:

◆ process_plugin_internal()

static bool vlink::Plugin::process_plugin_internal	(	const std::string &	lib_name,
		const std::string &	local_plugin_id,
		uint16_t	local_version_major,
		uint16_t	local_version_minor,
		const std::string &	target_plugin_id,
		uint16_t	target_version_major,
		uint16_t	target_version_minor,
		uint8_t	log_level
	)

static

Internal version/ID gate invoked from the VLINK_PLUGIN_DECLARE entry point.

Compares the plugin's exported ID and version against the host's expectations, emitting informational or error diagnostics gated by log_level. User code should never call this function directly. log_level only filters this function's own output and is not propagated into the plugin module's runtime logger.

Parameters

lib_name	Library file name (used as a tag in diagnostic output).
local_plugin_id	Plugin ID compiled into the plugin binary.
local_version_major	Major version compiled into the plugin binary.
local_version_minor	Minor version compiled into the plugin binary.
target_plugin_id	Plugin ID required by the host caller.
target_version_major	Major version required by the host caller.
target_version_minor	Minor version required by the host caller.
log_level	Threshold used to filter this function's own diagnostics.

Returns: true when IDs match and local_major == target_major and local_minor >= target_minor.

◆ set_log_level()

void vlink::Plugin::set_log_level ( Logger::Level level )

Sets the verbosity level used for plugin diagnostic messages.

Parameters

level Logger level to apply to plugin load/unload tracing.

◆ unload()

template<class T >

bool vlink::Plugin::unload ( const std::string & lib_name )

inline

Removes a previously loaded plugin from the registry.

The shared library is finally unmapped once every shared_ptr returned by load() has been destroyed; this call only releases the tracker entry.

Template Parameters

T	Interface type used during the original `load()` call.

Parameters

lib_name Library file name passed to load().

Returns: true when the registry entry existed and was removed.

The documentation for this class was generated from the following file:

include/vlink/base/plugin.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Handle

Constructor & Destructor Documentation

◆ Plugin()

◆ ~Plugin()

Member Function Documentation

◆ clear()

◆ default_search_path()

◆ get_log_level()

◆ get_plugin_complex_id()

◆ has_loaded()

◆ load()

◆ process_plugin_internal()

◆ set_log_level()

◆ unload()