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 by its library/interface pair. Loading the same pair more than once returns nullptr. 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.

A path-like or platform-suffixed lib_name that names a regular file is opened directly. Otherwise the loader appends the platform's library prefix/suffix, scans search_paths, and opens the first matching regular file. It then invokes the function_name entry point with the caller's ID and version and 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 stem without prefix/suffix, or a direct shared-library path.
version_major	Required interface major version.
version_minor	Required interface minor version.
dir_name	Optional subdirectory tried under each entry of `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()