Boost Plugin Loader

Plugin loading library based on Boost DLL

Platform	CI Status
Linux (Focal, Jammy, Noble)
Windows
Lint (Clang-Format)
Lint (CMake-Format)
Lint (Clang-Tidy)

Usage

The plugin loader must know the names of the libraries in which to search for plugins. These library names should not contain a prefix (i.e., lib/) or suffix (i.e., .so). The library names can be set in two ways:

1. Set the search_libraries member directly in code
2. Add a list of library names to an arbitrary environment variable (separated by colon), and set the search_libraries_env member to the name of that environment variable.

The plugin loader must also know the paths in which to look for the specified libraries that contain plugins. These paths can also be set in three ways:

1. Set the search_system_folders member true. This will allow the plugin loader to look for plugins in directories specified by system environment variables (e.g., LD_LIBRARY_PATH). Generally this is the easiest approach.
2. Set the search_paths member directly in code
3. Add a list of library names to an arbitrary environment variable (separated by colon), and set the search_paths_env member to the name of that environment variable

Defining a plugin base class

At a minimum, there are no requirements on the definition of a base class that can be used with this plugin loader. However, there is one optional requirement for enabling the plugin loader to discover the names of all plugins inheriting a specific base class type. Namely, the plugin base class must have a member function static std::string getSection() which defines a section name for the plugin and is accessible to the PluginLoader and has_getSection classes. The section name is a unique 8-byte string that associates implementations to the base class. The plugin loader method getAvailablePlugins can identify all symbols in a library with this section name and thereby return all implementations of a particular base class. It is also generally useful to define a new export macro for the base class that invokes the EXPORT_CLASS_SECTIONED macro with the section name directly. See the test plugin base class definition for an example.

Declaring plugin implementations

Creating an implementation of a plugin is as simple as inheriting from the plugin base class, and calling the EXPORT_CLASS_SECTIONED macro with the correct section (or calling a custom export macro defined for the plugin base class, described above). See the test plugin implementations for an example.

Usage Notes

Multiple instances of the same plugin with varying configuration

Objects loaded with PluginLoader<T>::createInstance are effectively singleton objects. Multiple calls to PluginLoader<T>::createInstance with the same arguments will create a pointer to the same object. If you need to load multiple instances of the same type of plugin but configured differently, consider making your plugin base class a factory that is itself capable of creating and configuring objects. See the ShapeFactory plugin for an example implementation.

Keep plugins in scope during use

Once the plugin object goes out of scope, the library providing it will be unloaded, resulting in undefined behavior and potential segfaults. Thus, the plugin object must be kept in scope for as long as it (and objects created by it) are being used. Here is an example of what not to do:

boost_plugin_loader::PluginLoader<ShapeFactory> plugin_loader;

Shape::Ptr shape;
{
  ShapeFactory::Ptr square_factory = plugin_loader.createInstance("Square");
  shape = square_factory.create(2.0);
  
  // Library providing "Square" plugin is unloaded here when `square_factory` goes out of scope
}

std::cout << "Square area: " << shape->area() << std::endl;  // <-- segfault because the library providing plugin factory (and the object generated by it) was unloaded

Changelog for package boost_plugin_loader

0.3.0 (2025-04-22)

• Add forward declaration header
• Update badges in readme
• Add codecov.yml file
• Update use of target_code_coverage to fix codecov build
• Move addSymbolLibraryToSearchLibrariesEnv to utils
• Add back cpack build to ubuntu.yml
• Fix clang-tidy error in utils.cpp
• Update CI to push codecov report
• Static plugin loading using symbol module resolution (#21)
  • Static plugin loading using symbol moodule resolution
  • Avoid exceptions in isSymbolAvailable
  • Removed deprecated functions; revised loadLibrary function
  • Add method to plugin loader to load valid libraries in the correct order; revised implementation of plugin loader functions to use library loader function
  • Updated function signature of getAllAvailableSymbols
  • Return libraries specified by absolute paths at the front of the return list
  • Update createSharedInstance signature to match other function
  • Fix macro formatting
  • Add unit test which uses full path for library name
  • Add plugin achor unit test
  • Update decorate to support library name as full path

  * Add name to clang format CI ---------Co-authored-by: Michael Ripperger <<michael.ripperger@swri.org>>

• CI Update (#20)
  • Updated clang format job
  • Updated Ubuntu CI job to run on focal, jammy, and noble
  • Update to non-deprecated version of upload artifact action
  • Changed name of variable per clang-tidy
• Removed duplicate entry in clang-format file (#18)
• Contributors: Levi Armstrong, Michael Ripperger

0.2.2 (2024-01-16)

• Catch exceptions when enumerating possible symbols and sections (#17)
• CI Update (#12)
• Change CI to run on Ubuntu 20.04 (#15)
• Contributors: Michael Ripperger

0.2.1 (2022-12-09)

• Improved error messaging (#14)
• Only catch plugin loader exception
• Fix issue not using library names returned from getAllLibraryNames
• Contributors: Levi Armstrong, Michael Ripperger

0.2.0 (2022-06-23)

• Update package CI
• Add cassert include to example
• Update package.xml
• Updates (#3)
  • Updated example and README
  • Replace pragma once with header guard
  • Remove include of implementation in header
  • Simplify test plugin getSection
• Contributors: Levi Armstrong, Michael Ripperger

0.1.1 (2022-06-21)

• Add cpack
• update windows ci
• update ubuntu focal CI build
• add std::enable_if to PluginLoader::getAvailablePlugins()
• update package.xml
• Update unit test to have full coverage
• Add PluginLoaderException class
• Update parseEnvironmentVariableList documentation
• Fixed search in system directories for plugins
• Switch got getSection method
• Rename getAllAvailablePlugins
• Port over \@marip8 example
• Switch SECTION_NAME to section as member variable
• Add code coverage to ubunut CI build
• Rename to align with \@marip8 refactor
• Remove ClassLoader class
• port macros.h
• Initial port from tesseract_common
• Initial commit
• Contributors: Levi Armstrong