#include <Corrade/PluginManager/Manager.h>

template<class T>

Corrade::PluginManager::Manager class

Plugin directories

Plugins are searched in the following directories, in order:

1. If a non-empty pluginDirectory was passed to the Manager(Containers::StringView) constructor, plugins are searched there. If the directory doesn't exist, no search is performed and the process stops here.
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::Path::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.

Custom plugin interfaces and template definitions

To avoid pulling in relatively big includes, the Corrade/PluginManager/Manager.h header contains only declarations of the template functions. While that works fine when using builtin plugin interfaces in Corrade and Magnum, you need to make an extra step when implementing your own plugin interfaces.

The easiest is to simply include Corrade/PluginManager/Manager.hpp instead of the *.h file in order to get the full definitions. If you however want to avoid the additional overhead of the template instantiations and includes it pulls in, it's recommended to include it only in the source file where you define the plugin interface and perform an explicit template instantiation:

#include <Corrade/PluginManager/Manager.hpp>

namespace MyNamespace {
    class MyAbstractPlugin: public PluginManager::AbstractPlugin {
        …
    };
}

namespace Corrade { namespace PluginManager {
    template class Manager<MyNamespace::MyAbstractPlugin>;
}}

The namespace where you locate the template class is important. Additionally, if the plugin interface is exposed in a shared library, you may need to export the template instantiation symbols for example with CORRADE_VISIBILITY_EXPORT. Look into Corrade and Magnum sources for further examples.

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(Containers::StringView pluginDirectory = {}) explicit

Constructor.

Public functions

auto instantiate(Containers::StringView plugin) -> Containers::Pointer<T>

Instantiate a plugin.

auto loadAndInstantiate(Containers::StringView plugin) -> Containers::Pointer<T>

Load and instantiate plugin.

template<class U>

auto externalManager() -> Manager<U>* new in Git master

Retrieve an external plugin manager.

Function documentation