Ignition Plugin

API Reference

1.2.1
Loader Class Reference

Class for loading plugins. More...

#include <Loader.hh>

Public Member Functions

 Loader ()
 Constructor. More...
 
 ~Loader ()
 Destructor. More...
 
std::set< std::stringAliasesOfPlugin (const std::string &_pluginName) const
 Get the aliases of the plugin with the given name. More...
 
std::set< std::stringAllPlugins () const
 Get a set of the names of all plugins that are currently known to this Loader. More...
 
template<typename InterfaceType >
std::shared_ptr< InterfaceType > Factory (const std::string &_pluginNameOrAlias) const
 Instantiates a plugin for the given plugin name, and then returns a reference-counting interface corresponding to InterfaceType. More...
 
bool ForgetLibrary (const std::string &_pathToLibrary)
 This loader will forget about the library at the given path location. If you want to instantiate a plugin from this library using this loader, you will first need to call LoadLib again. More...
 
bool ForgetLibraryOfPlugin (const std::string &_pluginNameOrAlias)
 Forget the library that provides the plugin with the given name. Note that this will also forget all other plugin types which are provided by that library. More...
 
PluginPtr Instantiate (const std::string &_pluginNameOrAlias) const
 Instantiates a plugin for the given plugin name. More...
 
template<typename PluginPtrType >
PluginPtrType Instantiate (const std::string &_pluginNameOrAlias) const
 Instantiates a plugin of PluginType for the given plugin name. This can be used to create a specialized PluginPtr. More...
 
std::unordered_set< std::stringInterfacesImplemented () const
 Get demangled names of interfaces that the loader has plugins for. More...
 
std::unordered_set< std::stringLoadLib (const std::string &_pathToLibrary)
 Load a library at the given path. More...
 
std::string LookupPlugin (const std::string &_nameOrAlias) const
 Resolve the plugin name or alias into the name of the plugin that it maps to. If this is a name or alias that does not uniquely map to a known plugin, then the return value will be an empty string. More...
 
template<typename Interface >
std::unordered_set< std::stringPluginsImplementing () const
 Get plugin names that implement the specified interface. More...
 
std::unordered_set< std::stringPluginsImplementing (const std::string &_interface, const bool _demangled=true) const
 Get plugin names that implement the specified interface string. Note that the templated version of this function is recommended instead of this version to avoid confusion about whether a mangled or demangled version of a string is being used. Note that the function InterfacesImplemented() returns demangled versions of the interface names. More...
 
std::set< std::stringPluginsWithAlias (const std::string &_alias) const
 Get plugin names that correspond to the specified alias string. More...
 
std::string PrettyStr () const
 Makes a printable string with info about plugins. More...
 

Detailed Description

Class for loading plugins.

Constructor & Destructor Documentation

◆ Loader()

Loader ( )

Constructor.

◆ ~Loader()

~Loader ( )

Destructor.

Member Function Documentation

◆ AliasesOfPlugin()

std::set<std::string> AliasesOfPlugin ( const std::string _pluginName) const

Get the aliases of the plugin with the given name.

Parameters
[in]_pluginNameThe name of the desired plugin
Returns
A set of aliases corresponding to the desired plugin

◆ AllPlugins()

std::set<std::string> AllPlugins ( ) const

Get a set of the names of all plugins that are currently known to this Loader.

Returns
A set of all plugin names known to this Loader.

◆ Factory()

std::shared_ptr<InterfaceType> Factory ( const std::string _pluginNameOrAlias) const

Instantiates a plugin for the given plugin name, and then returns a reference-counting interface corresponding to InterfaceType.

If you use this function to retrieve a Factory, you can call Construct(...) on the returned interface, as long as the returned interface is not a nullptr.

Remarks
This function is identical to:
loader->Instantiate(_pluginNameOrAlias)
->QueryInterfaceSharedPtr<InterfaceType>();
Template Parameters
InterfaceTypeThe type of interface to look for. This function is meant for producing Factories, but any type of Interface can be requested.
Parameters
[in]_pluginNameOrAliasName or alias of the plugin that you want to use for production.
Returns
reference to an InterfaceType if it can be provided by the requested plugin.

◆ ForgetLibrary()

bool ForgetLibrary ( const std::string _pathToLibrary)

This loader will forget about the library at the given path location. If you want to instantiate a plugin from this library using this loader, you will first need to call LoadLib again.

After this function has been called, once all plugin instances that are tied to the library have been deleted, the library will automatically be unloaded from the executable. Note that when this Loader leaves scope (or gets deleted), it will have the same effect as calling ForgetLibrary on all of the libraries that it loaded, so there is generally no need to call this function. However, it may be useful if you want to reduce clutter in the Loader instance or let go of library resources that are no longer being used.

Note that even if you have released all references to a library, it is still up to the discretion of your operating system whether (or when) that library will be unloaded. In some cases, the operating system might not choose to unload it until the program exits completely.

Parameters
[in]_pathToLibraryPath to the library that you want to forget
Returns
True if the library was actively loaded and is now successfully forgotten. If the library was not actively loaded, this returns false.

◆ ForgetLibraryOfPlugin()

bool ForgetLibraryOfPlugin ( const std::string _pluginNameOrAlias)

Forget the library that provides the plugin with the given name. Note that this will also forget all other plugin types which are provided by that library.

Parameters
[in]_pluginNameOrAliasName or alias of the plugin whose library you want to forget.
See also
bool ForgetLibrary(const std::string &_pathToLibrary)

◆ Instantiate() [1/2]

PluginPtr Instantiate ( const std::string _pluginNameOrAlias) const

Instantiates a plugin for the given plugin name.

Parameters
[in]_pluginNameOrAliasName or alias of the plugin to instantiate.
Returns
Pointer to instantiated plugin

◆ Instantiate() [2/2]

PluginPtrType Instantiate ( const std::string _pluginNameOrAlias) const

Instantiates a plugin of PluginType for the given plugin name. This can be used to create a specialized PluginPtr.

Template Parameters
PluginPtrTypeThe specialized type of PluginPtrPtr that you want to construct.
Parameters
[in]_pluginNameOrAliasName or alias of the plugin that you want to instantiate.
Returns
pointer for the instantiated PluginPtr

◆ InterfacesImplemented()

std::unordered_set<std::string> InterfacesImplemented ( ) const

Get demangled names of interfaces that the loader has plugins for.

Returns
Demangled names of the interfaces that are implemented

◆ LoadLib()

std::unordered_set<std::string> LoadLib ( const std::string _pathToLibrary)

Load a library at the given path.

Parameters
[in]_pathToLibraryThe path to a library
Returns
The set of plugins that have been loaded from the library

◆ LookupPlugin()

std::string LookupPlugin ( const std::string _nameOrAlias) const

Resolve the plugin name or alias into the name of the plugin that it maps to. If this is a name or alias that does not uniquely map to a known plugin, then the return value will be an empty string.

Parameters
[in]_nameOrAliasThe name or alias of the plugin of interest.
Returns
The name of the plugin being referred to, or an empty string if no such plugin is known.

◆ PluginsImplementing() [1/2]

std::unordered_set<std::string> PluginsImplementing ( ) const

Get plugin names that implement the specified interface.

Returns
names of plugins that implement the interface.

◆ PluginsImplementing() [2/2]

std::unordered_set<std::string> PluginsImplementing ( const std::string _interface,
const bool  _demangled = true 
) const

Get plugin names that implement the specified interface string. Note that the templated version of this function is recommended instead of this version to avoid confusion about whether a mangled or demangled version of a string is being used. Note that the function InterfacesImplemented() returns demangled versions of the interface names.

If you want to pass in a mangled version of an interface name, e.g. the result that would be produced by typeid(T).name(), then set demangled to false.

Parameters
[in]_interfaceName of an interface
[in]_demangledSpecify whether the _interface string is demangled (default, true) or mangled (false).
Returns
Names of plugins that implement the interface

◆ PluginsWithAlias()

std::set<std::string> PluginsWithAlias ( const std::string _alias) const

Get plugin names that correspond to the specified alias string.

If there is more than one entry in this set, then the alias cannot be used to instantiate any of those plugins.

If the name of a plugin matches the alias string, then that plugin will be instantiated any time the string is used to instantiate a plugin, no matter how many other plugins use the alias.

Parameters
[in]_aliasThe std::string of the alias
Returns
A set of plugins that correspond to the desired alias

◆ PrettyStr()

std::string PrettyStr ( ) const

Makes a printable string with info about plugins.

Returns
A pretty string

The documentation for this class was generated from the following file: