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

#include <class_loader.hpp>

Inheritance diagram for pluginlib::ClassLoader< T >:

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, ClassDesc >	determineAvailableClasses (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, ClassDesc >	classes_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

package	The package containing the base class
base_class	The type of the base class for classes to be loaded
attrib_name	The attribute to search for in manifext.xml files, defaults to "plugin"
plugin_xml_paths	The list of paths of plugin.xml files, defaults to be crawled via ros::package::getPlugins()

Exceptions

pluginlib::ClassLoaderException if 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::LibraryUnloadException if 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_name	The name of the class to load
auto_load	Specifies whether or not to automatically load the library containing the class, set to true by default.

Exceptions

pluginlib::LibraryLoadException	when the library associated with the class cannot be loaded
pluginlib::CreateClassException	when 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_name The name of the class to load

Exceptions

pluginlib::LibraryLoadException	when the library associated with the class cannot be loaded
pluginlib::CreateClassException	when 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_name The name of the class to load

Exceptions

pluginlib::LibraryLoadException	when the library associated with the class cannot be loaded
pluginlib::CreateClassException	when 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_paths The vector of paths of plugin.xml files

Exceptions

pluginlib::LibraryLoadException if 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_path The 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_name The 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_name The 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_name The 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_name The 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_name The 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_name The 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_name The 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::LibraryLoadException if 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_name The 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_name The 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_name The lookup name of the class to load

Exceptions

pluginlib::LibraryLoadException if 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::LibraryLoadException if 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

path	The 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_path The 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_name The lookup name of the class to unload

Exceptions

pluginlib::LibraryUnloadException if the library for the class cannot be unloaded

Returns: The number of pending unloads until the library is removed from memory

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:

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

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

Member Typedef Documentation

◆ ClassMapIterator

Constructor & Destructor Documentation

◆ ClassLoader()

◆ ~ClassLoader()

Member Function Documentation

◆ createClassInstance()

◆ createInstance()

◆ createUnmanagedInstance()

◆ determineAvailableClasses()

◆ extractPackageNameFromPackageXML()

◆ getAllLibraryPathsToTry()

◆ getBaseClassType()

◆ getCatkinLibraryPaths()

◆ getClassDescription()

◆ getClassLibraryPath()

◆ getClassPackage()

◆ getClassType()

◆ getDeclaredClasses()

◆ getErrorStringForUnknownClass()

◆ getName()

◆ getPackageFromPluginXMLFilePath()

◆ getPathSeparator()

◆ getPluginManifestPath()

◆ getPluginXmlPaths() [1/2]

◆ getPluginXmlPaths() [2/2]

◆ getRegisteredLibraries()

◆ getROSBuildLibraryPath()

◆ isClassAvailable()

◆ isClassLoaded()

◆ joinPaths()

◆ loadLibraryForClass()

◆ processSingleXMLPluginFile()

◆ refreshDeclaredClasses()

◆ stripAllButFileFromPath()

◆ unloadClassLibraryInternal()

◆ unloadLibraryForClass()

Member Data Documentation

◆ attrib_name_

◆ base_class_

◆ classes_available_

◆ lowlevel_class_loader_

◆ package_

◆ plugin_xml_paths_

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