helios::utils::DynamicLibrary Class Reference

#include <dynamic_library.hpp>

Public Types
using	HandleType = void *
	Native handle type (void* on all platforms for ABI stability)

Public Member Functions
	DynamicLibrary ()=default
	DynamicLibrary (const std::filesystem::path &path)
	Constructs and loads a library from the specified path.
	DynamicLibrary (const DynamicLibrary &)=delete
	DynamicLibrary (DynamicLibrary &&other) noexcept
	~DynamicLibrary () noexcept
	Destructor that unloads the library if loaded.
DynamicLibrary &	operator= (const DynamicLibrary &)=delete
DynamicLibrary &	operator= (DynamicLibrary &&other) noexcept
auto	Load (const std::filesystem::path &path) -> std::expected< void, DynamicLibraryError >
	Loads a dynamic library from the specified path.
auto	Unload () -> std::expected< void, DynamicLibraryError >
	Unloads the currently loaded library.
auto	Reload () -> std::expected< void, DynamicLibraryError >
	Reloads the library from the same path.
auto	GetSymbolAddress (std::string_view name) const -> std::expected< void *, DynamicLibraryError >
	Gets a raw symbol address from the library.
template<typename T > requires std::is_pointer_v<T>
auto	GetSymbol (std::string_view name) const -> std::expected< T, DynamicLibraryError >
	Gets a typed function pointer from the library.
bool	Loaded () const noexcept
	Checks if a library is currently loaded.
const std::filesystem::path &	Path () const noexcept
	Gets the path of the loaded library.
HandleType	Handle () const noexcept
	Gets the native handle of the loaded library.

Static Public Member Functions
static auto	FromPath (const std::filesystem::path &path) -> std::expected< DynamicLibrary, DynamicLibraryError >
static std::string	GetLastErrorMessage () noexcept
	Gets the last platform-specific error message.
static constexpr std::string_view	GetPlatformExtension () noexcept
	Gets the platform-specific file extension for dynamic libraries.
static constexpr std::string_view	GetPlatformPrefix () noexcept
	Gets the platform-specific library prefix.

Static Public Attributes
static constexpr HandleType	kInvalidHandle = nullptr

Detailed Description

Definition at line 74 of file dynamic_library.hpp.

Member Typedef Documentation

HandleType

using helios::utils::DynamicLibrary::HandleType = void*

Native handle type (void* on all platforms for ABI stability)

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/utils/dynamic_library.hpp.

Definition at line 77 of file dynamic_library.hpp.

Constructor & Destructor Documentation

DynamicLibrary() [1/4]

helios::utils::DynamicLibrary::DynamicLibrary ( )

default

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/utils/dynamic_library.hpp.

DynamicLibrary() [2/4]

helios::utils::DynamicLibrary::DynamicLibrary ( const std::filesystem::path &  path )

inlineexplicit

Constructs and loads a library from the specified path.

Parameters

path	Path to the dynamic library

Definition at line 193 of file dynamic_library.hpp.

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

DynamicLibrary() [3/4]

helios::utils::DynamicLibrary::DynamicLibrary ( const DynamicLibrary &  )

delete

DynamicLibrary() [4/4]

helios::utils::DynamicLibrary::DynamicLibrary ( DynamicLibrary &&  other )

inlinenoexcept

Definition at line 201 of file dynamic_library.hpp.

    : handle_(other.handle_), path_(std::move(other.path_)) {
  other.handle_ = kInvalidHandle;
}

~DynamicLibrary()

helios::utils::DynamicLibrary::~DynamicLibrary ( )

inlinenoexcept

Destructor that unloads the library if loaded.

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/utils/dynamic_library.hpp.

Definition at line 206 of file dynamic_library.hpp.

                                                {
  if (Loaded()) {
    auto result = Unload();
    if (!result) {
      HELIOS_WARN("Failed to unload dynamic library '{}': {}!", path_.string(),
                  DynamicLibraryErrorToString(result.error()));
    }
  }
}

Member Function Documentation

FromPath()

static auto helios::utils::DynamicLibrary::FromPath ( const std::filesystem::path &  path ) -> std::expected< DynamicLibrary, DynamicLibraryError >

static

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/utils/dynamic_library.hpp.

GetLastErrorMessage()

std::string helios::utils::DynamicLibrary::GetLastErrorMessage ( )

staticnoexcept

Gets the last platform-specific error message.

Returns

Error message string

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/utils/dynamic_library.hpp.

Definition at line 100 of file dynamic_library.cpp.

                                                       {
#ifdef HELIOS_PLATFORM_WINDOWS
  DWORD error_code = GetLastError();
  if (error_code == 0) {
    return "No error";
  }
 
  LPSTR message_buffer = nullptr;
  const size_t size = FormatMessageA(
      FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS, nullptr, error_code,
      MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), reinterpret_cast<LPSTR>(&message_buffer), 0, nullptr);
 
  std::string message(message_buffer, size);
  LocalFree(message_buffer);
 
  // Remove trailing newline
  while (!message.empty() && (message.back() == '\n' || message.back() == '\r')) {
    message.pop_back();
  }
 
  return message;
#else
  const char* error = dlerror();
  return error != nullptr ? std::string(error) : "No error";
#endif
}

GetPlatformExtension()

static constexpr std::string_view helios::utils::DynamicLibrary::GetPlatformExtension ( )

inlinestaticconstexprnoexcept

Gets the platform-specific file extension for dynamic libraries.

Returns

".dll" on Windows, ".so" on Linux, ".dylib" on macOS

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/utils/dynamic_library.hpp.

Definition at line 166 of file dynamic_library.hpp.

                                                                                {
#ifdef HELIOS_PLATFORM_WINDOWS
    return ".dll";
#elifdef HELIOS_PLATFORM_MACOS
    return ".dylib";
#else
    return ".so";
#endif
  }

GetPlatformPrefix()

static constexpr std::string_view helios::utils::DynamicLibrary::GetPlatformPrefix ( )

inlinestaticconstexprnoexcept

Gets the platform-specific library prefix.

Returns

Empty on Windows, "lib" on Unix-like systems

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/utils/dynamic_library.hpp.

Definition at line 180 of file dynamic_library.hpp.

                                                                             {
#ifdef HELIOS_PLATFORM_WINDOWS
    return "";
#else
    return "lib";
#endif
  }

GetSymbol()

template<typename T >
requires std::is_pointer_v<T>

auto helios::utils::DynamicLibrary::GetSymbol ( std::string_view  name ) const -> std::expected<T, DynamicLibraryError>

inline

Gets a typed function pointer from the library.

Template Parameters

T	Function pointer type

Parameters

name	Name of the symbol to retrieve

Returns

Expected with function pointer on success, or error on failure

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/utils/dynamic_library.hpp.

Definition at line 253 of file dynamic_library.hpp.

                                                                                                      {
  auto result = GetSymbolAddress(name);
  if (!result) {
    return std::unexpected(result.error());
  }
 
  // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
  return reinterpret_cast<T>(*result);
}

GetSymbolAddress()

auto helios::utils::DynamicLibrary::GetSymbolAddress

(

std::string_view

name

)

const -> std::expected<void*, DynamicLibraryError>

Gets a raw symbol address from the library.

Parameters

name	Name of the symbol to retrieve

Returns

Expected with void pointer on success, or error on failure

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/utils/dynamic_library.hpp.

Definition at line 76 of file dynamic_library.cpp.

                                                                                                          {
  if (!Loaded()) {
    return std::unexpected(DynamicLibraryError::NotLoaded);
  }
 
  // Need null-terminated string for platform APIs
  std::string name_str(name);
 
  void* symbol = nullptr;
#ifdef HELIOS_PLATFORM_WINDOWS
  // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
  symbol = reinterpret_cast<void*>(GetProcAddress(reinterpret_cast<HMODULE>(handle_), name_str.c_str()));
#else
  symbol = dlsym(handle_, name_str.c_str());
#endif
 
  if (symbol == nullptr) {
    HELIOS_WARN("Symbol '{}' not found in library '{}': {}!", name, path_.string(), GetLastErrorMessage());
    return std::unexpected(DynamicLibraryError::SymbolNotFound);
  }
 
  return symbol;
}

Handle()

HandleType helios::utils::DynamicLibrary::Handle ( ) const

inlinenoexcept

Gets the native handle of the loaded library.

Returns

Native handle, or kInvalidHandle if not loaded

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/utils/dynamic_library.hpp.

Definition at line 154 of file dynamic_library.hpp.

{ return handle_; }

Load()

auto helios::utils::DynamicLibrary::Load

(

const std::filesystem::path &

path

)

-> std::expected<void, DynamicLibraryError>

Loads a dynamic library from the specified path.

Parameters

path	Path to the dynamic library

Returns

Expected with void on success, or error on failure

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/utils/dynamic_library.hpp.

Definition at line 26 of file dynamic_library.cpp.

                                                                                                 {
  if (Loaded()) {
    return std::unexpected(DynamicLibraryError::AlreadyLoaded);
  }
 
  if (!std::filesystem::exists(path)) {
    return std::unexpected(DynamicLibraryError::FileNotFound);
  }
 
#ifdef HELIOS_PLATFORM_WINDOWS
  // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
  handle_ = reinterpret_cast<HandleType>(LoadLibraryW(path.wstring().c_str()));
#else
  handle_ = dlopen(path.c_str(), RTLD_NOW | RTLD_LOCAL);
#endif
 
  if (handle_ == kInvalidHandle) {
    HELIOS_ERROR("Failed to load library '{}': {}!", path.string(), GetLastErrorMessage());
    return std::unexpected(DynamicLibraryError::LoadFailed);
  }
 
  path_ = path;
  HELIOS_DEBUG("Loaded dynamic library: {}", path_.string());
  return {};
}

Loaded()

bool helios::utils::DynamicLibrary::Loaded ( ) const

inlinenoexcept

Checks if a library is currently loaded.

Returns

True if a library is loaded

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/utils/dynamic_library.hpp.

Definition at line 142 of file dynamic_library.hpp.

{ return handle_ != kInvalidHandle; }

operator=() [1/2]

DynamicLibrary & helios::utils::DynamicLibrary::operator= ( const DynamicLibrary &  )

delete

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/utils/dynamic_library.hpp.

operator=() [2/2]

DynamicLibrary & helios::utils::DynamicLibrary::operator= ( DynamicLibrary &&  other )

inlinenoexcept

Definition at line 216 of file dynamic_library.hpp.

                                                                                {
  if (this != &other) {
    if (Loaded()) {
      [[maybe_unused]] auto _ = Unload();
    }
    handle_ = other.handle_;
    path_ = std::move(other.path_);
    other.handle_ = kInvalidHandle;
  }
  return *this;
}

Path()

const std::filesystem::path & helios::utils::DynamicLibrary::Path ( ) const

inlinenoexcept

Gets the path of the loaded library.

Returns

Path to the library, or empty if not loaded

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/utils/dynamic_library.hpp.

Definition at line 148 of file dynamic_library.hpp.

{ return path_; }

Reload()

auto helios::utils::DynamicLibrary::Reload ( ) -> std::expected<void, DynamicLibraryError>

inline

Reloads the library from the same path.

Unloads the current library and loads it again.

Returns

Expected with void on success, or error on failure

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/utils/dynamic_library.hpp.

Definition at line 236 of file dynamic_library.hpp.

                                                                             {
  if (!Loaded()) {
    return std::unexpected(DynamicLibraryError::NotLoaded);
  }
 
  const auto saved_path = path_;
 
  auto unload_result = Unload();
  if (!unload_result) {
    return unload_result;
  }
 
  return Load(saved_path);
}

Unload()

auto helios::utils::DynamicLibrary::Unload

(

)

-> std::expected<void, DynamicLibraryError>

Unloads the currently loaded library.

Returns

Expected with void on success, or error on failure

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/utils/dynamic_library.hpp.

Definition at line 52 of file dynamic_library.cpp.

                                                                      {
  if (!Loaded()) {
    return std::unexpected(DynamicLibraryError::NotLoaded);
  }
 
  bool success = false;
#ifdef HELIOS_PLATFORM_WINDOWS
  // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
  success = FreeLibrary(reinterpret_cast<HMODULE>(handle_)) != 0;
#else
  success = dlclose(handle_) == 0;
#endif
 
  if (!success) {
    HELIOS_ERROR("Failed to unload library '{}': {}!", path_.string(), GetLastErrorMessage());
    return std::unexpected(DynamicLibraryError::PlatformError);
  }
 
  HELIOS_DEBUG("Unloaded dynamic library: {}", path_.string());
  handle_ = kInvalidHandle;
  path_.clear();
  return {};
}

Member Data Documentation

kInvalidHandle

constexpr HandleType helios::utils::DynamicLibrary::kInvalidHandle = nullptr

staticconstexpr

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/utils/dynamic_library.hpp.

Definition at line 78 of file dynamic_library.hpp.