[ prev :: next :: up ] libgg-current (3)

Cleanup callback facilities

Name

ggRegisterCleanup, ggUnregisterCleanup, ggCleanupForceExit : Cleanup callback facilities

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 when an abnormal and unexpected program termination is imminant. The :p:`func`tion will be called with its :p:`arg`ument.

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 469); backlink

Unknown interpreted text role "p".

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 469); backlink

Unknown interpreted text role "p".

ggUnregisterCleanup cancels a callback installed with ggRegisterCleanup.

Once ggCleanupForceExit is called, :man:`_exit(2)` will be explicitly called after all registered cleanup callbacks. It is not possible to cancel such a request once it is made.

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 478); backlink

Unknown interpreted text role "man".

These functions are for emergency use only, and should not be used as a substitute to proper memory deallocation routines. They should only be used to restore system state that would otherwise be left corrupted after an abnormal program termination, for example, a video-card timing mode. When normal termination occurs, ggUnregisterCleanup should be called to systematically remove the emergency callbacks.

Callback functions registered with ggRegisterCleanup should not itself invoke (or invoke any subroutines that may in turn invoke) any of the LibGG locking functions ggLockCreate, ggLockDestroy, ggLock, ggUnlock, or ggTryLock. Since they are only invoked during emergencies, they should be ignoring locks in general.

The callback functions may be called by a normal call to ggExit(). As such, it is considered best practice to use ggUnRegisterCleanup() to remove cleanups when gracefully deinitializing LibGG or a library that uses LibGG.

Return value

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

 
[ prev :: next :: up ] libgg-current (3)
2008/05/04 23:14:55