Cogs::Module Class Reference

Base class for managing libraries dynamically loaded at runtime. More...

#include <Module.h>

Inheritance diagram for Cogs::Module:

Public Types
enum class	LoadStatus { Unloaded , Loaded , Failed }

Public Member Functions
virtual	~Module ()=default
virtual void	initPtrs ()
template<typename T >
void	getProcAddress (T &ptr, const char *procName)
void *	getProcAddress (const char *procName)
	Retrieves a pointer to the named function.
bool	operator== (const Module &rhs) const

Static Public Member Functions
static void	load (const std::string &path, LoadStatus &status, void *&handle)
	Attempts to load a shared library with the given name.
static void	unload (void *handle)
template<typename T = Module>
static T	load (const std::string &path)
	Loads the named shared library.
static void *	getProcAddress (void *handle, const char *procName)
	Retrives the address of the named function within the shared library identified by the specified handle.

Public Attributes
LoadStatus	status = LoadStatus::Unloaded
void *	handle = nullptr

Protected Member Functions
template<typename RET , typename FN , typename... ARGS>
RET	Call (FN *fn, ARGS... args) const

Detailed Description

Base class for managing libraries dynamically loaded at runtime.

Derive a module implementation from this class with function pointers to library functions. Override the virtual function initPtrs to initialise them through repeated calls to getProcAddress, and then call them as you would any regular function pointer. (Or provide a real API in your class to hide the function pointers from your users and use the protected Call function to safely call them.)

Use the templated Module::load function to retrieve an instance of your Module derived class.

Member Enumeration Documentation

LoadStatus

enum class Cogs::Module::LoadStatus

strong

Enumerator
Unloaded
Loaded
Failed

Constructor & Destructor Documentation

~Module()

virtual Cogs::Module::~Module ( )

virtualdefault

Member Function Documentation

Call()

template<typename RET , typename FN , typename... ARGS>

RET Cogs::Module::Call ( FN *  fn, ARGS...  args  ) const

inlineprotected

getProcAddress() [1/3]

void * Cogs::Module::getProcAddress

(

const char *

procName

)

Retrieves a pointer to the named function.

This function should typically be called from an overridden initPtrs implementation that will be called during Module loading. *============================================================================================

References getProcAddress(), and handle.

getProcAddress() [2/3]

template<typename T >

void Cogs::Module::getProcAddress ( T &  ptr, const char *  procName  )

inline

References Cogs::T.

Referenced by getProcAddress(), and Cogs::ModuleAPI< API >::initPtrs().

getProcAddress() [3/3]

void * Cogs::Module::getProcAddress ( void *  handle, const char *  procName  )

static

Retrives the address of the named function within the shared library identified by the specified handle.

On Linux, this function merely forwards the request to the OS. *============================================================================================

On MacOS, this function merely forwards the request to the OS. *============================================================================================

On Windows, this function merely forwards the request to the OS. *============================================================================================

initPtrs()

virtual void Cogs::Module::initPtrs ( )

inlinevirtual

Reimplemented in Cogs::ModuleAPI< API >.

load() [1/2]

template<typename T = Module>

static T Cogs::Module::load ( const std::string &  path )

inlinestatic

Loads the named shared library.

If T is derived from Module (as opposed to being Module) an overloaded initPtrs function can be used to initialise pointers to functions exported from the library. *============================================================================================

References Cogs::T.

load() [2/2]

void Cogs::Module::load ( const std::string &  path, LoadStatus &  status, void *&  handle  )

static

Attempts to load a shared library with the given name.

The path can be a complete path to the library file, or just the filename of the library excluding any file extension such as DLL or SO. In the latter instance the library will be located for according to the host system's search criteria.

This function is primarily used to load Cogs extensions, but can be used to dynamically load any shared library. *============================================================================================

The path can be a complete path to the library file, or just the filename of the library excluding any file extension. In the latter instance the library will be located according to the host system's search criteria.

This function is primarily used to load Cogs extensions, but can be used to dynamically load any shared library. *============================================================================================

References Failed, handle, Loaded, and status.

operator==()

bool Cogs::Module::operator== ( const Module &  rhs ) const

inline

References handle, and status.

unload()

void Cogs::Module::unload ( void *  handle )

static

Member Data Documentation

handle

void* Cogs::Module::handle = nullptr

Referenced by getProcAddress(), Cogs::ModuleAPI< API >::initPtrs(), load(), Cogs::ModuleAPI< API >::ModuleAPI(), and operator==().

status

LoadStatus Cogs::Module::status = LoadStatus::Unloaded

Referenced by load(), Cogs::ModuleAPI< API >::ModuleAPI(), and operator==().

---

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

• Source/Platform/Module.h
• Source/Platform/Module.cpp
• Source/Platform/Module.Emscripten.cpp
• Source/Platform/Module.Linux.cpp
• Source/Platform/Module.MacOS.cpp
• Source/Platform/Module.Windows.cpp