NAME
ggInit, ggExit - Initialize and uninitialize LibGG
SYNOPSIS
#include <ggi/gg.h>
int ggInit();
int ggExit();
DESCRIPTION
ggInit initializes LibGG for use, allocates resources, examines the
runtime environment for options, and performs initializations necessary
to provide the LibGG API. This function must be called by the
application (or by proxy by another library used by the application)
and must return successfully before using any other LibGG function;
otherwise the results of invoking LibGG API functions will be
undefined.
ggInit allows multiple invocations. Unless ggExit is called as
described below, subsequent calls to ggInit will do nothing other than
increment a reference counter which LibGG uses to keep track of how
many times it has been initialized. This allows using multiple
libraries which call ggInit together without conflict.
ggExit decrements the reference counter which ggInit increments. Until
this counter indicates that ggExit has been called as many times as
ggInit it will do nothing else.
That is, to free resources used by LibGG, ggExit must be called as many
times as ggInit has been called beforehand (including any calls made by
libraries that depend on LibGG.) After ggExit returns 0, indicating
LibGG is deinitialized, ggInit may be called again to reinitialize
LibGG.
When ggExit determines that it has been called as many times as ggInit
it performs the following actions (order is not guaranteed.) Any tasks
scheduled with ggAddTask(3) are canceled (no task handlers will be
called after ggExit returns.) Any cleanup handlers registered with
ggRegisterCleanup(3) are invoked (no cleanup handlers will be called
after ggExit returns.) If any cleanup handlers invoked
ggCleanupForceExit(3), the current process will be terminated before
ggExit returns. Otherwise, all resources used by LibGG are released
for use by the application or operating system before ggExit returns.
After the "last" ggExit is so invoked, any GG functions (including
ggExit and ggInit) invoked will result in undefined, and probably
undesirable, behavior. After ggExit returns 0, it is again safe to
invoke ggInit.
ggInit and ggExit are threadsafe functions with a few small exceptions.
First, do not call ggInit at the same time from two threads unless
LibGG is already initialized. This is easily avoided by calling ggInit
once before threads that might call it are started. Secondly, it is
illegal to call ggExit after the "last" ggExit is invoked (note
specifically, "invoked," not "has returned"). Naturally you must
prevent threads from doing so, which is easy if you never call ggExit
more times than ggInit. Finally, it is not safe to cancel a thread
while it is calling either of the two functions.
ggInit and ggExit are not guaranteed to be safe to call in any special
context, such as a signal handler or asyncronous procedure call. They
are not safe to use in LibGG task handlers.
Note that, if ggInit is used in a library (like LibGII or LibGGI) and
the application also calls ggInit itself, cleanup handlers installed by
ggRegisterCleanup(3) may not execute when expected. See the
ggRegisterCleanup(3) manpage for more detail on this subject. The same
applies to cancelation of tasks scheduled with ggAddTask(3). See the
ggAddTask(3) manpage for more detail on that subject.
RETURN VALUE
ggInit returns:
· GGI_OK on success;
· GGI_EARGINVAL if the GG_OPTS variable is defined but the options
could not be parsed correctly;
· GGI_EUNKNOWN if the global libgg lock could not be created.
ggExit returns:
· GGI_OK when LibGG has been completely, successfully, deinitialized;
· >0 the number of open ggInit calls, if there has been more than one
call to ggInit. As ggInit and ggExit must be used in properly
nested pairs, for example, the first ggExit after two giiInit(3)s
will return 1;
· GGI_ENOTALLOC if ggExit has been invoked more times than ggInit
has.
SEE ALSO
gg-error(3)