helios::app::DynamicPlugin Class Reference

Wrapper for dynamically loaded plugins. More...

#include <dynamic_plugin.hpp>

Public Types
using	FileTime = std::filesystem::file_time_type

Public Member Functions
	DynamicPlugin ()=default
	DynamicPlugin (const std::filesystem::path &path, DynamicPluginConfig config={})
	Constructs and loads a plugin from the specified path.
	DynamicPlugin (const DynamicPlugin &)=delete
	DynamicPlugin (DynamicPlugin &&other) noexcept
	~DynamicPlugin () noexcept=default
DynamicPlugin &	operator= (const DynamicPlugin &)=delete
DynamicPlugin &	operator= (DynamicPlugin &&other) noexcept
auto	Load (const std::filesystem::path &path, DynamicPluginConfig config={}) -> DynamicPluginResult< void >
	Loads a plugin from the specified path.
auto	Unload () -> DynamicPluginResult< void >
	Unloads the current plugin.
auto	Reload (App &app) -> DynamicPluginResult< void >
	Reloads the plugin from the same path.
auto	ReloadIfChanged (App &app) -> DynamicPluginResult< void >
	Reloads the plugin only if the file has changed.
void	UpdateFileTime () noexcept
	Updates the cached file modification time.
bool	HasFileChanged () const noexcept
	Checks if the library file has been modified since last load.
bool	Loaded () const noexcept
	Checks if a plugin is currently loaded.
Plugin &	GetPlugin () noexcept
	Gets reference to the loaded plugin.
const Plugin &	GetPlugin () const noexcept
	Gets const reference to the loaded plugin.
Plugin *	TryGetPlugin () noexcept
	Tries to get the loaded plugin.
const Plugin *	TryGetPlugin () const noexcept
	Tries to get the loaded plugin.
auto	ReleasePlugin () noexcept -> std::unique_ptr< Plugin >
	Releases ownership of the plugin.
PluginTypeId	GetPluginTypeId () const noexcept
	Gets the plugin type ID.
std::string_view	GetPluginName () const noexcept
	Gets the plugin name.
const std::filesystem::path &	Path () const noexcept
	Gets the path of the loaded library.
helios::utils::DynamicLibrary &	Library () noexcept
	Gets reference to the underlying dynamic library.
const helios::utils::DynamicLibrary &	Library () const noexcept
	Gets const reference to the underlying dynamic library.
const DynamicPluginConfig &	Config () const noexcept
	Gets the configuration used for this plugin.

Detailed Description

Wrapper for dynamically loaded plugins.

Loads a plugin from a shared library and manages its lifecycle. Supports hot-reloading: when the library file changes, the plugin can be unloaded and reloaded without restarting the application.

The dynamic library must export:

• A creation function (default: "helios_create_plugin") that returns Plugin*
• A plugin type export function (default: "helios_plugin_type_id") that returns a PluginTypeExport via PluginTypeExportFn

Note

Not thread-safe.

// In my_plugin.cpp (compiled as shared library)
class MyPlugin : public helios::app::Plugin {
public:
  static constexpr std::string_view kName = "MyPlugin";
 
  void Build(App& app) override { ... }
  void Destroy(App& app) override { ... }
};
 
extern "C" {
 
HELIOS_EXPORT helios::app::Plugin* helios_create_plugin() {
  return new MyPlugin();
}
 
HELIOS_EXPORT auto helios_plugin_type_id()
    -> const helios::app::PluginTypeExport* {
  static const auto kExport =
      helios::app::PluginTypeExport::From<MyPlugin>();
  return &kExport;
}
 
}

DynamicPlugin dyn_plugin;
if (auto result = dyn_plugin.Load("my_plugin.so"); result) {
  app.AddDynamicPlugin(std::move(dyn_plugin));
}

Definition at line 184 of file dynamic_plugin.hpp.

Member Typedef Documentation

FileTime

using helios::app::DynamicPlugin::FileTime = std::filesystem::file_time_type

Definition at line 186 of file dynamic_plugin.hpp.

Constructor & Destructor Documentation

DynamicPlugin() [1/4]

helios::app::DynamicPlugin::DynamicPlugin ( )

default

DynamicPlugin() [2/4]

helios::app::DynamicPlugin::DynamicPlugin ( const std::filesystem::path & path, DynamicPluginConfig config = {} )

inlineexplicit

Constructs and loads a plugin from the specified path.

Parameters

path	Path to the dynamic library
config	Configuration options

Definition at line 367 of file dynamic_plugin.hpp.

DynamicPlugin() [3/4]

helios::app::DynamicPlugin::DynamicPlugin ( const DynamicPlugin & )

delete

DynamicPlugin() [4/4]

helios::app::DynamicPlugin::DynamicPlugin ( DynamicPlugin && other )

inlinenoexcept

Definition at line 376 of file dynamic_plugin.hpp.

~DynamicPlugin()

helios::app::DynamicPlugin::~DynamicPlugin ( )

defaultnoexcept

Member Function Documentation

Config()

const DynamicPluginConfig & helios::app::DynamicPlugin::Config ( ) const

inlinenodiscardnoexcept

Gets the configuration used for this plugin.

Returns

Configuration struct

Definition at line 346 of file dynamic_plugin.hpp.

GetPlugin() [1/2]

const Plugin & helios::app::DynamicPlugin::GetPlugin ( ) const

inlinenodiscardnoexcept

Gets const reference to the loaded plugin.

Warning

Triggers assertion if plugin is not loaded.

Returns

Const reference to the plugin

Definition at line 535 of file dynamic_plugin.hpp.

GetPlugin() [2/2]

Plugin & helios::app::DynamicPlugin::GetPlugin ( )

inlinenodiscardnoexcept

Gets reference to the loaded plugin.

Warning

Triggers assertion if plugin is not loaded.

Returns

Reference to the plugin

Definition at line 530 of file dynamic_plugin.hpp.

GetPluginName()

std::string_view helios::app::DynamicPlugin::GetPluginName ( ) const

inlinenodiscardnoexcept

Gets the plugin name.

Returns

Plugin name, or empty string if not loaded

Definition at line 314 of file dynamic_plugin.hpp.

GetPluginTypeId()

PluginTypeId helios::app::DynamicPlugin::GetPluginTypeId ( ) const

inlinenodiscardnoexcept

Gets the plugin type ID.

Returns

Plugin type ID, or 0 if not loaded

Definition at line 306 of file dynamic_plugin.hpp.

HasFileChanged()

bool helios::app::DynamicPlugin::HasFileChanged ( ) const

inlinenodiscardnoexcept

Checks if the library file has been modified since last load.

Returns

True if the file modification time has changed

Definition at line 515 of file dynamic_plugin.hpp.

Library() [1/2]

const helios::utils::DynamicLibrary & helios::app::DynamicPlugin::Library ( ) const

inlinenodiscardnoexcept

Gets const reference to the underlying dynamic library.

Returns

Const reference to DynamicLibrary

Definition at line 338 of file dynamic_plugin.hpp.

Library() [2/2]

helios::utils::DynamicLibrary & helios::app::DynamicPlugin::Library ( )

inlinenodiscardnoexcept

Gets reference to the underlying dynamic library.

Returns

Reference to DynamicLibrary

Definition at line 330 of file dynamic_plugin.hpp.

Load()

auto helios::app::DynamicPlugin::Load ( const std::filesystem::path & path, DynamicPluginConfig config = {} ) -> DynamicPluginResult< void >

inlinenodiscard

Loads a plugin from the specified path.

Parameters

path	Path to the dynamic library
config	Configuration options

Returns

DynamicPluginResult that holds void on success, or DynamicPluginError on failure

Definition at line 398 of file dynamic_plugin.hpp.

Loaded()

bool helios::app::DynamicPlugin::Loaded ( ) const

inlinenodiscardnoexcept

Checks if a plugin is currently loaded.

Returns

True if a plugin is loaded

Definition at line 260 of file dynamic_plugin.hpp.

operator=() [1/2]

DynamicPlugin & helios::app::DynamicPlugin::operator= ( const DynamicPlugin & )

delete

operator=() [2/2]

DynamicPlugin & helios::app::DynamicPlugin::operator= ( DynamicPlugin && other )

inlinenoexcept

Definition at line 383 of file dynamic_plugin.hpp.

Path()

const std::filesystem::path & helios::app::DynamicPlugin::Path ( ) const

inlinenodiscardnoexcept

Gets the path of the loaded library.

Returns

Path to the library, or empty if not loaded

Definition at line 322 of file dynamic_plugin.hpp.

ReleasePlugin()

auto helios::app::DynamicPlugin::ReleasePlugin ( ) -> std::unique_ptr< Plugin >

inlinenodiscardnoexcept

Releases ownership of the plugin.

After this call, the DynamicPlugin no longer owns the plugin. The caller is responsible for the plugin's lifetime.

Returns

Unique pointer to the plugin

Definition at line 298 of file dynamic_plugin.hpp.

Reload()

auto helios::app::DynamicPlugin::Reload ( App & app ) -> DynamicPluginResult< void >

inlinenodiscard

Reloads the plugin from the same path.

Calls Destroy on the old plugin, unloads the library, loads it again, and calls Build on the new plugin.

Warning

Triggers assertion if the plugin is not loaded.

Parameters

app	Reference to the app for Build/Destroy calls

Returns

DynamicPluginResult that holds void on success, or DynamicPluginError on failure

Definition at line 446 of file dynamic_plugin.hpp.

ReloadIfChanged()

auto helios::app::DynamicPlugin::ReloadIfChanged ( App & app ) -> DynamicPluginResult< void >

inlinenodiscard

Reloads the plugin only if the file has changed.

Warning

Triggers assertion if the plugin is not loaded.

Parameters

app	Reference to the app for Build/Destroy calls

Returns

DynamicPluginResult that holds void on success, or DynamicPluginError on failure

Definition at line 495 of file dynamic_plugin.hpp.

TryGetPlugin() [1/2]

const Plugin * helios::app::DynamicPlugin::TryGetPlugin ( ) const

inlinenodiscardnoexcept

Tries to get the loaded plugin.

Returns

Const pointer to plugin, or nullptr if not loaded

Definition at line 288 of file dynamic_plugin.hpp.

TryGetPlugin() [2/2]

Plugin * helios::app::DynamicPlugin::TryGetPlugin ( )

inlinenodiscardnoexcept

Tries to get the loaded plugin.

Returns

Pointer to plugin, or nullptr if not loaded

Definition at line 282 of file dynamic_plugin.hpp.

Unload()

auto helios::app::DynamicPlugin::Unload ( ) -> DynamicPluginResult< void >

inlinenodiscard

Unloads the current plugin.

Releases the plugin and unloads the library.

Warning

Triggers assertion if the plugin is not loaded.

Returns

DynamicPluginResult that holds void on success, or DynamicPluginError on failure

Definition at line 428 of file dynamic_plugin.hpp.

UpdateFileTime()

void helios::app::DynamicPlugin::UpdateFileTime ( )

inlinenoexcept

Updates the cached file modification time.

Call this after detecting a change to reset the tracking.

Definition at line 506 of file dynamic_plugin.hpp.