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

Plugin manager.

Manages loading, instancing and unloading plugins. See Plugin management for a high-level introduction.

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.

In both cases the path of Utility::Directory::executableLocation() is prepended to relative paths before testing. 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 (unless overridden in the plugin interface using AbstractPlugin::pluginMetadataSuffix()) 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 a general image converter plugin API.

See PluginMetadata for detailed description of the plugin metadata file.

Plugin dependencies

Plugins can depend on each other by listing then in the metadata file, as described in the PluginMetadata class documentation. From the user point-of-view the dependency handling is completely transparent — loading a plugin will also load all its dependencies, fail if some dependencies can't be found, and disallow the plugin from being unloaded when some other still needs it.

A special (and rarer) case is inter-manager dependencies. By default, to avoid shared mutable global state, plugin manager instances don't know about each other, so if a plugin depends on another from a different interface, you need to instantiate a manager for the other interface and register it with the original manager using registerExternalManager().

Multiple instances of the same manager

It's possible to have more than one instance of the same manager as well as loading and instantiating the same plugin in more than one manager at the same time. For static plugins there's no reason this could work, for dynamic both the Unix dlopen() and Windows LoadLibrary() load the library only once and maintain reference count to ensure it's unloaded only after it's not needed anymore. The only way you may run into problem is by loading the same plugin binary twice under different filenames, causing the loader to have symbol conflicts, violating ODR.

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.

On the other hand, all other functionality only reads from the global storage and thus is thread-safe.

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.