CeresEngine::DynamicLibrary Class Reference

#include <CeresEngine/Foundation/DynamicLibrary.hpp>

Classes
struct	Symbol
	A helper structure that provides an implicit conversion operator from a loaded void* function pointer into a T function pointer. More...
struct	Symbol< R(*)(Args...)>
struct	Symbol< R(Args...)>
struct	Symbol< void >
	A helper structure that provides an implicit conversion operator from a loaded void* function pointer into a T function pointer. More...

Public Types
enum class	Binding { Lazy , Immediate }
enum class	Sharing { Global , Local }
using	NativeHandle = void *
	A type that represents the native dynamic library handle.
using	NameVariant = Variant< StringView, FilePath >
	A variant type that holds either a library name or a path to a DLL/.so/.dylib file.
using	NameSequence = std::initializer_list< NameVariant >
	A sequence of library name variants.

Public Member Functions
	DynamicLibrary ()
	Creates a new unloaded DynamicLibrary.
	DynamicLibrary (const FilePath &path, Binding binding=Binding::Immediate, Sharing sharing=Sharing::Local)
	Creates a new DynamicLibrary by loading the library at the given path.
	DynamicLibrary (StringView name, Binding binding=Binding::Immediate, Sharing sharing=Sharing::Local)
	Creates a new DynamicLibrary by loading the library by it's name.
	DynamicLibrary (const DynamicLibrary &)=delete
	Copy of a DynamicLibrary is not allowed.
DynamicLibrary &	operator= (const DynamicLibrary &)=delete
	Copy assignment of a DynamicLibrary is not allowed.
	DynamicLibrary (DynamicLibrary &&other) noexcept
	Creates a new DynamicLibrary by moving the contents of another.
DynamicLibrary &	operator= (DynamicLibrary &&other) noexcept
	Assigns the DynamicLibrary by moving the contents of another.
	~DynamicLibrary () noexcept
	Unloads the dynamic library (if loaded) and destroy the DynamicLibrary object.
Symbol	resolve (StringView symbolName) const noexcept
	Resolves a symbol by it's name.
template<typename T >
T	resolve (StringView symbolName) const noexcept
	Resolves a symbol by it's name.
bool	loaded () const noexcept
	Checks if the library is loaded.
void	unload () noexcept
	Unloads the library.
	operator bool () const noexcept
	Checks if the library is loaded.
Symbol	operator[] (StringView symbolName) const noexcept
	Resolves a symbol by it's name.

Static Public Member Functions
static bool	available (const FilePath &path)
	Checks if a DynamicLibrary can be loaded with the given path.
static bool	available (StringView name)
	Checks if a DynamicLibrary can be loaded with the given name.
static bool	available (const NameSequence &names)
	Checks if a DynamicLibrary can be loaded with the given name.
template<typename... Ts>
static bool	available (Ts &&... names)
	Checks if a DynamicLibrary can be loaded with the given name.
static DynamicLibrary	tryOpen (const NameSequence &names)
	Tries to open a DynamicLibrary from a sequence of names and paths.
template<typename... Ts>
static DynamicLibrary	tryOpen (Ts &&... names)
	Tries to open a DynamicLibrary from a sequence of names and paths.

Static Public Attributes
static const StringView	prefix
	A prefix added to the library name.
static const StringView	suffix
	A suffix added to the library name.

Private Attributes
NativeHandle	mHandle = nullptr
	The native handle used to load the dynamic library.

Friends
bool	operator== (const DynamicLibrary &a, const DynamicLibrary &b) noexcept
	Checks if two DynamicLibrary instances point to the same loaded library.
bool	operator!= (const DynamicLibrary &a, const DynamicLibrary &b) noexcept
	Checks if two DynamicLibrary instances do not point to the same loaded library.
bool	operator== (const DynamicLibrary &library, std::nullptr_t) noexcept
	Checks if a DynamicLibrary is loaded by comparing it to nullptr.
bool	operator!= (const DynamicLibrary &library, std::nullptr_t) noexcept
	Checks if a DynamicLibrary is loaded by comparing it to nullptr.

Member Typedef Documentation

NameSequence

using CeresEngine::DynamicLibrary::NameSequence = std::initializer_list<NameVariant>

A sequence of library name variants.

NameVariant

using CeresEngine::DynamicLibrary::NameVariant = Variant<StringView, FilePath>

A variant type that holds either a library name or a path to a DLL/.so/.dylib file.

NativeHandle

using CeresEngine::DynamicLibrary::NativeHandle = void*

A type that represents the native dynamic library handle.

Member Enumeration Documentation

Binding

enum class CeresEngine::DynamicLibrary::Binding

strong

Enumerator
Lazy	Perform lazy binding. Only resolve symbols as the code that references them is executed. If the symbol is never referenced, then it is never normalize. (Lazy binding is only performed for function references; references to variables are always immediately bound when the library is loaded.) Remarks This is only implemented for POSIX systems.
Immediate	All undefined symbols in the library are normalize before the constructor returns. If this cannot be done, an error is returned. Remarks This is only implemented for POSIX systems.

Sharing

enum class CeresEngine::DynamicLibrary::Sharing

strong

Enumerator
Global	The symbols defined by this library will be made available for symbol resolution of subsequently loaded libraries. Remarks This is only implemented for POSIX systems.
Local	This is the converse of global. Symbols defined in this library are not made available to resolve references in subsequently loaded libraries. Remarks This is only implemented for POSIX systems.

Constructor & Destructor Documentation

DynamicLibrary() [1/5]

CeresEngine::DynamicLibrary::DynamicLibrary

(

)

Creates a new unloaded DynamicLibrary.

DynamicLibrary() [2/5]

CeresEngine::DynamicLibrary::DynamicLibrary ( const FilePath &  path, Binding  binding = Binding::Immediate, Sharing  sharing = Sharing::Local  )

explicit

Creates a new DynamicLibrary by loading the library at the given path.

Parameters

path	The library path
binding	The whether symbols should be bound immediately or lazily.
sharing	Whether symbols can be shared with subsequently loaded libraries

DynamicLibrary() [3/5]

CeresEngine::DynamicLibrary::DynamicLibrary ( StringView  name, Binding  binding = Binding::Immediate, Sharing  sharing = Sharing::Local  )

explicit

Creates a new DynamicLibrary by loading the library by it's name.

Parameters

name	The library name
binding	The whether symbols should be bound immediately or lazily.
sharing	Whether symbols can be shared with subsequently loaded libraries

DynamicLibrary() [4/5]

CeresEngine::DynamicLibrary::DynamicLibrary ( const DynamicLibrary &  )

delete

Copy of a DynamicLibrary is not allowed.

DynamicLibrary() [5/5]

CeresEngine::DynamicLibrary::DynamicLibrary ( DynamicLibrary &&  other )

noexcept

Creates a new DynamicLibrary by moving the contents of another.

Parameters

other

The instance to move from

~DynamicLibrary()

CeresEngine::DynamicLibrary::~DynamicLibrary ( )

noexcept

Unloads the dynamic library (if loaded) and destroy the DynamicLibrary object.

Member Function Documentation

available() [1/4]

static bool CeresEngine::DynamicLibrary::available ( const FilePath &  path )

static

Checks if a DynamicLibrary can be loaded with the given path.

If this method returns true, it is safe to assume that you can construct a DynamicLibrary using DynamicLibrary(path).

Parameters

path	The library path

available() [2/4]

static bool CeresEngine::DynamicLibrary::available ( const NameSequence &  names )

static

Checks if a DynamicLibrary can be loaded with the given name.

If this method returns true, it is safe to assume that you can construct a DynamicLibrary using tryOpen(names).

Parameters

names

The library names

available() [3/4]

static bool CeresEngine::DynamicLibrary::available ( StringView  name )

static

Checks if a DynamicLibrary can be loaded with the given name.

If this method returns true, it is safe to assume that you can construct a DynamicLibrary using DynamicLibrary(name).

Parameters

name	The library name

available() [4/4]

template<typename... Ts>

static bool CeresEngine::DynamicLibrary::available ( Ts &&...  names )

inlinestatic

Checks if a DynamicLibrary can be loaded with the given name.

If this method returns true, it is safe to assume that you can construct a DynamicLibrary using tryOpen(names).

Parameters

name	The library name

loaded()

bool CeresEngine::DynamicLibrary::loaded ( ) const

noexcept

Checks if the library is loaded.

Returns

true if the library is loaded.

operator bool()

CeresEngine::DynamicLibrary::operator bool ( ) const

explicitnoexcept

Checks if the library is loaded.

Returns

true if the library is loaded.

operator=() [1/2]

DynamicLibrary & CeresEngine::DynamicLibrary::operator= ( const DynamicLibrary &  )

delete

Copy assignment of a DynamicLibrary is not allowed.

operator=() [2/2]

DynamicLibrary & CeresEngine::DynamicLibrary::operator= ( DynamicLibrary &&  other )

noexcept

Assigns the DynamicLibrary by moving the contents of another.

Parameters

other

The instance to move from

Returns

*this

operator[]()

Symbol CeresEngine::DynamicLibrary::operator[] ( StringView  symbolName ) const

noexcept

Resolves a symbol by it's name.

Parameters

symbolName

The symbol name to be normalize

Returns

A pointer to the normalize symbol

resolve() [1/2]

Symbol CeresEngine::DynamicLibrary::resolve ( StringView  symbolName ) const

noexcept

Resolves a symbol by it's name.

Parameters

symbolName

The symbol name to be normalize

Returns

A pointer to the normalize symbol

resolve() [2/2]

template<typename T >

T CeresEngine::DynamicLibrary::resolve ( StringView  symbolName ) const

noexcept

Resolves a symbol by it's name.

Parameters

symbolName

The symbol name to be normalize

Template Parameters

T	the symbol type

Returns

A pointer to the normalize symbol

tryOpen() [1/2]

static DynamicLibrary CeresEngine::DynamicLibrary::tryOpen ( const NameSequence &  names )

static

Tries to open a DynamicLibrary from a sequence of names and paths.

Parameters

names

The library name sequence to attempt to load with

Returns

The loaded library (if any).

tryOpen() [2/2]

template<typename... Ts>

static DynamicLibrary CeresEngine::DynamicLibrary::tryOpen ( Ts &&...  names )

inlinestatic

Tries to open a DynamicLibrary from a sequence of names and paths.

Parameters

names

The library name sequence to attempt to load with

Returns

The loaded library (if any).

unload()

void CeresEngine::DynamicLibrary::unload ( )

noexcept

Unloads the library.

Friends And Related Symbol Documentation

operator!= [1/2]

bool operator!= ( const DynamicLibrary &  a, const DynamicLibrary &  b  )

friend

Checks if two DynamicLibrary instances do not point to the same loaded library.

Parameters

a	The first operand
b	The second operand

Returns

true if the libraries do not point to the same shared library object.

operator!= [2/2]

bool operator!= ( const DynamicLibrary &  library, std::nullptr_t    )

friend

Checks if a DynamicLibrary is loaded by comparing it to nullptr.

Parameters

library

The library to be checked

Returns

true if the library is loaded.

operator== [1/2]

bool operator== ( const DynamicLibrary &  a, const DynamicLibrary &  b  )

friend

Checks if two DynamicLibrary instances point to the same loaded library.

Parameters

a	The first operand
b	The second operand

Returns

true if both libraries point to the same shared library object.

operator== [2/2]

bool operator== ( const DynamicLibrary &  library, std::nullptr_t    )

friend

Checks if a DynamicLibrary is loaded by comparing it to nullptr.

Parameters

library

The library to be checked

Returns

true if the library is unloaded.

Member Data Documentation

mHandle

NativeHandle CeresEngine::DynamicLibrary::mHandle = nullptr

private

The native handle used to load the dynamic library.

prefix

const StringView CeresEngine::DynamicLibrary::prefix

static

A prefix added to the library name.

This value is platform dependent.

suffix

const StringView CeresEngine::DynamicLibrary::suffix

static

A suffix added to the library name.

This value is platform dependent.

---

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

• /Users/Rogiel/Developer/CeresEngine/Engine/Sources/CeresEngine/Foundation/DynamicLibrary.hpp