#include <ImFusion/Core/PluginManager.h>

Global singleton for loading ImFusion plugins from shared libraries and initializing them. More...

Inheritance diagram for ImFusion::PluginManager:

Detailed Description

Global singleton for loading ImFusion plugins from shared libraries and initializing them.

ImFusion plugins use a two-phase initialization:

The first step is loading the library into the application memory, checking compatibility with the host application, and registering them with PluginManager (registerPlugin(), registerPlugins()).
The second step is the actual initialization of a plugin where it will register it with the application's factories, etc (initPlugin(), initAllRegisteredPlugins()).

For convenience, you can use the loadPlugin() and loadPlugins() functions that combine both steps into a single function call.

See also: Plugin Architecture, PluginBase, IMFUSION_REGISTER_PLUGIN

Classes
struct	PluginInfo
	Record collecting metadata about registered plugins. More...

Public Types
enum class	PluginStatus { Unknown , Registered , Incompatible , Initialized , Failed }
	Enumeration of the set of states an ImFusion plugin can be in during its lifetime. More...
enum class	Status { Success = 0 , FileNotFound , MissingSymbol , Skipped , Incompatible , PluginIdConflict , LicenseCheckFailed , DependencyInitFailed , UnknownPluginId , WrongPluginStatus , Unsupported , InvalidPluginVersion , UnknownError }
	Enumeration of status/error codes for the member functions of PluginManager. More...

Public Member Functions
std::pair< std::string, Status >	registerPlugin (Filesystem::Path filename)
	Load the shared library from filename and check whether it is compatible with the host application.
std::vector< std::tuple< Filesystem::Path, std::string, Status > >	registerPlugins (const std::vector< Filesystem::Path > &scanDirectories=defaultPluginSearchDirectories(), std::function< bool(const Filesystem::Path &)> filterFunction=nullptr, bool performMagicStringDetection=true)
	Scans scanDirectories for shared library files and calls registerPlugin() for each suitable file.
Status	initPlugin (const std::string &pluginId)
	Initialize the given plugin and its dependencies by calling PluginBase::init().
std::vector< std::pair< std::string, Status > >	initAllRegisteredPlugins (bool logAvailablePlugins=true)
	Initialize all currently registered plugins by calling PluginBase::init().
std::pair< std::string, Status >	loadPlugin (const Filesystem::Path &filename)
	Convenience function combining registerPlugin() and initPlugin() into a single function call.
std::vector< std::tuple< Filesystem::Path, std::string, Status > >	loadPlugins (const std::vector< Filesystem::Path > &scanDirectories=defaultPluginSearchDirectories(), std::function< bool(const Filesystem::Path &)> filterFunction=nullptr, bool performMagicStringDetection=true)
	Convenience function first calling registerPlugins() and subsequently calling initPlugin() for each previously registered plugin.
void	addLibraryNameToBlacklist (const std::string &libraryName)
	Add libraryName to the list of blacklisted library names to prevent it from being loaded via loadPlugins().
bool	isCompatibleImFusionPlugin (const Filesystem::Path &filename) const
	Checks if filename looks like a library that contains a valid and compatible plugin without actually loading it via the OS.
PluginStatus	pluginStatus (const std::string &pluginId)
	Returns the current status of the given plugin.
PluginBase *	pluginInstance (const std::string &pluginId)
	Returns the PluginBase instance with status PluginStatus::Initialized and the given pluginId, or nullptr if no such plugin known, the plugin is not yet initialized, or initialization has failed.
template<typename T>
T *	pluginInstance ()
	Returns the first found PluginBase instance with status PluginStatus::Initialized that is of type T, or nullptr if no such plugin known, the plugin is not yet initialized, or initialization has failed.
const std::vector< PluginInfo > &	allPlugins () const
	Returns the list of all known plugins, including plugins that are not yet initialized or failed to do so.
void	deinit ()
	Explicitly unload all plugins and deinitialize PluginManager.

Static Public Member Functions
static PluginManager &	get ()
	Return the singleton instance.
static std::vector< Filesystem::Path >	defaultPluginSearchDirectories ()
	Returns a list of default search directories for plugins:

Member Enumeration Documentation

◆ PluginStatus

enum class ImFusion::PluginManager::PluginStatus

strong

Enumeration of the set of states an ImFusion plugin can be in during its lifetime.

Enumerator
Unknown	Plugin has not yet been registered.
Registered	Plugin library matches the requirements for an ImFusion plugin and was successfully registered.
Incompatible	Plugin was attempted to be registered but its library does not match the necessary requirements.
Initialized	Plugin was successfully initialized and ready to be used.
Failed	Plugin initialization has failed and can not be used.

◆ Status

enum class ImFusion::PluginManager::Status

strong

Enumeration of status/error codes for the member functions of PluginManager.

Enumerator
Success	Operation succeeded without errors.
FileNotFound	The library file was not found.
MissingSymbol	The library does not export the necessary symbols.
Skipped	The library was skipped because it was blacklisted.
Incompatible	The library contains a plugin that is not compatible with the host application.
PluginIdConflict	A different library file already registered a plugin with the same ID.
LicenseCheckFailed	A license check failed.
DependencyInitFailed	A plugin dependency could not be initialized.
UnknownPluginId	The given plugin ID is unknown.
WrongPluginStatus	The current PluginStatus is not suitable for the requested operation.
Unsupported	The requested operation is unsupported by the plugin.
InvalidPluginVersion	The version of the plugin is not a valid Utils::Version.
UnknownError	An unknown error error occurred during the requested operation.

Member Function Documentation

◆ defaultPluginSearchDirectories()

std::vector< Filesystem::Path > ImFusion::PluginManager::defaultPluginSearchDirectories ( )

static

Returns a list of default search directories for plugins:

on Windows: <executable-path>/plugins and <ImFusionCore.dll-path>/plugins
on Linux: <libImFusionCore.so-path>/../lib/ImFusionLib/plugins
all platforms: directories in IMFUSION_PLUGIN_PATH environment variable (separated by ;)

◆ registerPlugin()

std::pair< std::string, Status > ImFusion::PluginManager::registerPlugin ( Filesystem::Path filename )

Load the shared library from filename and check whether it is compatible with the host application.

Plugin state must be PluginStatus::Unknown. Afterwards, the plugin state will either be PluginStatus::Registered on success or PluginStatus::Incompatible in case of failure.

Returns: Pair of the Plugin ID of the registered plugin (if successful) and the status code indicating whether plugin registration was successful.

◆ registerPlugins()

std::vector< std::tuple< Filesystem::Path, std::string, Status > > ImFusion::PluginManager::registerPlugins	(	const std::vector< Filesystem::Path > &	scanDirectories = defaultPluginSearchDirectories(),
		std::function< bool(const Filesystem::Path &)>	filterFunction = nullptr,
		bool	performMagicStringDetection = true )

Scans scanDirectories for shared library files and calls registerPlugin() for each suitable file.

This function will only consider files with the platform-specific default extension for shared libraries (Windows: .dll, Linux: .so, MacOS: .dylib), and files that are not blacklisted (cf. addLibraryNameToBlacklist()). Furthermore, each file's content will be scanned for the presence of a magic string before attempting to register it. This avoids loading unrelated libraries into the process memory and the OS executing their static initializers only to have them being unloaded again after realizing that they do not implement the necessary interface.

Parameters

scanDirectories	List of local filesystem directories to scan for suitable shared libraries.
filterFunction	Optional predicate function to override the built-in library blacklist (cf. addLibraryNameToBlacklist()) with a custom filter function and register only those files found in scanDirectories where the function returns true and ignore files where it returns false.
performMagicStringDetection	Some platforms (e.g. MacOS) support optional encryption of the text sections in shared libraries. In this case the detection of the magic string in will fail. You can set this to false as a workaround when working with encrypted libraries.

Returns: A list of all found plugin libraries represented by a tuple containing the library filename, plugin ID, and plugin registration status.

◆ initPlugin()

Status ImFusion::PluginManager::initPlugin ( const std::string & pluginId )

Initialize the given plugin and its dependencies by calling PluginBase::init().

Plugin state must be PluginStatus::Registered. Afterwards, the plugin state will either be PluginStatus::Initialized on success or PluginStatus::Failed in case of failure.

Parameters

pluginId Unique plugin ID as returned by the corresponding PluginBase::id() function.

◆ initAllRegisteredPlugins()

std::vector< std::pair< std::string, Status > > ImFusion::PluginManager::initAllRegisteredPlugins ( bool logAvailablePlugins = true )

Initialize all currently registered plugins by calling PluginBase::init().

Only plugins with state PluginStatus::Registered are considered. Afterwards, their plugin state will either be PluginStatus::Initialized on success or PluginStatus::Failed in case of failure.

Parameters

logAvailablePlugins Flag whether to emit a log message with a list of all available plugins at the end of this function call using Log::Level::Info.

Returns: A list of all plugins that were initialized, represented by a pair of the plugin ID and the corresponding success status of the attempted initialization.

◆ loadPlugin()

std::pair< std::string, Status > ImFusion::PluginManager::loadPlugin ( const Filesystem::Path & filename )

Convenience function combining registerPlugin() and initPlugin() into a single function call.

Plugin state must be PluginStatus::Unknown. Afterwards, the plugin state will either be PluginStatus::Initialized on success, or PluginStatus::Incompatible or PluginStatus::Failed in case of failure.

Returns: Pair of the Plugin ID of the registered plugin (if available) and the status code indicating whether plugin registration was successful.

◆ loadPlugins()

std::vector< std::tuple< Filesystem::Path, std::string, Status > > ImFusion::PluginManager::loadPlugins	(	const std::vector< Filesystem::Path > &	scanDirectories = defaultPluginSearchDirectories(),
		std::function< bool(const Filesystem::Path &)>	filterFunction = nullptr,
		bool	performMagicStringDetection = true )

Convenience function first calling registerPlugins() and subsequently calling initPlugin() for each previously registered plugin.

Returns: A list of all found plugin libraries represented by a tuple containing the library filename, plugin ID, and plugin registration status.

◆ addLibraryNameToBlacklist()

void ImFusion::PluginManager::addLibraryNameToBlacklist ( const std::string & libraryName )

Add libraryName to the list of blacklisted library names to prevent it from being loaded via loadPlugins().

A library is considered blacklisted if any substring of the filename is part of the list. The blacklist is default-initialized by the value of the IMFUSION_PLUGIN_BLACKLIST environment variable.

◆ isCompatibleImFusionPlugin()

bool ImFusion::PluginManager::isCompatibleImFusionPlugin ( const Filesystem::Path & filename ) const

Checks if filename looks like a library that contains a valid and compatible plugin without actually loading it via the OS.

Internally, this function simply memory-maps the file and searches for the presence of a magic string containing the plugin descriptor. If found it will then check the descriptor for compatibility with the host application.

Note: Some platforms (e.g. MacOS) support optional encryption of the text sections in shared libraries. In this case the detection of the magic string in will fail even if the library is a valid plugin.

Returns: true if filename points to a shared library that can be loaded via registerPlugin().
false if it either could not locate the magic string or the plugin descriptor is incompatible.

◆ pluginStatus()

PluginStatus ImFusion::PluginManager::pluginStatus ( const std::string & pluginId )

Returns the current status of the given plugin.

Parameters

pluginId Unique plugin ID as returned by the corresponding PluginBase::id() function.

◆ pluginInstance() [1/2]

PluginBase * ImFusion::PluginManager::pluginInstance ( const std::string & pluginId )

Returns the PluginBase instance with status PluginStatus::Initialized and the given pluginId, or nullptr if no such plugin known, the plugin is not yet initialized, or initialization has failed.

Parameters

pluginId Unique plugin ID as returned by the corresponding PluginBase::id() function.

◆ pluginInstance() [2/2]

template<typename T>

T * ImFusion::PluginManager::pluginInstance ( )

Returns the first found PluginBase instance with status PluginStatus::Initialized that is of type T, or nullptr if no such plugin known, the plugin is not yet initialized, or initialization has failed.

Template Parameters

T	Concrete type of the plugin instance to dynamic_cast for.

◆ deinit()

void ImFusion::PluginManager::deinit ( )

Explicitly unload all plugins and deinitialize PluginManager.

Call this function to avoid deinitialization happening during static teardown time (PluginManager singleton destructor).

Note: After calling this function you must no longer use PluginManager or any of the previously loaded plugins.

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

ImFusion/Core/PluginManager.h

Detailed Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Member Enumeration Documentation

◆ PluginStatus

◆ Status

Member Function Documentation

◆ defaultPluginSearchDirectories()

◆ registerPlugin()

◆ registerPlugins()

◆ initPlugin()

◆ initAllRegisteredPlugins()

◆ loadPlugin()

◆ loadPlugins()

◆ addLibraryNameToBlacklist()

◆ isCompatibleImFusionPlugin()

◆ pluginStatus()

◆ pluginInstance() [1/2]

◆ pluginInstance() [2/2]

◆ deinit()