Corrade::PluginManager::AbstractPlugin class

Base class for plugin interfaces.

Makes it possible to connects every plugin instance to its corresponding plugin manager, which ensures the plugin can be unloaded only if there are no active instances. Besides that, provides access to interface-specific and plugin-specific metadata.

Subclassing

Plugin interface classes have to provide the following:

  • A pluginInterface() function, defining a unique plugin interface string. See its documentation for details.
  • A pluginSearchPaths() function, defining hardcoded search paths for plugins in this interface (if any). See its documentation for details.
  • A pair of initialize() / finalize() functions, used to initialize and finalize global state of given plugin library. See their documentation for details.
  • A constructor with signature the same as AbstractPlugin(AbstractManager&, const std::string&) so the plugin manager can load them
  • A constructor with signature the same as AbstractPlugin(), in case it makes sense to instantiate the plugin directly without a plugin manager

A minimal example is below. The pluginSearchPaths() function first lists a path relative to executable directory (which would be used for example when deploying a Windows build) and as a fallback a system location, depending on CMAKE_INSTALL_PREFIX that's propagated from CMake via a #define generated by configure_file(). The functions are inlined here, but it's advised to move their definitions to a separate source file.

class AbstractFilesystem: public PluginManager::AbstractPlugin {
    public:
        static std::string pluginInterface() {
            return "cz.mosra.corrade.AbstractFilesystem/1.0";
        }

        std::vector<std::string> pluginSearchPaths() {
            return {
                "corrade/filesystems",
                Utility::Directory::join(CMAKE_INSTALL_PREFIX, "lib/corrade/filesystems")
            };
        }

        explicit AbstractFilesystem(PluginManager::AbstractManager& manager, const std::string& plugin):
            PluginManager::AbstractPlugin{manager, plugin} {}

        explicit AbstractFilesystem() = default;

        // the actual plugin interface goes here
};

See Plugin management for a detailed tutorial.

Derived classes

template<class Interface>
class AbstractManagingPlugin
Base class for plugin interfaces with access to associated manager.

Public static functions

static auto pluginInterface() -> std::string
Plugin interface string.
static auto pluginSearchPaths() -> std::vector<std::string>
Plugin search paths.
static void initialize()
Initialize plugin.
static void finalize()
Finalize plugin.

Constructors, destructors, conversion operators

AbstractPlugin() explicit
Default constructor.
AbstractPlugin(AbstractManager& manager, const std::string& plugin) explicit
Plugin manager constructor.
AbstractPlugin(const AbstractPlugin&) deleted
Copying is not allowed.
AbstractPlugin(AbstractPlugin&&) deleted
Moving is not allowed.
~AbstractPlugin() pure virtual
Destructor.

Public functions

auto operator=(const AbstractPlugin&) -> AbstractPlugin& deleted
Copying is not allowed.
auto operator=(AbstractPlugin&&) -> AbstractPlugin& deleted
Moving is not allowed.
auto canBeDeleted() -> bool virtual
Whether the plugin can be deleted.
auto plugin() const -> const std::string&
Identifier string.
auto metadata() const -> const PluginMetadata*
Metadata.
auto configuration() -> Utility::ConfigurationGroup&
Plugin-specific configuration.
auto configuration() const -> const Utility::ConfigurationGroup&

Function documentation

static std::string Corrade::PluginManager::AbstractPlugin::pluginInterface()

Plugin interface string.

Plugins implementing given interface have to define exactly the same interface string, otherwise they won't be loaded. This can be used to ensure the interface and plugin is correctly paired even in case where there is no ABI mismatch A good practice is to use a "Java package name"-style syntax. The interface name should also contain version identifier to make sure the plugin will not be loaded with incompatible interface version.

static std::vector<std::string> Corrade::PluginManager::AbstractPlugin::pluginSearchPaths()

Plugin search paths.

List of hardcoded absolute or relative paths where to search for plugins of given interface. Relative paths are relative to Utility::Directory::executableLocation() directory. Earlier entries have more priority than later, search stops once an existing directory is found. By default this function returns an empty list. See also Plugin directories for more information.

static void Corrade::PluginManager::AbstractPlugin::initialize()

Initialize plugin.

You can override this function to perform initialization before any plugin instance is created. Default implementation does nothing.

If the plugin is static, this function is called on construction of corresponding plugin manager, if the plugin is dynamic, this function is called on plugin load. If the plugin is used directly without plugin manager, you have to call this function manually (if needed).

static void Corrade::PluginManager::AbstractPlugin::finalize()

Finalize plugin.

You can override this function to perform finalization after all plugin instances are destroyed. Default implementation does nothing.

If the plugin is static, this function is called on destruction of corresponding plugin manager, if the plugin is dynamic, this function is called on plugin unload. If the plugin is used directly without plugin manager, you have to call this function manually (if needed).

Corrade::PluginManager::AbstractPlugin::AbstractPlugin() explicit

Default constructor.

Define this constructor in your subclass only if you want to allow using the interface or plugin without plugin manager.

The metadata() function will return nullptr.

Corrade::PluginManager::AbstractPlugin::AbstractPlugin(AbstractManager& manager, const std::string& plugin) explicit

Plugin manager constructor.

Used by plugin manager. Don't forget to redefine this constructor in all your subclasses.

Corrade::PluginManager::AbstractPlugin::~AbstractPlugin() pure virtual

Destructor.

If instantiated through plugin manager, unregisters this instance from it.

bool Corrade::PluginManager::AbstractPlugin::canBeDeleted() virtual

Whether the plugin can be deleted.

Called from PluginManager on all active instances before the plugin is unloaded. Returns true if it is safe to delete the instance from the manager, false if not. If any instance returns false, the plugin is not unloaded. See Plugin loading, instantiation and unloading for more information.

const std::string& Corrade::PluginManager::AbstractPlugin::plugin() const

Identifier string.

Name under which the plugin was instantiated, either its true name or an alias. If the plugin was not instantiated via plugin manager, returns empty string. Use metadata()->name() to get plugin true name unconditionally.

const PluginMetadata* Corrade::PluginManager::AbstractPlugin::metadata() const

Metadata.

Metadata associated with given plugin. If the plugin was not instantiated through a plugin manager, returns nullptr.

Utility::ConfigurationGroup& Corrade::PluginManager::AbstractPlugin::configuration()

Plugin-specific configuration.

Configuration associated with given plugin instance. Can be used to modify plugin behavior beyond what's possible through the plugin interface. Every instance gets a fresh copy from PluginMetadata::configuration(), modifications are affecting only particular plugin instance. If the plugin was not instantiated through a plugin manager or the [configuration] group was not present in the metadata, the returned group is empty.

const Utility::ConfigurationGroup& Corrade::PluginManager::AbstractPlugin::configuration() const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.