Public Types | Public Member Functions | Private Member Functions | Private Attributes | List of all members
pluginlib::ClassLoader< T > Class Template Reference

A class to help manage and load classes. More...

#include <class_loader.hpp>

Inheritance diagram for pluginlib::ClassLoader< T >:
Inheritance graph
[legend]

Public Types

typedef std::map< std::string, ClassDesc >::iterator ClassMapIterator
 

Public Member Functions

 ClassLoader (std::string package, std::string base_class, std::string attrib_name=std::string("plugin"), std::vector< std::string > plugin_xml_paths=std::vector< std::string >())
 
T * createClassInstance (const std::string &lookup_name, bool auto_load=true)
 Create an instance of a desired class, optionally loading the associated library too. More...
 
boost::shared_ptr< T > createInstance (const std::string &lookup_name)
 Create an instance of a desired class. More...
 
T * createUnmanagedInstance (const std::string &lookup_name)
 Create an instance of a desired class. More...
 
virtual std::string getBaseClassType () const
 Given the lookup name of a class, return the type of the associated base class. More...
 
virtual std::string getClassDescription (const std::string &lookup_name)
 Given the lookup name of a class, return its description. More...
 
virtual std::string getClassLibraryPath (const std::string &lookup_name)
 Given the name of a class, return the path to its associated library. More...
 
virtual std::string getClassPackage (const std::string &lookup_name)
 Given the name of a class, return name of the containing package. More...
 
virtual std::string getClassType (const std::string &lookup_name)
 Given the lookup name of a class, return the type of the derived class associated with it. More...
 
std::vector< std::string > getDeclaredClasses ()
 Return a list of all available classes for this ClassLoader's base class type. More...
 
virtual std::string getName (const std::string &lookup_name)
 Strip the package name off of a lookup name. More...
 
virtual std::string getPluginManifestPath (const std::string &lookup_name)
 Given the name of a class, return the path of the associated plugin manifest. More...
 
std::vector< std::string > getPluginXmlPaths ()
 Return a list of all available plugin manifest paths for this ClassLoader's base class type. More...
 
virtual std::vector< std::string > getRegisteredLibraries ()
 Return the libraries that are registered and can be loaded. More...
 
virtual bool isClassAvailable (const std::string &lookup_name)
 Check if the class associated with a plugin name is available to be loaded. More...
 
bool isClassLoaded (const std::string &lookup_name)
 Check if the library for a given class is currently loaded. More...
 
virtual void loadLibraryForClass (const std::string &lookup_name)
 Attempt to load the library containing a class with a given name. More...
 
virtual void refreshDeclaredClasses ()
 Refresh the list of all available classes for this ClassLoader's base class type. More...
 
virtual int unloadLibraryForClass (const std::string &lookup_name)
 Decrement the counter for the library containing a class with a given name. More...
 
 ~ClassLoader () override
 The destructor attempts to unload all libraries which are still loaded. More...
 
- Public Member Functions inherited from pluginlib::ClassLoaderBase
virtual ~ClassLoaderBase ()
 Empty virtual destructor. More...
 

Private Member Functions

std::map< std::string, ClassDescdetermineAvailableClasses (const std::vector< std::string > &plugin_xml_paths)
 Return the available classes. More...
 
std::string extractPackageNameFromPackageXML (const std::string &package_xml_path)
 Open a package.xml file and extract the package name (i.e. contents of <name> tag). More...
 
std::vector< std::string > getAllLibraryPathsToTry (const std::string &library_name, const std::string &exporting_package_name)
 Get a list of paths to try to find a library. More...
 
std::vector< std::string > getCatkinLibraryPaths ()
 Return the paths where libraries are installed according to the Catkin build system. More...
 
std::string getErrorStringForUnknownClass (const std::string &lookup_name)
 Return an error message for an unknown class. More...
 
std::string getPackageFromPluginXMLFilePath (const std::string &path)
 Get the package name from a path to a plugin XML file. More...
 
std::string getPathSeparator ()
 Get the standard path separator for the native OS (e.g. "/" on *nix, "\" on Windows). More...
 
std::vector< std::string > getPluginXmlPaths (const std::string &package, const std::string &attrib_name, bool force_recrawl=false)
 Return the paths to plugin.xml files. More...
 
std::string getROSBuildLibraryPath (const std::string &exporting_package_name)
 Given a package name, return the path where rosbuild thinks plugins are installed. More...
 
std::string joinPaths (const std::string &path1, const std::string &path2)
 Join two filesystem paths together utilzing appropriate path separator. More...
 
void processSingleXMLPluginFile (const std::string &xml_file, std::map< std::string, ClassDesc > &class_available)
 Parse a plugin XML file. More...
 
std::string stripAllButFileFromPath (const std::string &path)
 Strip all but the filename from an explicit file path. More...
 
int unloadClassLibraryInternal (const std::string &library_path)
 Helper function for unloading a shared library. More...
 

Private Attributes

std::string attrib_name_
 
std::string base_class_
 
std::map< std::string, ClassDescclasses_available_
 
class_loader::MultiLibraryClassLoader lowlevel_class_loader_
 
std::string package_
 
std::vector< std::string > plugin_xml_paths_
 

Detailed Description

template<class T>
class pluginlib::ClassLoader< T >

A class to help manage and load classes.

Definition at line 61 of file class_loader.hpp.

Member Typedef Documentation

◆ ClassMapIterator

template<class T >
typedef std::map<std::string, ClassDesc>::iterator pluginlib::ClassLoader< T >::ClassMapIterator

Definition at line 64 of file class_loader.hpp.

Constructor & Destructor Documentation

◆ ClassLoader()

template<class T >
pluginlib::ClassLoader< T >::ClassLoader ( std::string  package,
std::string  base_class,
std::string  attrib_name = std::string("plugin"),
std::vector< std::string >  plugin_xml_paths = std::vector<std::string>() 
)
Parameters
packageThe package containing the base class
base_classThe type of the base class for classes to be loaded
attrib_nameThe attribute to search for in manifext.xml files, defaults to "plugin"
plugin_xml_pathsThe list of paths of plugin.xml files, defaults to be crawled via ros::package::getPlugins()
Exceptions
pluginlib::ClassLoaderExceptionif package manifest cannot be found

Definition at line 68 of file class_loader_imp.hpp.

◆ ~ClassLoader()

template<class T >
pluginlib::ClassLoader< T >::~ClassLoader
override

The destructor attempts to unload all libraries which are still loaded.

Exceptions
class_loader::LibraryUnloadExceptionif unloading a library fails

Definition at line 98 of file class_loader_imp.hpp.

Member Function Documentation

◆ createClassInstance()

template<class T >
T * pluginlib::ClassLoader< T >::createClassInstance ( const std::string &  lookup_name,
bool  auto_load = true 
)

Create an instance of a desired class, optionally loading the associated library too.

Parameters
lookup_nameThe name of the class to load
auto_loadSpecifies whether or not to automatically load the library containing the class, set to true by default.
Exceptions
pluginlib::LibraryLoadExceptionwhen the library associated with the class cannot be loaded
pluginlib::CreateClassExceptionwhen the class cannot be instantiated
Returns
An instance of the class
Deprecated:
use either createInstance() or createUnmanagedInstance()

Definition at line 107 of file class_loader_imp.hpp.

◆ createInstance()

template<class T >
boost::shared_ptr< T > pluginlib::ClassLoader< T >::createInstance ( const std::string &  lookup_name)

Create an instance of a desired class.

Implicitly calls loadLibraryForClass() to increment the library counter.

Deleting the instance and calling unloadLibraryForClass() is automatically handled by the shared pointer.

Parameters
lookup_nameThe name of the class to load
Exceptions
pluginlib::LibraryLoadExceptionwhen the library associated with the class cannot be loaded
pluginlib::CreateClassExceptionwhen the class cannot be instantiated
Returns
An instance of the class

Definition at line 136 of file class_loader_imp.hpp.

◆ createUnmanagedInstance()

template<class T >
T * pluginlib::ClassLoader< T >::createUnmanagedInstance ( const std::string &  lookup_name)

Create an instance of a desired class.

Implicitly calls loadLibraryForClass() to increment the library counter.

Attention
The ownership is transfered to the caller, which is responsible for deleting the instance and calling unloadLibraryForClass() (in order to decrement the associated library counter and unloading it if it is no more used).
Parameters
lookup_nameThe name of the class to load
Exceptions
pluginlib::LibraryLoadExceptionwhen the library associated with the class cannot be loaded
pluginlib::CreateClassExceptionwhen the class cannot be instantiated
Returns
An instance of the class

Definition at line 200 of file class_loader_imp.hpp.

◆ determineAvailableClasses()

template<class T >
std::map< std::string, ClassDesc > pluginlib::ClassLoader< T >::determineAvailableClasses ( const std::vector< std::string > &  plugin_xml_paths)
private

Return the available classes.

Parameters
plugin_xml_pathsThe vector of paths of plugin.xml files
Exceptions
pluginlib::LibraryLoadExceptionif package manifest cannot be found
Returns
A map of class names and the corresponding descriptions

Definition at line 243 of file class_loader_imp.hpp.

◆ extractPackageNameFromPackageXML()

template<class T >
std::string pluginlib::ClassLoader< T >::extractPackageNameFromPackageXML ( const std::string &  package_xml_path)
private

Open a package.xml file and extract the package name (i.e. contents of <name> tag).

Parameters
package_xml_pathThe path to the package.xml file
Returns
The name of the package if successful, otherwise an empty string

Definition at line 273 of file class_loader_imp.hpp.

◆ getAllLibraryPathsToTry()

template<class T >
std::vector< std::string > pluginlib::ClassLoader< T >::getAllLibraryPathsToTry ( const std::string &  library_name,
const std::string &  exporting_package_name 
)
private

Get a list of paths to try to find a library.

As we transition from rosbuild to Catkin build systems, plugins can be found in the old rosbuild place (pkg_name/lib usually) or somewhere in the Catkin build space.

Definition at line 333 of file class_loader_imp.hpp.

◆ getBaseClassType()

template<class T >
std::string pluginlib::ClassLoader< T >::getBaseClassType
virtual

Given the lookup name of a class, return the type of the associated base class.

Returns
The type of the associated base class

Implements pluginlib::ClassLoaderBase.

Definition at line 386 of file class_loader_imp.hpp.

◆ getCatkinLibraryPaths()

template<class T >
std::vector< std::string > pluginlib::ClassLoader< T >::getCatkinLibraryPaths
private

Return the paths where libraries are installed according to the Catkin build system.

Definition at line 310 of file class_loader_imp.hpp.

◆ getClassDescription()

template<class T >
std::string pluginlib::ClassLoader< T >::getClassDescription ( const std::string &  lookup_name)
virtual

Given the lookup name of a class, return its description.

Parameters
lookup_nameThe lookup name of the class
Returns
The description of the class

Implements pluginlib::ClassLoaderBase.

Definition at line 393 of file class_loader_imp.hpp.

◆ getClassLibraryPath()

template<class T >
std::string pluginlib::ClassLoader< T >::getClassLibraryPath ( const std::string &  lookup_name)
virtual

Given the name of a class, return the path to its associated library.

Parameters
lookup_nameThe name of the class
Returns
The path to the associated library

Implements pluginlib::ClassLoaderBase.

Definition at line 415 of file class_loader_imp.hpp.

◆ getClassPackage()

template<class T >
std::string pluginlib::ClassLoader< T >::getClassPackage ( const std::string &  lookup_name)
virtual

Given the name of a class, return name of the containing package.

Parameters
lookup_nameThe name of the class
Returns
The name of the containing package

Implements pluginlib::ClassLoaderBase.

Definition at line 451 of file class_loader_imp.hpp.

◆ getClassType()

template<class T >
std::string pluginlib::ClassLoader< T >::getClassType ( const std::string &  lookup_name)
virtual

Given the lookup name of a class, return the type of the derived class associated with it.

Parameters
lookup_nameThe name of the class
Returns
The name of the associated derived class

Implements pluginlib::ClassLoaderBase.

Definition at line 404 of file class_loader_imp.hpp.

◆ getDeclaredClasses()

template<class T >
std::vector< std::string > pluginlib::ClassLoader< T >::getDeclaredClasses
virtual

Return a list of all available classes for this ClassLoader's base class type.

Returns
A vector of strings corresponding to the names of all available classes

Implements pluginlib::ClassLoaderBase.

Definition at line 469 of file class_loader_imp.hpp.

◆ getErrorStringForUnknownClass()

template<class T >
std::string pluginlib::ClassLoader< T >::getErrorStringForUnknownClass ( const std::string &  lookup_name)
private

Return an error message for an unknown class.

Parameters
lookup_nameThe name of the class
Returns
The error message

Definition at line 481 of file class_loader_imp.hpp.

◆ getName()

template<class T >
std::string pluginlib::ClassLoader< T >::getName ( const std::string &  lookup_name)
virtual

Strip the package name off of a lookup name.

Parameters
lookup_nameThe name of the plugin
Returns
The name of the plugin stripped of the package name

Implements pluginlib::ClassLoaderBase.

Definition at line 495 of file class_loader_imp.hpp.

◆ getPackageFromPluginXMLFilePath()

template<class T >
std::string pluginlib::ClassLoader< T >::getPackageFromPluginXMLFilePath ( const std::string &  path)
private

Get the package name from a path to a plugin XML file.

Definition at line 506 of file class_loader_imp.hpp.

◆ getPathSeparator()

template<class T >
std::string pluginlib::ClassLoader< T >::getPathSeparator
private

Get the standard path separator for the native OS (e.g. "/" on *nix, "\" on Windows).

Definition at line 561 of file class_loader_imp.hpp.

◆ getPluginManifestPath()

template<class T >
std::string pluginlib::ClassLoader< T >::getPluginManifestPath ( const std::string &  lookup_name)
virtual

Given the name of a class, return the path of the associated plugin manifest.

Parameters
lookup_nameThe name of the class
Returns
The path of the associated plugin manifest

Implements pluginlib::ClassLoaderBase.

Definition at line 577 of file class_loader_imp.hpp.

◆ getPluginXmlPaths() [1/2]

template<class T >
std::vector< std::string > pluginlib::ClassLoader< T >::getPluginXmlPaths
virtual

Return a list of all available plugin manifest paths for this ClassLoader's base class type.

Returns
A vector of strings corresponding to the paths of all available plugin manifests

Implements pluginlib::ClassLoaderBase.

Definition at line 462 of file class_loader_imp.hpp.

◆ getPluginXmlPaths() [2/2]

template<class T >
std::vector< std::string > pluginlib::ClassLoader< T >::getPluginXmlPaths ( const std::string &  package,
const std::string &  attrib_name,
bool  force_recrawl = false 
)
private

Return the paths to plugin.xml files.

Exceptions
pluginlib::LibraryLoadExceptionif package manifest cannot be found
Returns
A vector of paths

Definition at line 230 of file class_loader_imp.hpp.

◆ getRegisteredLibraries()

template<class T >
std::vector< std::string > pluginlib::ClassLoader< T >::getRegisteredLibraries
virtual

Return the libraries that are registered and can be loaded.

Returns
A vector of strings corresponding to the names of registered libraries

Implements pluginlib::ClassLoaderBase.

Definition at line 589 of file class_loader_imp.hpp.

◆ getROSBuildLibraryPath()

template<class T >
std::string pluginlib::ClassLoader< T >::getROSBuildLibraryPath ( const std::string &  exporting_package_name)
private

Given a package name, return the path where rosbuild thinks plugins are installed.

Definition at line 596 of file class_loader_imp.hpp.

◆ isClassAvailable()

template<class T >
bool pluginlib::ClassLoader< T >::isClassAvailable ( const std::string &  lookup_name)
virtual

Check if the class associated with a plugin name is available to be loaded.

Parameters
lookup_nameThe name of the plugin
Returns
true if the plugin is available, false otherwise

Implements pluginlib::ClassLoaderBase.

Definition at line 603 of file class_loader_imp.hpp.

◆ isClassLoaded()

template<class T >
bool pluginlib::ClassLoader< T >::isClassLoaded ( const std::string &  lookup_name)
virtual

Check if the library for a given class is currently loaded.

Parameters
lookup_nameThe lookup name of the class to query
Returns
True if the class is loaded, false otherwise

Implements pluginlib::ClassLoaderBase.

Definition at line 379 of file class_loader_imp.hpp.

◆ joinPaths()

template<class T >
std::string pluginlib::ClassLoader< T >::joinPaths ( const std::string &  path1,
const std::string &  path2 
)
private

Join two filesystem paths together utilzing appropriate path separator.

Definition at line 610 of file class_loader_imp.hpp.

◆ loadLibraryForClass()

template<class T >
void pluginlib::ClassLoader< T >::loadLibraryForClass ( const std::string &  lookup_name)
virtual

Attempt to load the library containing a class with a given name.

The counter for the library uses (refcount) is also incremented.

Parameters
lookup_nameThe lookup name of the class to load
Exceptions
pluginlib::LibraryLoadExceptionif the library for the class cannot be loaded

Implements pluginlib::ClassLoaderBase.

Definition at line 618 of file class_loader_imp.hpp.

◆ processSingleXMLPluginFile()

template<class T >
void pluginlib::ClassLoader< T >::processSingleXMLPluginFile ( const std::string &  xml_file,
std::map< std::string, ClassDesc > &  class_available 
)
private

Parse a plugin XML file.

Also insert the appropriate ClassDesc entries into the passes classes_available map.

Definition at line 653 of file class_loader_imp.hpp.

◆ refreshDeclaredClasses()

template<class T >
void pluginlib::ClassLoader< T >::refreshDeclaredClasses
virtual

Refresh the list of all available classes for this ClassLoader's base class type.

Exceptions
pluginlib::LibraryLoadExceptionif package manifest cannot be found

Implements pluginlib::ClassLoaderBase.

Definition at line 768 of file class_loader_imp.hpp.

◆ stripAllButFileFromPath()

template<class T >
std::string pluginlib::ClassLoader< T >::stripAllButFileFromPath ( const std::string &  path)
private

Strip all but the filename from an explicit file path.

Parameters
pathThe path to strip
Returns
The basename of the path

Definition at line 802 of file class_loader_imp.hpp.

◆ unloadClassLibraryInternal()

template<class T >
int pluginlib::ClassLoader< T >::unloadClassLibraryInternal ( const std::string &  library_path)
private

Helper function for unloading a shared library.

Parameters
library_pathThe exact path to the library to unload
Returns
The number of pending unloads until the library is removed from memory

Definition at line 830 of file class_loader_imp.hpp.

◆ unloadLibraryForClass()

template<class T >
int pluginlib::ClassLoader< T >::unloadLibraryForClass ( const std::string &  lookup_name)
virtual

Decrement the counter for the library containing a class with a given name.

Also try to unload the library, If the counter reaches zero.

Parameters
lookup_nameThe lookup name of the class to unload
Exceptions
pluginlib::LibraryUnloadExceptionif the library for the class cannot be unloaded
Returns
The number of pending unloads until the library is removed from memory

Implements pluginlib::ClassLoaderBase.

Definition at line 815 of file class_loader_imp.hpp.

Member Data Documentation

◆ attrib_name_

template<class T >
std::string pluginlib::ClassLoader< T >::attrib_name_
private

Definition at line 347 of file class_loader.hpp.

◆ base_class_

template<class T >
std::string pluginlib::ClassLoader< T >::base_class_
private

Definition at line 346 of file class_loader.hpp.

◆ classes_available_

template<class T >
std::map<std::string, ClassDesc> pluginlib::ClassLoader< T >::classes_available_
private

Definition at line 344 of file class_loader.hpp.

◆ lowlevel_class_loader_

template<class T >
class_loader::MultiLibraryClassLoader pluginlib::ClassLoader< T >::lowlevel_class_loader_
private

Definition at line 348 of file class_loader.hpp.

◆ package_

template<class T >
std::string pluginlib::ClassLoader< T >::package_
private

Definition at line 345 of file class_loader.hpp.

◆ plugin_xml_paths_

template<class T >
std::vector<std::string> pluginlib::ClassLoader< T >::plugin_xml_paths_
private

Definition at line 342 of file class_loader.hpp.


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


pluginlib
Author(s): Eitan Marder-Eppstein, Tully Foote, Dirk Thomas, Mirza Shah
autogenerated on Tue Jul 9 2024 02:50:20