gz/plugin/Register.hh File Reference

#include <gz/plugin/detail/Register.hh>

Go to the source code of this file.

Macros
#define	IGNITION_ADD_FACTORY(ProductType, FactoryType)   DETAIL_IGNITION_ADD_FACTORY(ProductType, FactoryType)
	Add a plugin factory. More...
#define	IGNITION_ADD_FACTORY_ALIAS(ProductType, FactoryType, ...)   DETAIL_IGNITION_ADD_FACTORY_ALIAS(ProductType, FactoryType, __VA_ARGS__)
	Add an alias for a factory. More...
#define	IGNITION_ADD_PLUGIN(PluginClass, ...)   DETAIL_IGNITION_ADD_PLUGIN(PluginClass, __VA_ARGS__)
	Add a plugin and interface from this shared library. More...
#define	IGNITION_ADD_PLUGIN_ALIAS(PluginClass, ...)   DETAIL_IGNITION_ADD_PLUGIN_ALIAS(PluginClass, __VA_ARGS__)
	Add an alias for one of your plugins. More...

Macro Definition Documentation

IGNITION_ADD_FACTORY

#define IGNITION_ADD_FACTORY	(		ProductType,
			FactoryType
	)		DETAIL_IGNITION_ADD_FACTORY(ProductType, FactoryType)

Add a plugin factory.

A plugin factory is a plugin that is able to generate objects that implement some interface. These objects can be passed off to a consumer, and as long as the object is alive, it will ensure that the shared library of the plugin remains loaded. The objects are handed off with a std::unique_ptr, so the raw pointer can be released from its std::unique_ptr and passed into any memory management system the consumer prefers.

The inputs and output of a factory are defined using the ignition::plugin::Factory class in the ignition/plugin/Factory.hh header.

The first argument of this macro should be the class that implements the factory's output interface. The second argument should be the factory definition.

NOTE: If your factory has any input arguments, then you must define it outside of this macro, or else you will get a compilation error. This happens because macros will parse the commas between your template arguments as separators for the macro arguments. For example:

   class MyBase
   {
     public: virtual double SomeFunction() = 0;
   };
  
   class MyType : public MyBase
   {
     public: MyType(double value);
     public: double SomeFunction() override;
   };
  
   /* BAD! Will not compile:
*  IGNITION_ADD_FACTORY(MyType, ignition::plugin::Factory<MyBase, double>);
   */
  
   // Instead do this:
   using MyFactory = ignition::plugin::Factory<MyBase, double>;
   IGNITION_ADD_FACTORY(MyType, MyFactory);

IGNITION_ADD_FACTORY_ALIAS

#define IGNITION_ADD_FACTORY_ALIAS	(		ProductType,
			FactoryType,
			...
	)		DETAIL_IGNITION_ADD_FACTORY_ALIAS(ProductType, FactoryType, __VA_ARGS__)

Add an alias for a factory.

This will do the same as IGNITION_ADD_FACTORY(), but you may also add in any number of strings which can then be used as aliases for this factory. For example:

IGNITION_ADD_FACTORY_ALIAS(MyType, MyFactory, "Foo", "My favorite factory")

This macro can be called any number of times for the same factory or for different factories. If you call this macro, you do not need to call IGNITION_ADD_FACTORY(), but there is nothing wrong with calling both (except it might imperceptibly increase your compile time).

IGNITION_ADD_PLUGIN

#define IGNITION_ADD_PLUGIN	(		PluginClass,
			...
	)		DETAIL_IGNITION_ADD_PLUGIN(PluginClass, __VA_ARGS__)

Add a plugin and interface from this shared library.

This macro can be put in any namespace and may be called any number of times. It can be called multiple times on the same plugin class in order to register multiple interfaces, e.g.:

IGNITION_ADD_PLUGIN(PluginClass, Interface1)
IGNITION_ADD_PLUGIN(PluginClass, Interface2)
 
/* Some other code */
 
IGNITION_ADD_PLUGIN(PluginClass, Interface3)

Or you can list multiple interfaces in a single call to the macro, e.g.:

IGNITION_ADD_PLUGIN(PluginClass, Interface1, Interface2, Interface3)

If your library has multiple translation units (.cpp files) and you want to register plugins in multiple translation units, use this ignition/plugin/Register.hh header in ONE of the translation units, and then the ignition/plugin/RegisterMore.hh header in all of the rest of the translation units.

IGNITION_ADD_PLUGIN_ALIAS

#define IGNITION_ADD_PLUGIN_ALIAS	(		PluginClass,
			...
	)		DETAIL_IGNITION_ADD_PLUGIN_ALIAS(PluginClass, __VA_ARGS__)

Add an alias for one of your plugins.

This macro can be put in any namespace and may be called any number of times. It can be called multiple times on the same plugin class in order to register multiple aliases, e.g.:

IGNITION_ADD_PLUGIN_ALIAS(PluginClass, "PluginClass")
IGNITION_ADD_PLUGIN_ALIAS(PluginClass, "SomeOtherName", "Yet another name")
IGNOTION_ADD_PLUGIN_ALIAS(AnotherPluginClass, "Foo", "Bar", "Baz")

You can give the same alias to multiple plugins, but then that alias can no longer be used to instantiate any plugin.

If you give a plugin an alias string that matches the demangled symbol name of another plugin, then the Loader will always prefer to instantiate the plugin whose symbol name matches that string.