Gazebo Plugin

API Reference

1.4.0
SpecializedPlugin< SpecInterface > Class Template Reference

This class allows Plugin instances to have high-speed access to interfaces that can be anticipated at compile time. The plugin does not have to actually offer the specialized interface in order to get this performance improvement. This template is variadic, so it can support arbitrarily many interfaces. More...

#include <SpecializedPlugin.hh>

Public Member Functions

template<class Interface >
bool HasInterface () const
 Checks if this Plugin has the specified type of interface. More...
 
template<class Interface >
bool HasInterface () const
 
bool HasInterface (const std::string &_interfaceName, const bool _demangled=true) const
 Checks if this Plugin has the specified type of interface. More...
 
template<class Interface >
Interface * QueryInterface ()
 Get an interface of the specified type, if it is provided by this plugin. More...
 
template<class Interface >
Interface * QueryInterface ()
 
template<class Interface >
const Interface * QueryInterface () const
 const-qualified version of QueryInterface<Interface>() More...
 
template<class Interface >
const Interface * QueryInterface () const
 
template<class Interface >
Interface * QueryInterface (const std::string &)
 This function has been deprecated in favor of the version of QueryInterface which does not take a std::string argument. More...
 
template<class Interface >
const Interface * QueryInterface (const std::string &) const
 const-qualified version of QueryInterface<Interface>(std::string) More...
 
template<class Interface >
std::shared_ptr< Interface > QueryInterfaceSharedPtr ()
 Get the requested interface as a std::shared_ptr. The template argument Interface must exactly match the underlying type associated with _interfaceName, or else the behavior of this function is undefined. More...
 
template<class Interface >
std::shared_ptr< Interface > QueryInterfaceSharedPtr ()
 
template<class Interface >
std::shared_ptr< const Interface > QueryInterfaceSharedPtr () const
 Same as QueryInterfaceSharedPtr<Interface>(), but it returns a std::shared_ptr to a const-qualified Interface. More...
 
template<class Interface >
std::shared_ptr< const Interface > QueryInterfaceSharedPtr () const
 
template<class Interface >
std::shared_ptr< Interface > QueryInterfaceSharedPtr (const std::string &)
 This version of QueryInterfaceSharedPtr has been deprecated in favor of the version that does not take a std::string argument. More...
 
template<class Interface >
std::shared_ptr< const Interface > QueryInterfaceSharedPtr (const std::string &) const
 Same as QueryInterfaceSharedPtr<Interface>(std::string), but it returns a std::shared_ptr to a const-qualified Interface. More...
 
- Public Member Functions inherited from Plugin
virtual ~Plugin ()
 Virtual destructor. More...
 
template<class Interface >
bool HasInterface () const
 Checks if this Plugin has the specified type of interface. More...
 
bool HasInterface (const std::string &_interfaceName, const bool _demangled=true) const
 Checks if this Plugin has the specified type of interface. More...
 
const std::stringName () const
 Gets the name of this Plugin. More...
 
template<class Interface >
Interface * QueryInterface ()
 Get an interface of the specified type, if it is provided by this plugin. More...
 
template<class Interface >
const Interface * QueryInterface () const
 const-qualified version of QueryInterface<Interface>() More...
 
template<class Interface >
Interface * QueryInterface (const std::string &)
 This function has been deprecated in favor of the version of QueryInterface which does not take a std::string argument. More...
 
template<class Interface >
const Interface * QueryInterface (const std::string &) const
 const-qualified version of QueryInterface<Interface>(std::string) More...
 
template<class Interface >
std::shared_ptr< Interface > QueryInterfaceSharedPtr ()
 Get the requested interface as a std::shared_ptr. The template argument Interface must exactly match the underlying type associated with _interfaceName, or else the behavior of this function is undefined. More...
 
template<class Interface >
std::shared_ptr< const Interface > QueryInterfaceSharedPtr () const
 Same as QueryInterfaceSharedPtr<Interface>(), but it returns a std::shared_ptr to a const-qualified Interface. More...
 
template<class Interface >
std::shared_ptr< Interface > QueryInterfaceSharedPtr (const std::string &)
 This version of QueryInterfaceSharedPtr has been deprecated in favor of the version that does not take a std::string argument. More...
 
template<class Interface >
std::shared_ptr< const Interface > QueryInterfaceSharedPtr (const std::string &) const
 Same as QueryInterfaceSharedPtr<Interface>(std::string), but it returns a std::shared_ptr to a const-qualified Interface. More...
 

Protected Member Functions

 SpecializedPlugin ()
 Default constructor. More...
 
- Protected Member Functions inherited from Plugin
 Plugin ()
 Default constructor. This is kept protected to discourage users from instantiating them directly. They should instead only be retrieved as a PluginPtr from the plugin Loader. More...
 

Additional Inherited Members

- Public Types inherited from Plugin
using InterfaceMap = std::map< std::string, void * >
 The InterfaceMap type needs to get used in several places, like Plugin::Implementation and SpecializedPlugin<T>. We make the typedef public so that those other classes can use it without needing to be friends of Plugin. End-users should not have any need for this typedef. More...
 

Detailed Description

template<class SpecInterface>
class ignition::plugin::SpecializedPlugin< SpecInterface >

This class allows Plugin instances to have high-speed access to interfaces that can be anticipated at compile time. The plugin does not have to actually offer the specialized interface in order to get this performance improvement. This template is variadic, so it can support arbitrarily many interfaces.

Usage example:

using MySpecialPluginPtr = SpecializedPluginPtr<
MyInterface1, FooInterface, MyInterface2, BarInterface>;
MySpecialPluginPtr plugin = loader->Instantiate(pluginName);

Then, calling the function

plugin->QueryInterface<FooInterface>();

will have extremely high-speed associated with it. It will provide direct access to the the FooInterface* of plugin. If plugin does not actually offer FooInterface, then it will return a nullptr, still at extremely high speed.

Constructor & Destructor Documentation

◆ SpecializedPlugin()

SpecializedPlugin ( )
protected

Default constructor.

Member Function Documentation

◆ HasInterface() [1/3]

bool HasInterface ( class Interface  )

Checks if this Plugin has the specified type of interface.

Returns
Returns true if this Plugin has the specified type of interface, and false otherwise.

◆ HasInterface() [2/3]

bool HasInterface ( ) const

◆ HasInterface() [3/3]

bool HasInterface

Checks if this Plugin has the specified type of interface.

By default, we expect you to pass in a demangled version of the interface name. If you want to use a mangled version of the name, set the demangled argument to false.

Parameters
[in]_interfaceNameThe name of the desired interface, as a std::string. Note that this expects the name to be mangled.
[in]_demangledIf _interfaceName is demangled, set this to true. If you are instead using the raw mangled name that gets provided by typeid(T).name(), then set _demangled to false.
Returns
Returns true if this Plugin has the specified type of interface, and false otherwise.

◆ QueryInterface() [1/6]

Interface* QueryInterface ( class Interface  )

Get an interface of the specified type, if it is provided by this plugin.

Note that the interface pointer you receive is owned by the Plugin object. You MUST NOT ever try to deallocate it yourself. Moreover, the pointer will be invalidated once all Plugin objects that refer to the same Plugin instance are destructed. Use the QueryInterfaceSharedPtr function in order to get a reference-counting pointer to an interface of this Plugin object. The pointer will remain valid as long as the std::shared_ptr provided by QueryInterfaceSharedPtr is alive.

Returns
A raw pointer to the specified interface. If the requested _interfaceName is not provided by this Plugin, this returns a nullptr. This pointer is invalidated when the reference count of the plugin instance drops to zero.

◆ QueryInterface() [2/6]

Interface* QueryInterface ( )

◆ QueryInterface() [3/6]

const Interface* QueryInterface ( class Interface  )

const-qualified version of QueryInterface<Interface>()

◆ QueryInterface() [4/6]

const Interface* QueryInterface ( ) const

◆ QueryInterface() [5/6]

Interface* QueryInterface ( class Interface  )

This function has been deprecated in favor of the version of QueryInterface which does not take a std::string argument.

◆ QueryInterface() [6/6]

const Interface* QueryInterface ( class Interface  )

const-qualified version of QueryInterface<Interface>(std::string)

◆ QueryInterfaceSharedPtr() [1/6]

std::shared_ptr<Interface> QueryInterfaceSharedPtr ( class Interface  )

Get the requested interface as a std::shared_ptr. The template argument Interface must exactly match the underlying type associated with _interfaceName, or else the behavior of this function is undefined.

This std::shared_ptr and the interface+plugin that it refers to will remain valid, even if all Plugin objects which refer to the plugin instance are destructed.

You MUST NOT attempt to pass a QueryInterface pointer into a std::shared_ptr yourself; that will result in double-delete memory errors. You must always call QueryInterfaceSharedPtr for a reference- counting pointer to an interface.

Returns
A reference-counting pointer to the specified interface. This will keep the interface valid and the plugin instance alive, even if all Plugin objects that refer to this plugin instance are destructed.

◆ QueryInterfaceSharedPtr() [2/6]

std::shared_ptr<Interface> QueryInterfaceSharedPtr ( )

◆ QueryInterfaceSharedPtr() [3/6]

std::shared_ptr<const Interface> QueryInterfaceSharedPtr ( class Interface  )

Same as QueryInterfaceSharedPtr<Interface>(), but it returns a std::shared_ptr to a const-qualified Interface.

◆ QueryInterfaceSharedPtr() [4/6]

std::shared_ptr<const Interface> QueryInterfaceSharedPtr ( ) const

◆ QueryInterfaceSharedPtr() [5/6]

std::shared_ptr<Interface> QueryInterfaceSharedPtr ( class Interface  )

This version of QueryInterfaceSharedPtr has been deprecated in favor of the version that does not take a std::string argument.

◆ QueryInterfaceSharedPtr() [6/6]

std::shared_ptr<const Interface> QueryInterfaceSharedPtr ( class Interface  )

Same as QueryInterfaceSharedPtr<Interface>(std::string), but it returns a std::shared_ptr to a const-qualified Interface.


The documentation for this class was generated from the following file:
TemplatePluginPtr< SpecializedPlugin< SpecInterfaces... > > SpecializedPluginPtr
This alias allows PluginPtr instances to have high-speed access to interfaces that can be anticipated...
Definition: gz/plugin/SpecializedPluginPtr.hh:65