Type-safe dynamic plugin loader with version verification and lifecycle management. More...

#include <plugin.h>

Collaboration diagram for vlink::Plugin:

Public Types
using	Handle = void*
	Opaque handle to a loaded shared library object (used internally).

Public Member Functions
	Plugin ()
	Constructs a `Plugin` manager with an empty library registry.
	~Plugin ()
	Destructor. Calls `clear()` to unload all still-loaded libraries.
void	set_log_level (Logger::Level level)
	Sets the log level used for plugin load/unload diagnostics.
Logger::Level	get_log_level () const
	Returns the current log level for plugin diagnostics.
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 plugin implementing interface `T` from a shared library.
template<class T>
bool	unload (const std::string &lib_name)
	Unloads the plugin library for interface `T`.
template<class T>
bool	has_loaded (const std::string &lib_name)
	Returns `true` if the plugin for interface `T` is currently loaded.
template<class T>
std::string	get_plugin_complex_id (const std::string &lib_name)
	Returns the composite key used internally to identify a (library, interface) pair.
void	clear ()
	Unloads all loaded plugin libraries.

Static Public Member Functions
static std::deque< std::string >	default_search_path ()
	Returns the default search path list for finding plugin shared libraries.
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 entry-point handler called from `VLINK_PLUGIN_DECLARE`.

Detailed Description

Type-safe dynamic plugin loader with version verification and lifecycle management.

Loads one or more shared library plugins by interface type T. Multiple distinct interface types may be loaded by a single Plugin instance.

Member Typedef Documentation

◆ Handle

using vlink::Plugin::Handle = void*

Opaque handle to a loaded shared library object (used internally).

Constructor & Destructor Documentation

◆ Plugin()

vlink::Plugin::Plugin ( )

Constructs a Plugin manager with an empty library registry.

Here is the caller graph for this function:

◆ ~Plugin()

vlink::Plugin::~Plugin ( )

Destructor. Calls clear() to unload all still-loaded libraries.

Member Function Documentation

◆ clear()

void vlink::Plugin::clear ( )

Unloads all loaded plugin libraries.

Equivalent to calling unload<T>(lib_name) for every previously loaded plugin.

◆ default_search_path()

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

staticnodiscard

Returns the default search path list for finding plugin shared libraries.

Includes the executable directory, the system library directories, and the current working directory.

Returns: Deque of directory path strings to search in order.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_log_level()

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

nodiscard

Returns the current log level for plugin diagnostics.

Returns: Current log level.

◆ get_plugin_complex_id()

template<class T>

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

inlinenodiscard

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

The key is lib_name + "@" + T::get_plugin_id().

Template Parameters

T	Interface type.

Parameters

lib_name Library file name.

Returns: Composite ID string.

Here is the caller graph for this function:

◆ has_loaded()

template<class T>

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

inlinenodiscard

Returns true if the plugin for interface T is currently loaded.

Template Parameters

T	Interface type.

Parameters

lib_name Library file name used during load().

Returns: true if loaded.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ 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) )

inlinenodiscard

Loads a plugin implementing interface T from a shared library.

Details.

Resolves the library file by searching search_paths for a file whose name matches lib_name (with platform-appropriate prefix/suffix).
Opens the library with dlopen (or LoadLibrary on Windows).
Calls the vlink_plugin_create entry point with version and ID information.
Returns a shared_ptr<T> whose custom deleter calls vlink_plugin_destroy.

Template Parameters

T	Interface type. Must have a `get_plugin_id()` static method (inserted by `VLINK_PLUGIN_REGISTER` or `VLINK_PLUGIN_REGISTER_BY_ID`).

Parameters

lib_name	File name of the shared library (without prefix/suffix).
version_major	Required major version.
version_minor	Required minor version.
dir_name	Optional explicit directory to search first. Default: empty.
search_paths	Ordered list of directories to search. Default: `default_search_path()`.
function_name	Name of the creation entry point. Default: `vlink_plugin_create`.

Returns: shared_ptr<T> on success, or nullptr on failure.

Here is the caller graph for this function:

◆ process_plugin_internal()

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 entry-point handler called from VLINK_PLUGIN_DECLARE.

Validates the plugin ID and version, then configures the logger level inside the plugin. Should not be called directly by user code.

Parameters

lib_name	Library name (for logging).
local_plugin_id	ID exported by the plugin implementation.
local_version_major	Major version exported by the plugin.
local_version_minor	Minor version exported by the plugin.
target_plugin_id	ID expected by the caller (from `T::get_plugin_id()`).
target_version_major	Major version required by the caller.
target_version_minor	Minor version required by the caller.
log_level	Logger level to propagate into the plugin.

Returns: true if the ID and version match.

Here is the call graph for this function:

◆ set_log_level()

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

Sets the log level used for plugin load/unload diagnostics.

Parameters

level Logger level.

◆ unload()

template<class T>

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

inline

Unloads the plugin library for interface T.

Removes the library from the internal registry and decrements the reference count. The library is actually closed when all shared_ptr instances to the plugin object are destroyed.

Template Parameters

T	Interface type.

Parameters

lib_name Library file name used during load().

Returns: true if the library was found and unloaded.

Here is the call graph for this function:

Here is the caller graph for this function:

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()