rll::library class final

#include <rll/library.h>

enum class rll::library::load_hint

Library load hints. This enum describes the possible hints that can be used to change the way libraries are handled when they are loaded.

These values indicate how symbols are resolved when libraries are loaded, and are specified using the set_load_hints method.

static bool rll::library::is_library(std::filesystem::path const& path)

Returns true if path has a valid suffix for a loadable library; otherwise returns false.

Supported suffixes:

rll::library::library(std::filesystem::path path, library::load_hint hints = library::load_hint::none) explicit

Constructs a library object that will load the library specified by path.

rll::library::operator bool() const explicit noexcept

Returns true if the library is loaded; otherwise returns false.

std::string rll::library::filename() const

Returns the file name part of the library's path.

result rll::library::load() noexcept

Loads the library.

Since resolve() always calls this function before resolving any symbols it is not necessary to call it explicitly. In some situations you might want the library loaded in advance, in which case you would use this function.

load_hint rll::library::load_hints() const

Give the load function some hints on how it should behave.

You can give some hints on how the symbols are resolved. Usually, the symbols are not resolved at load time, but resolved lazily, (that is, when resolve is called). If you set the load hints to load_hints::resolve_all_symbols, then all symbols will be resolved at load time if the platform supports it.

Setting load_hints::export_external_symbols will make the external symbols in the library available for resolution in subsequent loaded libraries.

If load_hints::load_archive_member is set, the file name is composed of two components: A path which is a reference to an archive file followed by the second component which is the reference to the archive member. For instance, the fileName libGL.a(shr_64.o) will refer to the library shr_64.o in the archive file named libGL.a. This is only supported on the AIX platform.

The interpretation of the load hints is platform dependent, and if you use it you are probably making some assumptions on which platform you are compiling for, so use them only if you understand the consequences of them.

By default, none of these flags are set, so libraries will be loaded with lazy symbol resolution, and will not export external symbols for resolution in other dynamically-loaded libraries.

bool rll::library::loaded() const

Returns true if the library is loaded; otherwise returns false.

result<library::function_pointer_type> rll::library::operator[](std::string_view const symbol) noexcept

Returns the address of the exported symbol.

The library is loaded if necessary. The function returns error if the symbol could not be resolved or if the library could not be loaded.

Example:

using fn = int (*)(int, int);
auto add = lib.resolve("add")
  .map([](auto* f) { return reinterpret_cast<fn>(f)(1, 2); });
if(add)
  std::cout << add(1, 2) << std::endl; // => 3
else
  std::cout << "error" << std::endl;

The symbol must be exported as a C function from the library. This means that the function must be wrapped in an extern "C" if the library is compiled with a C++ compiler.

std::filesystem::path const& rll::library::path() const

Returns the file name or an absolute path to the library.

When loading the library, library searches in all system-specific library locations (for example, LD_LIBRARY_PATH on Unix), unless the file name has an absolute path. After loading the library successfully, path returns the fully-qualified file name of the library, including the full path to the library if one was given in the constructor or passed to set_path.

For example, after successfully loading the "GL" library on Unix platforms, path() will return "libGL.so". If the file name was originally passed as "/usr/lib/libGL", path() will return "/usr/lib/libGL.so".

result<library::function_pointer_type> rll::library::resolve(std::string_view symbol) noexcept

Returns the address of the exported symbol.

The library is loaded if necessary. The function returns error if the symbol could not be resolved or if the library could not be loaded.

Example:

using fn = int (*)(int, int);
auto add = lib.resolve("add")
  .map([](auto* f) { return reinterpret_cast<fn>(f)(1, 2); });
if(add)
  std::cout << add(1, 2) << std::endl; // => 3
else
  std::cout << "error" << std::endl;

The symbol must be exported as a C function from the library. This means that the function must be wrapped in an extern "C" if the library is compiled with a C++ compiler.

template <typename F>

result<F> rll::library::resolve_cast(std::string_view const symbol) noexcept

Resolves the symbol (see resolve()) and casts the result to function type T.

result rll::library::unload() noexcept

Unloads the library.

This happens automatically on application termination, so you shouldn't normally need to call this function.

If other instances of library are using the same library, the call will fail, and unloading will only happen when every instance has called unload().

rll::library::load_hint operator&(rll::library::load_hint const lhs, rll::library::load_hint const rhs) constexpr noexcept

Flag bitwise and operator for rll::library::load_hint.

rll::library::load_hint& operator&=(rll::library::load_hint& lhs, rll::library::load_hint const rhs) constexpr noexcept

Assign bitwise and operator for rll::library::load_hint.

rll::library::load_hint operator^(rll::library::load_hint const lhs, rll::library::load_hint const rhs) constexpr noexcept

Flag bitwise xor operator for rll::library::load_hint.

rll::library::load_hint& operator^=(rll::library::load_hint& lhs, rll::library::load_hint const rhs) constexpr noexcept

Assign bitwise xor operator for rll::library::load_hint.

rll::library::load_hint operator|(rll::library::load_hint const lhs, rll::library::load_hint const rhs) constexpr noexcept

Flag bitwise or operator for rll::library::load_hint.

rll::library::load_hint& operator|=(rll::library::load_hint& lhs, rll::library::load_hint const rhs) constexpr noexcept

Assign bitwise or operator for rll::library::load_hint.

rll::library::load_hint operator~(rll::library::load_hint const value) constexpr noexcept

Flag bitwise not operator for rll::library::load_hint.