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

Plugin manager.

Contents

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 std::unique_ptr::release() on all std::unique_ptr instances returned from Manager::instance() 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.

Base classes

class AbstractManager
Non-templated base for plugin managers.

Constructors, destructors, conversion operators

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

Public functions

auto instantiate(const std::string& plugin) -> std::unique_ptr<T>
Instantiate a plugin.
auto instance(const std::string& plugin) -> std::unique_ptr<T> deprecated
Instantiate a plugin.
auto loadAndInstantiate(const std::string& plugin) -> std::unique_ptr<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>
std::unique_ptr<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>
std::unique_ptr<T> Corrade::PluginManager::Manager<T>::instance(const std::string& plugin)

Instantiate a plugin.

template<class T>
std::unique_ptr<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.