ggLoadModule, ggFreeModule, ggGetSymbolAddress : Portable code module loading facilities

#include <ggi/gg.h>

gg_module ggLoadModule(const char *name, int flags);

void ggFreeModule(gg_module module);

void *ggGetSymbolAddress(gg_module module, const char *symbol);

LibGG abstracts dynamic code loading (and emulates dynamic code loading for statically linked embedded binaries) through a simple API which represents the very lowest level required of any loadable module system. The actual underlying mechanisms used in various operating systems to load additional code into an application on demand vary drastically, however, minus OS-specific frills, they can all be mapped to the above three LibGG API functions.

A more sophisticated module system (a layer above these functions) is also provided as part of the LibGG configuration abstraction system (see ggMLoadModule.)

ggLoadModule finds a loadable collection of code symbols known by the name name through whatever system is available on the operating system. The symbols are loaded into the address space of the caller. If the flags parameter contains the bitflag GG_MODULE_GLOBAL, then certain symbols in the collection are also made accessible to any modules also loaded through ggLoadModule. This may happen even if the bitflag is not supplied, depending on the underlying system, but to guarantee it you must use the bitflag.

ggFreeModule unloads the symbol collection represented by the handle module, which must have been previously loaded with ggLoadModule (module should be a return value from a previous call to ggLoadModule.) Reference counts are kept to ensure that redundantly loaded symbol collections are not discarded until their last owner releases them. Calling ggFreeModule on a handle too many times, or on an invalid handle, may produce undefined results. Accessing symbols after the collections they were contained in are unloaded will produce undesirable and undefined results.

ggGetSymbolAddress searches the symbol collection represented by the handle module, which has been loaded with ggLoadModule (and not yet unloaded with ggFreeModule, of course) for a symbol named symbol, so that the application may use the item associated with the symbol. The parameter module should be a return value from a previous call to ggLoadModule. As ggGetSymbolAddress may have no way of knowing what the symbol represents, the application must take the responsibility for assigning the item a correct C type.

On success, ggLoadModule returns an opaque pointer to a handle representing a newly loaded symbol collection (which must be retained in order to use or free the collection.) These pointers are not guaranteed to be unique. On failure, ggLoadModule returns the special value GG_MODULE_NULL, which is guaranteed never to be used as a valid handle.

ggGetSymbolAddress returns the address of the item that the named symbol represents, if it has been loaded into the caller's address space. Otherwise it returns NULL.