template<class T>
Corrade::PluginManager::Manager class

Plugin manager.

Manages loading, instancing and unloading plugins. See Plugin management for a detailed usage tutorial.

Plugin directories

Plugins are searched in the following directories, in order:

  1. If a non-empty pluginDirectory was passed to the Manager(std::string) constructor, plugins are searched there.
  2. Otherwise, it's expected that given plugin interface defined AbstractPlugin::pluginSearchPaths(). The search goes through the entries and stops once an existing directory is found.

The matching directory is then saved and available through pluginDirectory().

Besides the above, it's possible to call load() with a concrete path to a dynamic module file to load a plugin from outside of the plugin directory. The file is expected to be accompanied by its corresponding *.conf metadata file and no plugin with the same name is expected to be loaded at the same time. If loading succeeds, the module is exposed through the API under its basename (excluding extension).

Plugin loading, instantiation and unloading

A plugin is loaded by calling load() with given plugin name or alias. After that, you can get one or more instances using instantiate(). For convenience, loadAndInstantiate() combines these two operations into one.

Plugin is unloaded either by calling unload() or on plugin manager destruction. By default, all active plugin instances have to be deleted before a plugin can be unloaded. For hot reloading and other specific use cases it's possible to unload a plugin that still has active instances. For that to work, AbstractPlugin::canBeDeleted() has to return true for all active instances, otherwise unload() returns LoadState::Used. Moreover, in order to avoid double-free issues, you have to call release() on all Containers::Pointer instances returned from Manager::instantiate() or Manager::loadAndInstantiate().

Plugin-specific data and configuration

Besides the API provided by a particular plugin interface after given plugin is instantiated, plugins can also define various additional metadata that can be accessed even if the plugin is not loaded. That can be used for example to provide extra information to users in a plugin listing UI. Plugin-specific data can be accessed via PluginMetadata::data() through either metadata() or AbstractPlugin::metadata().

In order to make it possible to configure behavior of specific plugins on top of what the general plugin interface provides, the AbstractPlugin::configuration() function provides read-write access to a configuration specific to a particular plugin instance. This can be used for example to adjust various quality/speed properties of a JPEG image conversion plugin that wouldn't be otherwise available in the general image converter plugin API.

See PluginMetadata for detailed description of the plugin metadata file.

Thread safety

Static plugins register themselves into a global storage. If done implicitly, the registration is executed before entering main() and thus serially. If done explicitly via CORRADE_PLUGIN_IMPORT() / CORRADE_PLUGIN_EJECT(), these macros have to be called from a single thread or externally guarded to avoid data races.

All other operation (instantiating a manager, loading/unloading plugins, instantiating them, ...) is done thread-locally if Corrade is compiled with CORRADE_BUILD_MULTITHREADED enabled (the default). This might cause some performance penalties — if you are sure that you will never need to manage plugins over multiple threads (and won't need any other functionality enabled by this option either), build Corrade with the option disabled.

Base classes

class AbstractManager
Base for plugin managers.

Constructors, destructors, conversion operators

Manager(std::string pluginDirectory = {}) explicit
Constructor.

Public functions

auto instantiate(const std::string& plugin) -> Containers::Pointer<T>
Instantiate a plugin.
auto loadAndInstantiate(const std::string& plugin) -> Containers::Pointer<T>
Load and instantiate plugin.

Function documentation

template<class T>
Corrade::PluginManager::Manager<T>::Manager(std::string pluginDirectory = {}) explicit

Constructor.

Parameters
pluginDirectory Optional directory where plugins will be searched. See Plugin directories for more information.

First goes through list of static plugins and finds ones that use the same interface as this manager instance. Then gets list of all dynamic plugins in given directory.

template<class T>
Containers::Pointer<T> Corrade::PluginManager::Manager<T>::instantiate(const std::string& plugin)

Instantiate a plugin.

Returns new instance of given plugin. The plugin must be already successfully loaded by this manager. The returned value is never nullptr.

template<class T>
Containers::Pointer<T> Corrade::PluginManager::Manager<T>::loadAndInstantiate(const std::string& plugin)

Load and instantiate plugin.

Convenience alternative to calling both load() and instantiate(). If loading fails, nullptr is returned.

As with load(), it's possible to pass a file path to plugin. See its documentation for more information. The resulting plugin name is then loaded using instantiate() as usual.