NAME¶
ggGetScope,
ggFromScope,
ggDelScope,
ggNewScope -
Portable code module loading facilities
SYNOPSIS¶
#include <ggi/gg.h>
gg_scope ggGetScope(const char *location);
void ggDelScope(gg_scope scope);
void *ggFromScope(gg_scope, const char *symbol);
typedef void *(*ggfunc_scope_get)(void * handle, const char * symbol);
typedef void (*ggfunc_scope_del)(void * handle);
gg_scope ggNewScope(const char * location, void * handle,
ggfunc_scope_get get, ggfunc_scope_del del)
DESCRIPTION¶
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.
ggGetScope finds a loadable collection of symbols known by its
location through whatever system is available on the operating system.
Those symbols were once supposed to be code from modules, but the scope
abstraction does not impose this restriction. The scopes can have different
implementations and are not restricted to dynamic libraries. They could also
be used as an interface to a attribute/value configuration system.
Note that when a scope happens to be dynamic library, the symbols are loaded
into the address space of the caller, but libgg does not guarantee that the
imported symbols will be seen by other modules.
ggDelScope unloads the symbol collection represented by the handle
scope, which must have been previously loaded with
ggGetScope
(
scope should be a return value from a previous call to
ggGetScope.) Reference counts are kept to ensure that redundantly
loaded symbol collections are not discarded until their last owner releases
them. Calling
ggDelScope 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.
ggFromScope searches the symbol collection represented by the handle
scope, which has been loaded with
ggGetScope (and not yet
unloaded with
ggDelScope, of course) for a symbol named
symbol,
so that the application may use the item associated with the symbol. The
parameter
scope should be a return value from a previous call to
ggDelScope. As
ggFromScope may have no way of knowing what the
symbol represents, the application must take the responsibility for assigning
the item a correct C type.
ggNewScope allows to register a custom scope to libgg. The primary
purpose is to allow libraries to provide builtin modules that are accessible
through the same interface as dynamic ones.
location is the string at
which the scope can be retreived.
handle is a opaque pointer provided
by the caller that will be passed to the callbacks.
get is a function
that take an opaque handle, a symbol name, and that must return the requested
symbol address, or NULL if not found.
del is a function that will take
the provided handler, and that must cleanup everything before the scope is
removed from the scope registry. This scheme allows to implement all kind of
scopes in a very flexible way. Note that
ggNewScope will take a
reference on the scope.
RETURN VALUE¶
On success,
ggGetScope 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,
ggGetScope returns
NULL.
ggFromScope 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. Note that the value associated to a symbol really
depends on the scope itself and the caller must know what is behind it. So a
NULL value does not necessarily means failure. It could be a valid
value for a specific scope.
ggNewScope returns an opaque pointer to a handle representing the custom
scope. On failure,
ggNewScope returns
NULL.