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 ()

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 69 of file class_loader_imp.hpp.

◆ ~ClassLoader()

template<class T >

pluginlib::ClassLoader< T >::~ClassLoader ( )

Definition at line 99 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 108 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 137 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 201 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 244 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 274 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 334 of file class_loader_imp.hpp.

◆ getBaseClassType()

template<class T >

std::string pluginlib::ClassLoader< T >::getBaseClassType ( ) const

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 387 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 311 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 394 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 416 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 449 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 405 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 467 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 479 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 493 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 504 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 559 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 575 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 460 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 231 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 587 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 594 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 601 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 380 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 608 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 616 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 651 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 766 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 800 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 828 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 338 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 >