Plugin System

[中文]

Public header: #include "brookesia/lib_utils/plugin.hpp"

Overview

plugin provides a generic plugin registry and instance management: register, discover, and create plugins by name.

Features

• Template registration and lookup by name

• Lazy instantiation and singleton registration

• Enumerate, release, and cleanup

• Macros for registration symbols and link visibility

API Reference

Header File

• utils/brookesia_lib_utils/include/brookesia/lib_utils/plugin.hpp

Classes

template<typename T>
class PluginRegistry

Thread-safe registry for named plugin factories and cached instances.

Template Parameters

T – Base class type exposed by the registry.

Public Static Functions

static inline std::shared_ptr<T> get_instance(const std::string &name)

Get a plugin instance by name.

Returns the cached instance when available, otherwise creates it through the registered factory.

Note

The returned shared_ptr shares ownership with the Registry. The instance remains valid as long as either the Registry or any returned shared_ptr holds a reference, ensuring thread-safe access even if release_instance() or remove_plugin() is called.

Parameters

name – [in] Registered plugin name.

Returns

Shared pointer to the plugin instance, or nullptr when the plugin is not registered or the factory is empty.

static inline std::map<std::string, std::shared_ptr<T>> get_all_instances()

Get instances for all registered plugins.

Missing cached instances are created on demand before they are returned.

Note

Each returned shared_ptr shares ownership with the Registry. The instances remain valid as long as either the Registry or any returned shared_ptr holds a reference, ensuring thread-safe access.

Returns

Map from plugin name to shared plugin instance.

static inline size_t get_plugin_count()

Get the number of registered plugin names.

Returns

Total number of registered plugins.

static inline bool has_plugin(const std::string &name)

Check whether a plugin name is registered.

Parameters

name – [in] Plugin name to test.

Returns

true when the plugin exists in the registry, or false otherwise.

static inline void release_instance(const std::string &name)

Release the cached instance for a registered plugin.

This keeps the factory registration intact and only drops the registry-held shared pointer.

Parameters

name – [in] Plugin name.

static inline void release_all_instances()

Release all cached plugin instances without removing registrations.

static inline void remove_plugin(const std::string &name)

Remove a plugin registration and its cached instance.

Parameters

name – [in] Plugin name to remove.

static inline void remove_all_plugins()

Remove all registered plugins and cached instances.

template<typename PluginType>
static inline void register_plugin(const std::string &name, FactoryFunc factory)

Register a plugin factory under a unique name.

Template Parameters

PluginType – Concrete plugin type being registered.

Parameters

• name – [in] Plugin name. Existing registrations with the same name are kept unchanged.

• factory – [in] Factory used to lazily create instances.

Macros

_BROOKESIA_PLUGIN_CONCAT(a, b)

BROOKESIA_PLUGIN_CONCAT(a, b)

BROOKESIA_PLUGIN_CREATE_SYMBOL(symbol_name, static_var_name)

Create a linker-visible symbol that keeps a registrar object alive.

Note

The function is defined outside any namespace to ensure proper linking. The static variable reference ensures the registrar instance is not optimized away.

BROOKESIA_PLUGIN_REGISTER_WITH_CONSTRUCTOR(BaseType, PluginType, name, creator, symbol_name)

Register a plugin using a custom creator expression.

Note

Automatically creates a fixed symbol name based on PluginType for linker -u option

Parameters

• BaseType – Registry base type.

• PluginType – Concrete plugin type to register.

• name – Plugin name used by PluginRegistry.

• creator – Creator expression returning shared_ptr or unique_ptr compatible with the registry.

• symbol_name – Linker symbol exported for -u.

BROOKESIA_PLUGIN_REGISTER(BaseType, PluginType, name, ...)

Register a plugin constructed with std::make_shared.

// Example usage:
BROOKESIA_PLUGIN_REGISTER(BaseService, MyPlugin, "my_plugin");
BROOKESIA_PLUGIN_REGISTER(BaseService, MyPlugin, "my_plugin", arg1, arg2);

Parameters

• BaseType – Registry base type.

• PluginType – Concrete plugin type to register.

• name – Plugin name used by PluginRegistry.

• ... – Optional constructor arguments forwarded to PluginType.

BROOKESIA_PLUGIN_REGISTER_SINGLETON(BaseType, PluginType, name, instance_expr)

Register a singleton object in the plugin registry.

This macro allows registering a singleton instance to the plugin registry. It uses a custom no-op deleter to prevent the shared_ptr from destroying the singleton. Automatically generates a fixed symbol name based on PluginType for linker -u option.

// Example usage:
BROOKESIA_PLUGIN_REGISTER_SINGLETON(
    BaseService,
    MySingleton,
    "my_singleton",
    MySingleton::get_instance()
);
// Creates symbol: _MySingleton_symbol_<line_number>
// Use: target_link_libraries(${COMPONENT_LIB} INTERFACE "-u _MySingleton_symbol_<line_number>")

Parameters

• BaseType – Registry base type.

• PluginType – Singleton type to register.

• name – Plugin name used by PluginRegistry.

• instance_expr – Expression that yields a singleton instance reference, for example Type::get_instance().

BROOKESIA_PLUGIN_REGISTER_WITH_SYMBOL(BaseType, PluginType, name, symbol_name, ...)

Register a plugin constructed with std::make_shared and a custom linker symbol.

// Example usage:
BROOKESIA_PLUGIN_REGISTER_WITH_SYMBOL(BaseService, MyPlugin, "my_plugin", "custom_symbol_name");
BROOKESIA_PLUGIN_REGISTER_WITH_SYMBOL(BaseService, MyPlugin, "my_plugin", "custom_symbol_name", arg1, arg2);
// Use: target_link_libraries(${COMPONENT_LIB} INTERFACE "-u custom_symbol_name")

Parameters

• BaseType – Registry base type.

• PluginType – Concrete plugin type to register.

• name – Plugin name used by PluginRegistry.

• symbol_name – Custom linker symbol exported for -u.

• ... – Optional constructor arguments forwarded to PluginType.

BROOKESIA_PLUGIN_REGISTER_SINGLETON_WITH_SYMBOL(BaseType, PluginType, name, instance_expr, symbol_name)

Register a singleton object with a custom linker symbol.

This macro allows registering a singleton instance to the plugin registry. It uses a custom no-op deleter to prevent the shared_ptr from destroying the singleton. Uses the provided custom symbol name for linker -u option.

// Example usage:
BROOKESIA_PLUGIN_REGISTER_SINGLETON_WITH_SYMBOL(
    BaseService,
    MySingleton,
    "my_singleton",
    MySingleton::get_instance(),
    "custom_symbol_name"
);
// Use: target_link_libraries(${COMPONENT_LIB} INTERFACE "-u custom_symbol_name")

Parameters

• BaseType – Registry base type.

• PluginType – Singleton type to register.

• name – Plugin name used by PluginRegistry.

• instance_expr – Expression that yields a singleton instance reference.

• symbol_name – Custom linker symbol exported for -u.