Maliput Plugin Architecture

Overview

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.

MaliputPlugin

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.

MaliputPluginManager

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 {
 public:
  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:

RoadNetworkLoader class inherits from maliput::plugin::RoadNetworkLoader and the operator() calls into the specific maliput backend load procedure.
REGISTER_ROAD_NETWORK_LOADER_PLUGIN() macros is called.

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.
maliput::plugin::MaliputPluginManager manager;
 
// Get plugin.
const maliput::plugin::MaliputPlugin* maliput_plugin =
    manager.GetPlugin(maliput::plugin::MaliputPlugin::Id(plugin_name));
 
// Verifies that the plugin was obtained.
if (!maliput_plugin) {
  throw std::runtime_error("Plugin hasn't been found");
}
 
// Verifies plugin type.
if (maliput_plugin->GetType() != maliput::plugin::MaliputPluginType::kRoadNetworkLoader) {
  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>(
        maliput::plugin::RoadNetworkLoader::GetEntryPoint());
 
// Use smart pointers to gracefully manage heap allocation.
std::unique_ptr<maliput::plugin::RoadNetworkLoader> road_network_loader{
    reinterpret_cast<maliput::plugin::RoadNetworkLoader*>(rn_loader_ptr)};
 
// 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

maliput backends that already have implemented their maliput::plugin::RoadNetworkLoader plugin:
Python interface: There are python bindings for the plugin architecture, see maliput_py package for further information.

Table of Contents