Maliput Plugin Architecture
October 7, 2021

Maliput Plugin Architecture


This document aims to explain the plugin architecture that Maliput provides.

The main objective of the plugin architecture is to hand out an architecture that allows users to customize certain systems implementations in an easy and effective way.


Maliput defines maliput::plugin::MaliputPlugin class which is in charge of providing an interface to interact with a given dynamic library.

To be considered a maliput plugin, the following two functions must be defined:

extern "C" char* GetMaliputPluginId();
extern "C" MaliputPluginType GetMaliputPluginType();

MaliputPlugin types

The MaliputPlugin type that are currently supported are listed at the enum named maliput::plugin::MaliputPluginType.


maliput::plugin::MaliputPluginManager manages the lifecycle of MaliputPlugins. It will try to load all the available plugins in the path(MALIPUT_PLUGIN_PATH) and make them available via maliput::plugin::MaliputPluginManager::GetPlugin().

The MaliputPlugin's discovery process consists on retrieving all the MaliputPlugins that are located as the MALIPUT_PLUGIN_PATH environment variable points to.

To extend the discovery process to other locations simply extend the MALIPUT_PLUGIN_PATH environment variable.

export MALIPUT_PLUGIN_PATH=/new/path/for/plugin/discovery:$MALIPUT_PLUGIN_PATH

Maliput available interfaces

RoadNetworkLoader plugin

Maliput clients may opt to use the plugin architecture to load at runtime specific backends. That simplifies the linkage process and reduces the number of compile time dependencies. See maliput::plugin::RoadNetworkLoader class which offers a unified interface for maliput users to load a maliput::api::RoadNetwork.

Maliput backend implementations must use REGISTER_ROAD_NETWORK_LOADER_PLUGIN() macro to instantiate the necessary entry points of the plugin. Those symbols are required by the plugin architecture discovery phase. Refer to the following code snippet for a usage example:

// Implementation of a maliput::plugin::RoadNetworkLoader using a custom maliput backend called `my_custom_backend`.
class RoadNetworkLoader : public maliput::plugin::RoadNetworkLoader {
std::unique_ptr<const maliput::api::RoadNetwork> operator()(
const std::map<std::string, std::string>& properties) const override {
return my_custom_backend::loader::RoadNetworkLoader(properties)();
REGISTER_ROAD_NETWORK_LOADER_PLUGIN("my_custom_backend", RoadNetworkLoader);

As it can be seen:

Note: MALIPUT_PLUGIN_PATH must contain the path to the installed plugin shared library in order to make maliput::plugin::MaliputPluginManager aware of its existence and load it.

Using a custom RoadNetworkLoader plugin

After the creation of the maliput::plugin::MaliputPlugin that implements a maliput::plugin::RoadNetworkLoader and the correct set up of the MALIPUT_PLUGIN_PATH discovery path, the use of this plugin is quite straightforward:

const std::string plugin_name{"my_custom_backend"};
const std::map<std::string, std::string> loader_parameters{/* Parameters for the backend's builder if necessary */}
// Create maliput::plugin::MaliputPluginManager instance.
// Get plugin.
const maliput::plugin::MaliputPlugin* maliput_plugin =
// Verifies that the plugin was obtained.
if (!maliput_plugin) {
throw std::runtime_error("Plugin hasn't been found");
// Verifies plugin type.
throw std::runtime_error("Plugin type doesn't match");
// Obtains a pointer to an instance of the loader class.
auto rn_loader_ptr = maliput_plugin->ExecuteSymbol<maliput::plugin::RoadNetworkLoaderPtr>(
// Use smart pointers to gracefully manage heap allocation.
std::unique_ptr<maliput::plugin::RoadNetworkLoader> road_network_loader{
// Generates the maliput::api::RoadNetwork.
std::unique_ptr<const maliput::api::RoadNetwork> road_network = (*road_network_loader)(loader_parameters);

For convenience, maliput offers a helper method for loading a maliput::api::RoadNetwork from a plugin, which is a shortcut to the above code snippet.

const std::string road_network_loader_plugin_id{"my_custom_backend"};
const std::map<std::string, std::string> loader_parameters{/* Parameters for the backend's builder if necessary */}
// Create maliput::api::RoadNetwork instance.
std::unique_ptr<maliput::api::RoadNetwork> road_network =
maliput::plugin::CreateRoadNetwork(road_network_loader_plugin_id, loader_parameters);

Related References

virtual std::unique_ptr< maliput::api::RoadNetwork > operator()(const std::map< std::string, std::string > &properties) const =0
Returns a maliput::api::RoadNetwork.
#define REGISTER_ROAD_NETWORK_LOADER_PLUGIN(PluginName, RoadNetworkLoaderClass)
Definition: road_network_loader.h:42
Types of maliput plugin.
Definition: maliput_plugin_type.h:39
std::unique_ptr< maliput::api::RoadNetwork > CreateRoadNetwork(const std::string &road_network_loader_id, const std::map< std::string, std::string > &properties)
Creates a maliput::api::RoadNetwork via RoadNetworkLoader plugin.
MaliputPluginType GetType() const
Definition: maliput_plugin.h:82
void * RoadNetworkLoaderPtr
Additional name for the MakeRoadNetworkLoader method's return type.
Definition: road_network_loader.h:53
ReturnType ExecuteSymbol(const std::string &sym_name, Args &&... args) const
Finds and executes a symbol loaded by the plugin library.
Definition: maliput_plugin.h:94
@ kRoadNetworkLoader
Definition: maliput_plugin_type.h:40
Manages the lifecycle of MaliputPlugins.
Definition: maliput_plugin_manager.h:46
static std::string GetEntryPoint()
Definition: road_network_loader.h:59
MaliputPlugin loads a dynamic library.
Definition: maliput_plugin.h:64
Interface class for creating a RoadNetwork loader functor.
Definition: road_network_loader.h:56
maliput::api::TypeSpecificIdentifier< class MaliputPlugin >
const MaliputPlugin * GetPlugin(const MaliputPlugin::Id &id) const
Get a pointer to an already loaded plugin.