Detailed Description

Provides access to functions of a shared library.

This class will load a shared library file with a OS dependent method (e.g. LoadLibrary on Windows or dlopen on unix). If the shared library was loaded successfully, symbols like functions can be loaded. This basically works with any shared library also once that the application is not linking against.

Loading a shared library increases an OS internal reference counter. If this object goes out of scope, the reference counter is decreased again and the shared library might be unloaded from the process.

Public Types
enum class	Mode { Lazy , Now }
	These modes currently have no effect on Windows. More...

enum class	Flag : int { None = 0 , Global = 1 , Local = 2 , NoLoad = 4 }

Public Member Functions
	DynamicLib (const std::string &path, Mode mode=Mode::Lazy, Flags< Flag > flags=Flag::None)
	Tries to open the shared library at the given path.

	DynamicLib (LIB_HANDLE existingHandle)
	Creates an instance from an existing handle.

	~DynamicLib ()
	Frees the internal handle to the shared library if it hasn't been released yet.

LIB_HANDLE	release ()
	Releases and returns the internal handle to the shared library.

template<typename F>
F	loadSymbol (const std::string &symbolName)
	Loads the symbol with the given name from the library.

void *	loadSymbol (const std::string &symbolName)
	Same as the function above but does not cast to a concrete type.

Member Enumeration Documentation

◆ Mode

enum class Mode

strong

These modes currently have no effect on Windows.

Enumerator
Lazy	Symbols are loaded when needed. See RTLD_LAZY.
Now	Symbols are resolved right away. See RTLD_NOW.

◆ Flag

enum class Flag : int

strong

Enumerator
Global	Symbols are available globally. See RTLD_GLOBAL.
Local	Symbols are only available in the current library. See RTLD_LOCAL.
NoLoad	Don't actual load the library. See RTLD_NOLOAD.

Constructor & Destructor Documentation

◆ DynamicLib() [1/2]

DynamicLib	(	const std::string &	path,
		Mode	mode = Mode::Lazy,
		Flags< Flag >	flags = Flag::None )

explicit

Tries to open the shared library at the given path.

Throws a runtime_error exception if the library cannot be loaded. For details about mode and flags see https://linux.die.net/man/3/dlopen. Both mode and flags have no effect on Windows.

◆ DynamicLib() [2/2]

DynamicLib ( LIB_HANDLE existingHandle )

explicit

Creates an instance from an existing handle.

This assumes that the handle was received from either LoadLibrary (Windows) or dlopen (Linux/macOS). No checks are performed whether the handle is actually valid! Only use when you know what you are doing!

Member Function Documentation

◆ release()

LIB_HANDLE release ( )

Releases and returns the internal handle to the shared library.

This does not free the handle but only returns it and assures that it is no longer freed by the dtor. Shared libraries are always freed automatically when the process exists. This function is usually needed when a function pointer needs to be kept valid even when the corresponding DynamicLib object goes out of scope.

◆ loadSymbol()

template<typename F>

F loadSymbol ( const std::string & symbolName )

inline

Loads the symbol with the given name from the library.

The template argument must be a function signature for the symbol. This signature must match the actual signature of the function as defined by the shared library. Otherwise the behaviour is undefined.

In general, this only works with C-style symbols and not with C++ symbols.

Throws an exception if the function does not exist. Never returns a nullptr.

The returned pointer is only valid as long as the underlying library is loaded. When DynamicLib goes out of scope, the pointer becomes invalid (unless DynamicLib::release was called)!

Example:

// load a function called "my_func" that receives an int and returns a float
try {
    typedef float (*MY_FUNC)(int);
    auto my_func = lib.loadSymbol<MY_FUNC>("my_func");
    my_func(5);
} catch { const std::runtime_error&) { }

The documentation for this class was generated from the following file:

ImFusion/Core/DynamicLib.h