limes::files::DynamicLibrary Class Reference

This class represents a dynamically loaded library. More...

#include <lfilesystem_DynamicLibrary.h>

Classes
class	Listener
	This class listens for events to a DynamicLibrary and receives a callback when the library is opened, closed, or reloaded. More...
class	Reloader
	This class watches a dynamic library file for changes on disk. More...

Public Types
using	Handle = void *
	The type of platform-specific handle used for dynamic libraries. More...

Public Member Functions
	DynamicLibrary (const DynamicLibrary &)=delete
	DynamicLibrary (DynamicLibrary &&other) noexcept
	~DynamicLibrary ()
	Destructor. More...
void	close ()
	Closes the shared library, if one is open. More...
void *	findFunction (const std::string_view &functionName) noexcept
	Attempts to locate a function within the shared library, and, if found, returns a pointer to the function. More...
File	getFile () const
	Attempts to locate the file on disk where the code for the current shared library is actually located. More...
Handle	getHandle () const noexcept
	Returns a platform-specific handle to the currently open shared library (if any). More...
std::string	getName () const
	Attempts to determine the name of the library, if it is open. More...
bool	isOpen () const noexcept
	Returns true if the library is currently open. More...
bool	open (const std::string_view &nameOrPath) noexcept
	Attempts to open a new shared library. More...
bool	operator!= (const DynamicLibrary &other) const noexcept
	Returns true if this library object does not refer to the same shared library as the other one. More...
DynamicLibrary &	operator= (const DynamicLibrary &)=delete
DynamicLibrary &	operator= (DynamicLibrary &&other) noexcept
bool	operator== (const DynamicLibrary &other) const noexcept
	Returns true if this library object refers to the same shared library as the other one. More...
bool	reload ()
	Closes and reloads the library. More...
Constructors
	DynamicLibrary ()=default
	Creates an unopened library object. More...
	DynamicLibrary (const std::string_view &nameOrPath) noexcept
	Creates a library object and attempts to open the specified library. More...

Detailed Description

This class represents a dynamically loaded library.

On Unixes, this is the equivalent of using dlopen() , but wrapped in an RAII class that frees the library handle when it is destroyed.

This class can also locate the file on disk that the library was loaded from, and "reload" itself.

All functions of this class are thread-safe; the library handle is stored atomically.

Todo:

double check iOS. I've heard that iOS disallows calling dlopen() .

Todo:

use emscripten_dlopen when building with Emscripten. Note that this function is asynchronous, however.

Todo:

function to add a directory to the search paths for DLLs?

Todo:

function to check if dynamic libraries are supported by the current system

Definition at line 57 of file lfilesystem_DynamicLibrary.h.

Member Typedef Documentation

Handle

limes::files::DynamicLibrary::Handle

The type of platform-specific handle used for dynamic libraries.

This will be HMODULE on Windows and void* everywhere else. This will always be a pointer or pointer-like type.

Definition at line 87 of file lfilesystem_DynamicLibrary.h.

Constructor & Destructor Documentation

DynamicLibrary() [1/2]

limes::files::DynamicLibrary::DynamicLibrary ( )

default

Creates an unopened library object.

Call open() to actually open a library.

DynamicLibrary() [2/2]

limes::files::DynamicLibrary::DynamicLibrary ( const std::string_view &  nameOrPath )

explicitnoexcept

Creates a library object and attempts to open the specified library.

See also

open()

~DynamicLibrary()

limes::files::DynamicLibrary::~DynamicLibrary

(

)

Destructor.

If the library is open when this object is destroyed, the destructor will close the library.

See also

close()

Member Function Documentation

close()

void limes::files::DynamicLibrary::close

(

)

Closes the shared library, if one is open.

This will call libraryClosed() on all listeners.

Postcondition

Calling getHandle() after calling this function will return nullptr .

See also

Listener::libraryClosed()

findFunction()

void* limes::files::DynamicLibrary::findFunction ( const std::string_view &  functionName )

noexcept

Attempts to locate a function within the shared library, and, if found, returns a pointer to the function.

getFile()

File limes::files::DynamicLibrary::getFile

(

)

const

Attempts to locate the file on disk where the code for the current shared library is actually located.

If the library isn't open, returns a null file.

Todo:

Emscripten implementation

getHandle()

Handle limes::files::DynamicLibrary::getHandle ( ) const

noexcept

Returns a platform-specific handle to the currently open shared library (if any).

getName()

std::string limes::files::DynamicLibrary::getName

(

)

const

Attempts to determine the name of the library, if it is open.

If the library isn't open, returns an empty string.

isOpen()

bool limes::files::DynamicLibrary::isOpen ( ) const

noexcept

Returns true if the library is currently open.

This can be called after the constructor, or after calling open(), to check if the library opened correctly.

open()

bool limes::files::DynamicLibrary::open ( const std::string_view &  nameOrPath )

noexcept

Attempts to open a new shared library.

If one was previously open, calling this will close the old library (even if the new library fails to open).

This will call libraryOpened() on all listeners.

Returns

True if the library was opened successfully

See also

Listener::libraryOpened()

operator!=()

bool limes::files::DynamicLibrary::operator!= ( const DynamicLibrary &  other ) const

noexcept

Returns true if this library object does not refer to the same shared library as the other one.

operator==()

bool limes::files::DynamicLibrary::operator== ( const DynamicLibrary &  other ) const

noexcept

Returns true if this library object refers to the same shared library as the other one.

reload()

bool limes::files::DynamicLibrary::reload

(

)

Closes and reloads the library.

This locates the file on disk from which the library was loaded, then closes the library and reopens it from this same file.

Returns

True if the library was reloaded successfully; false if the library was not open when this was called, or if reopening it fails.

See also

Reloader

---

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

• lfilesystem_DynamicLibrary.h