CppPluginSystem Class Reference

Generic plugin system for C++ plugins. More...

#include <CppPluginSystem.hpp>

Public Types
using	Ptr = CppPluginSystemPtr
using	ConstPtr = CppPluginSystemConstPtr
using	PathAndPlugin = std::pair< std::filesystem::path, CppPluginSystemPluginPtr >
	Pair of absolute path to plugin and shared_ptr to plugin instance. More...
using	ValidationCallback = std::function< std::optional< Str >(const CppPluginSystemPluginPtr &)>
	Callback provided to scan to provide further validation. More...

Public Member Functions
void	reset ()
	Clear any previously loaded plugins. More...
void	scan (std::string_view paths, std::string_view pathsEnvVar, std::string_view moduleHookName, const ValidationCallback &validationCallback)
	Searches the supplied paths for plugin modules. More...
openassetio::Identifiers	identifiers () const
	Returns the identifiers known to the plugin system. More...
const PathAndPlugin &	plugin (const openassetio::Identifier &identifier) const
	Retrieves the plugin that provides the given identifier. More...

Static Public Member Functions
static CppPluginSystemPtr	make (log::LoggerInterfacePtr logger)
	Constructs a new CppPluginSystem. More...

Detailed Description

Generic plugin system for C++ plugins.

The API broadly mirrors the PythonPluginSystem.

See also

scan

PluginFactory

CppPluginSystemPlugin

Member Typedef Documentation

using ConstPtr = CppPluginSystemConstPtr

using PathAndPlugin = std::pair<std::filesystem::path, CppPluginSystemPluginPtr>

Pair of absolute path to plugin and shared_ptr to plugin instance.

using Ptr = CppPluginSystemPtr

using ValidationCallback = std::function<std::optional<Str>(const CppPluginSystemPluginPtr&)>

Callback provided to scan to provide further validation.

A return value of empty optional signals that the plugin is OK. A return value of a string signals that the plugin is not OK and the string provides the reason.

Member Function Documentation

openassetio::Identifiers identifiers

(

)

const

Returns the identifiers known to the plugin system.

If scan has not been called, then this will be empty.

static CppPluginSystemPtr make ( log::LoggerInterfacePtr  logger )

static

Constructs a new CppPluginSystem.

Parameters

logger

Logger used to log progress and warnings. Note that most logs are at debug severity.

Returns

Newly constructed CppPluginSystem wrapped in a shared_ptr.

const PathAndPlugin& plugin

(

const openassetio::Identifier &

identifier

)

const

Retrieves the plugin that provides the given identifier.

Parameters

identifier

Identifier to look up.

Returns

A pair of plugin path and instance.

Exceptions

errors.InputValidationException

Raised if no plugin provides the specified identifier.

void reset

(

)

Clear any previously loaded plugins.

Note this does not unload/unlink any previously loaded binary shared libraries from the application.

void scan	(	std::string_view	paths,
		std::string_view	pathsEnvVar,
		std::string_view	moduleHookName,
		const ValidationCallback &	validationCallback
	)

Searches the supplied paths for plugin modules.

Paths are searched left-to-right, but only the first instance of any given plugin identifier will be used, and subsequent registrations ignored. This means entries to the left of the paths list take precedence over ones to the right.

Note

Precedence order is undefined for plugins sharing the same identifier within the same directory.

If the given paths string and the given environment variable both contain search paths, then only the paths string is used.

Each given directory is scanned for shared libraries that expose a given hook function (with C linkage), which is expected to return a PluginFactory function pointer, which when called returns an instantiated (subclass of) CppPluginSystemPlugin.

Discovered plugins are registered by their exposed identifier, and subsequent registrations with the same identifier will be skipped.

No attempt is made to catch exceptions during static initialisation or during the call to the provided PluginFactory, and any such exception will almost definitely terminate the process.

Parameters

paths	A list of paths to search, delimited by operating system specific path separator (i.e. : for POSIX, ; for Windows). Leave blank to search paths given by the environment variable specified in pathsEnvVar.
pathsEnvVar	An environment variable name containing paths formatted as described in paths. Paths from this environment variable are ignored if paths is non-empty.
moduleHookName	The name of the entry point function to scan for and execute within discovered files.
validationCallback	A callback that will be given a candidate CppPluginSystemPtr and should return an empty optional if the plugin is valid, or a reason string if not valid.

---

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

• /src/src/openassetio-core/include/openassetio/pluginSystem/CppPluginSystem.hpp