helios::app::DynamicModule Class Reference

#include <dynamic_module.hpp>

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

Public Member Functions
	DynamicModule ()=default
	DynamicModule (const std::filesystem::path &path, DynamicModuleConfig config={})
	Constructs and loads a module from the specified path.
	DynamicModule (const DynamicModule &)=delete
	DynamicModule (DynamicModule &&other) noexcept
	~DynamicModule () noexcept=default
	Destructor that destroys the module if loaded.
DynamicModule &	operator= (const DynamicModule &)=delete
DynamicModule &	operator= (DynamicModule &&other) noexcept
auto	Load (const std::filesystem::path &path, DynamicModuleConfig config={}) -> std::expected< void, DynamicModuleError >
	Loads a module from the specified path.
auto	Unload () -> std::expected< void, DynamicModuleError >
	Unloads the current module.
auto	Reload (App &app) -> std::expected< void, DynamicModuleError >
	Reloads the module from the same path.
auto	ReloadIfChanged (App &app) -> std::expected< void, DynamicModuleError >
	Reloads the module 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 module is currently loaded.
Module &	GetModule () noexcept
	Gets reference to the loaded module.
const Module &	GetModule () const noexcept
	Gets const reference to the loaded module.
Module *	GetModulePtr () noexcept
	Gets pointer to the loaded module.
const Module *	GetModulePtr () const noexcept
	Gets const pointer to the loaded module.
std::unique_ptr< Module >	ReleaseModule () noexcept
	Releases ownership of the module.
ModuleTypeId	GetModuleId () const noexcept
	Gets the module type ID.
std::string_view	GetModuleName () const noexcept
	Gets the module 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 DynamicModuleConfig &	Config () const noexcept
	Gets the configuration used for this module.

Detailed Description

Definition at line 154 of file dynamic_module.hpp.

Member Typedef Documentation

FileTime

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

Definition at line 156 of file dynamic_module.hpp.

Constructor & Destructor Documentation

DynamicModule() [1/4]

helios::app::DynamicModule::DynamicModule ( )

default

DynamicModule() [2/4]

helios::app::DynamicModule::DynamicModule ( const std::filesystem::path &  path, DynamicModuleConfig  config = {}  )

inlineexplicit

Constructs and loads a module from the specified path.

Parameters

path	Path to the dynamic library
config	Configuration options

Definition at line 314 of file dynamic_module.hpp.

                                                                                             {
  auto result = Load(path, config);
  if (!result) {
    HELIOS_ERROR("Failed to load dynamic module '{}': {}", path.string(), DynamicModuleErrorToString(result.error()));
  }
}

DynamicModule() [3/4]

helios::app::DynamicModule::DynamicModule ( const DynamicModule &  )

delete

DynamicModule() [4/4]

helios::app::DynamicModule::DynamicModule ( DynamicModule &&  other )

inlinenoexcept

Definition at line 321 of file dynamic_module.hpp.

    : library_(std::move(other.library_)),
      module_(std::move(other.module_)),
      module_id_(other.module_id_),
      module_name_(std::move(other.module_name_)),
      config_(other.config_),
      last_write_time_(other.last_write_time_) {
  other.module_id_ = 0;
}

~DynamicModule()

helios::app::DynamicModule::~DynamicModule ( )

defaultnoexcept

Destructor that destroys the module if loaded.

Member Function Documentation

Config()

const DynamicModuleConfig & helios::app::DynamicModule::Config ( ) const

inlinenoexcept

Gets the configuration used for this module.

Returns

Configuration struct

Definition at line 295 of file dynamic_module.hpp.

{ return config_; }

GetModule() [1/2]

const Module & helios::app::DynamicModule::GetModule ( ) const

inlinenoexcept

Gets const reference to the loaded module.

Warning

Triggers assertion if module is not loaded.

Returns

Const reference to the module

Definition at line 471 of file dynamic_module.hpp.

                                                             {
  HELIOS_ASSERT(Loaded(), "Failed to get module: Module is not loaded!");
  return *module_;
}

GetModule() [2/2]

Module & helios::app::DynamicModule::GetModule ( )

inlinenoexcept

Gets reference to the loaded module.

Warning

Triggers assertion if module is not loaded.

Returns

Reference to the module

Definition at line 466 of file dynamic_module.hpp.

                                                 {
  HELIOS_ASSERT(Loaded(), "Failed to get module: Module is not loaded!");
  return *module_;
}

GetModuleId()

ModuleTypeId helios::app::DynamicModule::GetModuleId ( ) const

inlinenoexcept

Gets the module type ID.

Returns

Module type ID, or 0 if not loaded

Definition at line 265 of file dynamic_module.hpp.

{ return module_id_; }

GetModuleName()

std::string_view helios::app::DynamicModule::GetModuleName ( ) const

inlinenoexcept

Gets the module name.

Returns

Module name, or empty string if not loaded

Definition at line 271 of file dynamic_module.hpp.

{ return module_name_; }

GetModulePtr() [1/2]

const Module * helios::app::DynamicModule::GetModulePtr ( ) const

inlinenoexcept

Gets const pointer to the loaded module.

Returns

Const pointer to module, or nullptr if not loaded

Definition at line 251 of file dynamic_module.hpp.

{ return module_.get(); }

GetModulePtr() [2/2]

Module * helios::app::DynamicModule::GetModulePtr ( )

inlinenoexcept

Gets pointer to the loaded module.

Returns

Pointer to module, or nullptr if not loaded

Definition at line 245 of file dynamic_module.hpp.

{ return module_.get(); }

HasFileChanged()

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

inlinenoexcept

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

Returns

True if the file modification time has changed

Definition at line 452 of file dynamic_module.hpp.

                                                         {
  if (!library_.Loaded()) {
    return false;
  }
 
  std::error_code ec;
  auto current_time = std::filesystem::last_write_time(library_.Path(), ec);
  if (ec) {
    return false;
  }
 
  return current_time != last_write_time_;
}

Library() [1/2]

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

inlinenoexcept

Gets const reference to the underlying dynamic library.

Returns

Const reference to helios::utils::DynamicLibrary

Definition at line 289 of file dynamic_module.hpp.

{ return library_; }

Library() [2/2]

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

inlinenoexcept

Gets reference to the underlying dynamic library.

Returns

Reference to helios::utils::DynamicLibrary

Definition at line 283 of file dynamic_module.hpp.

{ return library_; }

Load()

auto helios::app::DynamicModule::Load ( const std::filesystem::path &  path, DynamicModuleConfig  config = {}  ) -> std::expected<void, DynamicModuleError>

inline

Loads a module from the specified path.

Parameters

path	Path to the dynamic library
config	Configuration options

Returns

Expected with void on success, or error on failure

Definition at line 346 of file dynamic_module.hpp.

                                             {
  config_ = config;
 
  // Load the library
  const auto load_result = library_.Load(path);
  if (!load_result) {
    return std::unexpected(DynamicModuleError::LibraryLoadFailed);
  }
 
  // Load module symbols and create instance
  auto module_result = LoadModuleInstance();
  if (!module_result) {
    [[maybe_unused]] auto _ = library_.Unload();
    return module_result;
  }
 
  // Cache the file modification time
  UpdateFileTime();
 
  HELIOS_INFO("Loaded dynamic module '{}' from: {}", module_name_, path.string());
  return {};
}

Loaded()

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

inlinenoexcept

Checks if a module is currently loaded.

Returns

True if a module is loaded

Definition at line 225 of file dynamic_module.hpp.

{ return module_ != nullptr && library_.Loaded(); }

operator=() [1/2]

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

delete

operator=() [2/2]

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

inlinenoexcept

Definition at line 331 of file dynamic_module.hpp.

                                                                             {
  if (this != &other) {
    module_.reset();
    library_ = std::move(other.library_);
    module_ = std::move(other.module_);
    module_id_ = other.module_id_;
    module_name_ = std::move(other.module_name_);
    config_ = other.config_;
    last_write_time_ = other.last_write_time_;
 
    other.module_id_ = 0;
  }
  return *this;
}

Path()

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

inlinenoexcept

Gets the path of the loaded library.

Returns

Path to the library, or empty if not loaded

Definition at line 277 of file dynamic_module.hpp.

{ return library_.Path(); }

ReleaseModule()

std::unique_ptr< Module > helios::app::DynamicModule::ReleaseModule ( )

inlinenoexcept

Releases ownership of the module.

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

Returns

Unique pointer to the module

Definition at line 259 of file dynamic_module.hpp.

{ return std::move(module_); }

Reload()

auto helios::app::DynamicModule::Reload ( App &  app ) -> std::expected<void, DynamicModuleError>

inline

Reloads the module from the same path.

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

Parameters

app	Reference to the app for Build/Destroy calls

Returns

Expected with void on success, or error on failure

Definition at line 388 of file dynamic_module.hpp.

                                                                                   {
  if (!Loaded()) {
    return std::unexpected(DynamicModuleError::NotLoaded);
  }
 
  // Call Destroy on the old module
  HELIOS_INFO("Reloading dynamic module '{}': {}", module_name_, library_.Path().string());
  module_->Destroy(app);
 
  // Save the path and config before unloading
  auto saved_path = library_.Path();
  auto saved_config = config_;
 
  // Release module and unload library
  module_.reset();
  module_id_ = 0;
  module_name_.clear();
 
  auto unload_result = library_.Unload();
  if (!unload_result) {
    return std::unexpected(DynamicModuleError::ReloadFailed);
  }
 
  // Reload the library
  auto load_result = library_.Load(saved_path);
  if (!load_result) {
    return std::unexpected(DynamicModuleError::ReloadFailed);
  }
 
  // Load module symbols and create new instance
  config_ = saved_config;
  auto module_result = LoadModuleInstance();
  if (!module_result) {
    [[maybe_unused]] auto _ = library_.Unload();
    return std::unexpected(DynamicModuleError::ReloadFailed);
  }
 
  // Call Build on the new module
  module_->Build(app);
 
  // Update file time
  UpdateFileTime();
 
  HELIOS_INFO("Successfully reloaded dynamic module '{}': {}", module_name_, saved_path.string());
  return {};
}

ReloadIfChanged()

auto helios::app::DynamicModule::ReloadIfChanged ( App &  app ) -> std::expected<void, DynamicModuleError>

inline

Reloads the module only if the file has changed.

Parameters

app	Reference to the app for Build/Destroy calls

Returns

Expected with void on success, FileNotChanged if not modified, or error on failure

Definition at line 435 of file dynamic_module.hpp.

                                                                                            {
  if (!HasFileChanged()) {
    return std::unexpected(DynamicModuleError::FileNotChanged);
  }
 
  return Reload(app);
}

Unload()

auto helios::app::DynamicModule::Unload ( ) -> std::expected<void, DynamicModuleError>

inline

Unloads the current module.

Releases the module and unloads the library.

Returns

Expected with void on success, or error on failure

Definition at line 370 of file dynamic_module.hpp.

                                                                           {
  if (!Loaded()) {
    return std::unexpected(DynamicModuleError::NotLoaded);
  }
 
  // Release module before unloading library
  module_.reset();
  module_id_ = 0;
  module_name_.clear();
 
  auto unload_result = library_.Unload();
  if (!unload_result) {
    return std::unexpected(DynamicModuleError::LibraryLoadFailed);
  }
 
  return {};
}

UpdateFileTime()

void helios::app::DynamicModule::UpdateFileTime ( )

inlinenoexcept

Updates the cached file modification time.

Call this after detecting a change to reset the tracking.

Definition at line 443 of file dynamic_module.hpp.

                                                   {
  if (!library_.Loaded()) {
    return;
  }
 
  std::error_code ec;
  last_write_time_ = std::filesystem::last_write_time(library_.Path(), ec);
}