LibGG Functions
===============

Initialize and uninitialize LibGG
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggInit ggExit

Synopsis
--------

::

  #include <ggi/gg.h>

  int ggInit();

  int ggExit();


Description
-----------


`ggInit` initializes the library. This function must be called before
using other LibGG functions; otherwise the results will be undefined.


`ggExit` uninitializes the library (after being initialized by
`ggInit`) and automatically cleanup if necessary.  This should be
called after an application is finished with the library.  If any GG
functions are called after the library has been uninitialized, the
results will be undefined.


ggInit allows multiple invocations.  A reference count is maintained,
and to completely uninitialize the library, `ggExit` must be called as
many times as `ggInit` has been called beforehand.


These functions must only be called if neither libgii nor libggi is
used. These libraries make use of libgg internally, so it will be
properly initialized by `giiInit` and `ggiInit`.


Return value
------------

`ggInit` returns `0` for OK, otherwise an error code.


ggExit returns:

`0`
    after successfully cleaning up,

`>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, e.g. the first `ggExit` after two
    `giiInit`\ s will return 1.
    

`<0`
    error, especially if more `ggExit` calls have been done than
    `ggInit` calls.


Get user home directory
~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggGetUserDir

Synopsis
--------

::

  #include <ggi/gg.h>

  const char * ggGetUserDir(void);


Description
-----------

`ggGetUserDir` returns a path to the user's home directory, whatever
it can be on a given system.  On unix systems it will be the `HOME`
environment variable.


Return value
------------

`ggGetUserDir` returns a NULL-terminated string holding the path the
the current user home directory.  This string is just a reference and
**must not** be freed.


Mutex facilities
~~~~~~~~~~~~~~~~

.. manpage:: 3 ggLockCreate ggLockDestroy ggLock ggUnlock ggTryLock

Synopsis
--------

::

  #include <ggi/gg.h>

  void *ggLockCreate(void);

  int ggLockDestroy(void *lock);

  int ggLock(void *lock);

  int ggUnlock(void *lock);

  int ggTryLock(void *lock);


Description
-----------

These functions allow sensitive resources protection in a threaded
environmment, by ensuring exclusive access to them by a thread or
process.


`ggLockCreate` creates a new open lock. `ggLockDestroy` destroys a lock.

`ggLock` blocks until the :p:`lock` becomes available and acquire it
before returning. This operation is atomic, so it guarantees that no
other thread or process hold the lock after this function returns.

`ggUnlock` releases the :p:`lock`, waking up a process that is
currently waiting for this :p:`lock` in `ggLock`.

`ggTryLock` attempts to acquire the :p:`lock`, but unlike `ggLock` it
will not block if the lock is not available.


Return value
------------


`ggLockCreate` returns an opaque pointer to a mutex, hiding its internal implementation.

`ggLock` returns `0` when the lock is acquired.

`ggUnlock` returns `0` on success.


`ggTryLock` returns `0` on success, or `GGI_EBUSY` if the lock could
not be acquired.


See Also
--------

:man:`pthread_mutex_init(3)`



Cleanup callback facilities
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggRegisterCleanup ggUnregisterCleanup ggCleanupForceExit

Synopsis
--------

::

  #include <ggi/gg.h>

  typedef void (ggcleanup_func)(void *);

  int ggRegisterCleanup(ggcleanup_func *func, void *arg);

  int ggUnregisterCleanup(ggcleanup_func *func, void *arg);

  void ggCleanupForceExit(void);


Description
-----------

`ggRegisterCleanup` registers a callback to be executed on exit. The
:p:`func`\ tion will be called with its :p:`arg`\ ument.


`ggUnregisterCleanup` cancels a callback installed with
`ggRegisterCleanup`.


Once `ggCleanupForceExit` is called, :man:`_exit(2)` will be
explicitly called after all cleanup callbacks.


Return value
------------

`ggRegisterCleanup` and `ggUnregisterCleanup` return `0` on success, a
negative error code otherwise.




Get CPU features
~~~~~~~~~~~~~~~~

.. manpage:: 3 ggGetSwarType

Synopsis
--------

::

  #include <ggi/gg.h>

  enum gg_swartype ggGetSwarType(void);


Description
-----------


`ggGetSwarType` tells which specific instruction sets the CPU
handle. This is useful to choose at runtime a specific implementation
of a very time-consuming routine.


Return value
------------

`ggGetSwarType` returns an integer in which each bit set means that a
specific SWAR is available.


Recognized SWARs
----------------


The following flags are defined for all architectures.  All of these
flags can be OR'ed and are exclusive even between architecture.  Note
at this stage of development some of these SIMD sets are not yet detected
correctly.

`GG_SWAR_NONE`
    The CPU can run a vanilla C program. (hopefully!)
    
`GG_SWAR_32BITC`
    The CPU can perform 32-bit math fast enough to give an advantage over 
    16-bit math for software SWAR implementations.

`GG_SWAR_ALTIVEC`
    The CPU has an AltiVec matrix coprocessor (Motorolla G4.)

`GG_SWAR_SSE`
    The CPU supports Intel Streaming SIMD Extensions.

`GG_SWAR_SSE2`
    The CPU supports Intel Streaming SIMD Extensions Version 2.

`GG_SWAR_MMX`
    The CPU supports Intel Multimedia Extensions.

`GG_SWAR_MMXPLUS`
    The CPU supports Cyrix enhancements to Intel Multimedia Extensions.

`GG_SWAR_3DNOW`
    The CPU supports AMD 3DNOW! instructions (and thus, also MMX.)

`GG_SWAR_ADV3DNOW`
    The CPU supports AMD Advanced 3DNOW! instructions (and thus, also MMX.)

`GG_SWAR_MAX`
    The CPU supports PA-RISC MAX Instructions.

`GG_SWAR_SIGD`
    The CPU supports Microunity Mediaprocessor SIGD instructions.


Additionnaly, 64 bits architectures defines the following flags:

`GG_SWAR_64BITC`
    The CPU can perform 64-bit math fast enough to give an advantage over 
    32-bit and 16-bit math for software SWAR implementations.

`GG_SWAR_MVI`
    The CPU supports DEC (Compaq) Alpha Motion Video Instructions.

`GG_SWAR_MAX2`
    The CPU supports PA-RISC MAX2 Instructions.

`GG_SWAR_MDMX`
    The CPU supports MIPS Digital Media Extension (MaDMaX) Instructions.

`GG_SWAR_MAJC`
    The CPU supports SUN Microprocessor Architecture for Java Computing.

`GG_SWAR_VIS`
    The CPU supports the SUN Visual Instruction Set
