Hook Functions

Hook Functions — support for manipulating lists of hook functions

Synopsis


#include <glib.h>


                    GHookList;
void                (*GHookFinalizeFunc)                (GHookList *hook_list,
                                                         GHook *hook);
                    GHook;
void                (*GHookFunc)                        (gpointer data);
gboolean            (*GHookCheckFunc)                   (gpointer data);

void                g_hook_list_init                    (GHookList *hook_list,
                                                         guint hook_size);
void                g_hook_list_invoke                  (GHookList *hook_list,
                                                         gboolean may_recurse);
void                g_hook_list_invoke_check            (GHookList *hook_list,
                                                         gboolean may_recurse);
void                g_hook_list_marshal                 (GHookList *hook_list,
                                                         gboolean may_recurse,
                                                         GHookMarshaller marshaller,
                                                         gpointer marshal_data);
void                (*GHookMarshaller)                  (GHook *hook,
                                                         gpointer marshal_data);
void                g_hook_list_marshal_check           (GHookList *hook_list,
                                                         gboolean may_recurse,
                                                         GHookCheckMarshaller marshaller,
                                                         gpointer marshal_data);
gboolean            (*GHookCheckMarshaller)             (GHook *hook,
                                                         gpointer marshal_data);
void                g_hook_list_clear                   (GHookList *hook_list);

GHook*              g_hook_alloc                        (GHookList *hook_list);
#define             g_hook_append                       ( hook_list, hook )
void                g_hook_prepend                      (GHookList *hook_list,
                                                         GHook *hook);
void                g_hook_insert_before                (GHookList *hook_list,
                                                         GHook *sibling,
                                                         GHook *hook);
void                g_hook_insert_sorted                (GHookList *hook_list,
                                                         GHook *hook,
                                                         GHookCompareFunc func);
gint                (*GHookCompareFunc)                 (GHook *new_hook,
                                                         GHook *sibling);
gint                g_hook_compare_ids                  (GHook *new_hook,
                                                         GHook *sibling);

GHook*              g_hook_get                          (GHookList *hook_list,
                                                         gulong hook_id);
GHook*              g_hook_find                         (GHookList *hook_list,
                                                         gboolean need_valids,
                                                         GHookFindFunc func,
                                                         gpointer data);
gboolean            (*GHookFindFunc)                    (GHook *hook,
                                                         gpointer data);
GHook*              g_hook_find_data                    (GHookList *hook_list,
                                                         gboolean need_valids,
                                                         gpointer data);
GHook*              g_hook_find_func                    (GHookList *hook_list,
                                                         gboolean need_valids,
                                                         gpointer func);
GHook*              g_hook_find_func_data               (GHookList *hook_list,
                                                         gboolean need_valids,
                                                         gpointer func,
                                                         gpointer data);

GHook*              g_hook_first_valid                  (GHookList *hook_list,
                                                         gboolean may_be_in_call);
GHook*              g_hook_next_valid                   (GHookList *hook_list,
                                                         GHook *hook,
                                                         gboolean may_be_in_call);
enum                GHookFlagMask;
#define             G_HOOK_FLAGS                        (hook)
#define             G_HOOK_FLAG_USER_SHIFT

#define             G_HOOK                              (hook)
#define             G_HOOK_IS_VALID                     (hook)
#define             G_HOOK_ACTIVE                       (hook)
#define             G_HOOK_IN_CALL                      (hook)
#define             G_HOOK_IS_UNLINKED                  (hook)

GHook*              g_hook_ref                          (GHookList *hook_list,
                                                         GHook *hook);
void                g_hook_unref                        (GHookList *hook_list,
                                                         GHook *hook);
void                g_hook_free                         (GHookList *hook_list,
                                                         GHook *hook);
gboolean            g_hook_destroy                      (GHookList *hook_list,
                                                         gulong hook_id);
void                g_hook_destroy_link                 (GHookList *hook_list,
                                                         GHook *hook);

Description

The GHookList, GHook and their related functions provide support for lists of hook functions. Functions can be added and removed from the lists, and the list of hook functions can be invoked.

Details

GHookList

typedef struct {
  gulong	    seq_id;
  guint		    hook_size : 16;
  guint		    is_setup : 1;
  GHook		   *hooks;
  gpointer	    dummy3;
  GHookFinalizeFunc finalize_hook;
  gpointer	    dummy[2];
} GHookList;

The GHookList struct represents a list of hook functions.

gulong seq_id;

 the next free GHook id

guint hook_size : 16;

 the size of the GHookList elements, in bytes

guint is_setup : 1;

 1 if the GHookList has been initialized

GHook *hooks;

 the first GHook element in the list

gpointer dummy3;

 unused

GHookFinalizeFunc finalize_hook;

 the function to call to finalize a GHook element. The default behaviour is to call the hooks destroy function

gpointer dummy[2];

 unused

GHookFinalizeFunc ()

void                (*GHookFinalizeFunc)                (GHookList *hook_list,
                                                         GHook *hook);

Defines the type of function to be called when a hook in a list of hooks gets finalized.

hook_list :

 a GHookList

hook :

 the hook in hook_list that gets finalized

GHook

typedef struct {
  gpointer	 data;
  GHook		*next;
  GHook		*prev;
  guint		 ref_count;
  gulong	 hook_id;
  guint		 flags;
  gpointer	 func;
  GDestroyNotify destroy;
} GHook;

The GHook struct represents a single hook function in a GHookList.

gpointer data;

 data which is passed to func when this hook is invoked

GHook *next;

 pointer to the next hook in the list

GHook *prev;

 pointer to the previous hook in the list

guint ref_count;

 the reference count of this hook

gulong hook_id;

 the id of this hook, which is unique within its list

guint flags;

 flags which are set for this hook. See GHookFlagMask for predefined flags

gpointer func;

 the function to call when this hook is invoked. The possible signatures for this function are GHookFunc and GHookCheckFunc

GDestroyNotify destroy;

 the default finalize_hook function of a GHookList calls this member of the hook that is being finalized

GHookFunc ()

void                (*GHookFunc)                        (gpointer data);

Defines the type of a hook function that can be invoked by g_hook_list_invoke().

data :

 the data field of the GHook is passed to the hook function here

GHookCheckFunc ()

gboolean            (*GHookCheckFunc)                   (gpointer data);

Defines the type of a hook function that can be invoked by g_hook_list_invoke_check().

data :

 the data field of the GHook is passed to the hook function here

Returns :

 FALSE if the GHook should be destroyed

g_hook_list_init ()

void                g_hook_list_init                    (GHookList *hook_list,
                                                         guint hook_size);

Initializes a GHookList. This must be called before the GHookList is used.

hook_list :

 a GHookList

hook_size :

 the size of each element in the GHookList, typically sizeof (GHook)

g_hook_list_invoke ()

void                g_hook_list_invoke                  (GHookList *hook_list,
                                                         gboolean may_recurse);

Calls all of the GHook functions in a GHookList.

hook_list :

 a GHookList

may_recurse :

 TRUE if functions which are already running (e.g. in another thread) can be called. If set to FALSE, these are skipped

g_hook_list_invoke_check ()

void                g_hook_list_invoke_check            (GHookList *hook_list,
                                                         gboolean may_recurse);

Calls all of the GHook functions in a GHookList. Any function which returns FALSE is removed from the GHookList.

hook_list :

 a GHookList

may_recurse :

 TRUE if functions which are already running (e.g. in another thread) can be called. If set to FALSE, these are skipped

g_hook_list_marshal ()

void                g_hook_list_marshal                 (GHookList *hook_list,
                                                         gboolean may_recurse,
                                                         GHookMarshaller marshaller,
                                                         gpointer marshal_data);

Calls a function on each valid GHook.

hook_list :

 a GHookList

may_recurse :

 TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to FALSE, these are skipped

marshaller :

 the function to call for each GHook

marshal_data :

 data to pass to marshaller

GHookMarshaller ()

void                (*GHookMarshaller)                  (GHook *hook,
                                                         gpointer marshal_data);

Defines the type of function used by g_hook_list_marshal().

hook :

 a GHook

marshal_data :

 user data

g_hook_list_marshal_check ()

void                g_hook_list_marshal_check           (GHookList *hook_list,
                                                         gboolean may_recurse,
                                                         GHookCheckMarshaller marshaller,
                                                         gpointer marshal_data);

Calls a function on each valid GHook and destroys it if the function returns FALSE.

hook_list :

 a GHookList

may_recurse :

 TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to FALSE, these are skipped

marshaller :

 the function to call for each GHook

marshal_data :

 data to pass to marshaller

GHookCheckMarshaller ()

gboolean            (*GHookCheckMarshaller)             (GHook *hook,
                                                         gpointer marshal_data);

Defines the type of function used by g_hook_list_marshal_check().

hook :

 a GHook

marshal_data :

 user data

Returns :

 FALSE if hook should be destroyed

g_hook_list_clear ()

void                g_hook_list_clear                   (GHookList *hook_list);

Removes all the GHook elements from a GHookList.

hook_list :

 a GHookList

g_hook_alloc ()

GHook*              g_hook_alloc                        (GHookList *hook_list);

Allocates space for a GHook and initializes it.

hook_list :

 a GHookList

Returns :

 a new GHook

g_hook_append()

#define             g_hook_append( hook_list, hook )

Appends a GHook onto the end of a GHookList.

hook_list :

 a GHookList

hook :

 the GHook to add to the end of hook_list

g_hook_prepend ()

void                g_hook_prepend                      (GHookList *hook_list,
                                                         GHook *hook);

Prepends a GHook on the start of a GHookList.

hook_list :

 a GHookList

hook :

 the GHook to add to the start of hook_list

g_hook_insert_before ()

void                g_hook_insert_before                (GHookList *hook_list,
                                                         GHook *sibling,
                                                         GHook *hook);

Inserts a GHook into a GHookList, before a given GHook.

hook_list :

 a GHookList

sibling :

 the GHook to insert the new GHook before

hook :

 the GHook to insert

g_hook_insert_sorted ()

void                g_hook_insert_sorted                (GHookList *hook_list,
                                                         GHook *hook,
                                                         GHookCompareFunc func);

Inserts a GHook into a GHookList, sorted by the given function.

hook_list :

 a GHookList

hook :

 the GHook to insert

func :

 the comparison function used to sort the GHook elements

GHookCompareFunc ()

gint                (*GHookCompareFunc)                 (GHook *new_hook,
                                                         GHook *sibling);

Defines the type of function used to compare GHook elements in g_hook_insert_sorted().

new_hook :

 the GHook being inserted

sibling :

 the GHook to compare with new_hook

Returns :

 a value <= 0 if new_hook should be before sibling

g_hook_compare_ids ()

gint                g_hook_compare_ids                  (GHook *new_hook,
                                                         GHook *sibling);

Compares the ids of two GHook elements, returning a negative value if the second id is greater than the first.

new_hook :

 a GHook

sibling :

 a GHook to compare with new_hook

Returns :

 a value <= 0 if the id of sibling is >= the id of new_hook

g_hook_get ()

GHook*              g_hook_get                          (GHookList *hook_list,
                                                         gulong hook_id);

Returns the GHook with the given id, or NULL if it is not found.

hook_list :

 a GHookList

hook_id :

 a hook id

Returns :

 the GHook with the given id, or NULL if it is not found

g_hook_find ()

GHook*              g_hook_find                         (GHookList *hook_list,
                                                         gboolean need_valids,
                                                         GHookFindFunc func,
                                                         gpointer data);

Finds a GHook in a GHookList using the given function to test for a match.

hook_list :

 a GHookList

need_valids :

 TRUE if GHook elements which have been destroyed should be skipped

func :

 the function to call for each GHook, which should return TRUE when the GHook has been found

data :

 the data to pass to func

Returns :

 the found GHook or NULL if no matching GHook is found

GHookFindFunc ()

gboolean            (*GHookFindFunc)                    (GHook *hook,
                                                         gpointer data);

Defines the type of the function passed to g_hook_find().

hook :

 a GHook

data :

 user data passed to g_hook_find_func()

Returns :

 TRUE if the required GHook has been found

g_hook_find_data ()

GHook*              g_hook_find_data                    (GHookList *hook_list,
                                                         gboolean need_valids,
                                                         gpointer data);

Finds a GHook in a GHookList with the given data.

hook_list :

 a GHookList

need_valids :

 TRUE if GHook elements which have been destroyed should be skipped

data :

 the data to find

Returns :

 the GHook with the given data or NULL if no matching GHook is found

g_hook_find_func ()

GHook*              g_hook_find_func                    (GHookList *hook_list,
                                                         gboolean need_valids,
                                                         gpointer func);

Finds a GHook in a GHookList with the given function.

hook_list :

 a GHookList

need_valids :

 TRUE if GHook elements which have been destroyed should be skipped

func :

 the function to find

Returns :

 the GHook with the given func or NULL if no matching GHook is found

g_hook_find_func_data ()

GHook*              g_hook_find_func_data               (GHookList *hook_list,
                                                         gboolean need_valids,
                                                         gpointer func,
                                                         gpointer data);

Finds a GHook in a GHookList with the given function and data.

hook_list :

 a GHookList

need_valids :

 TRUE if GHook elements which have been destroyed should be skipped

func :

 the function to find

data :

 the data to find

Returns :

 the GHook with the given func and data or NULL if no matching GHook is found

g_hook_first_valid ()

GHook*              g_hook_first_valid                  (GHookList *hook_list,
                                                         gboolean may_be_in_call);

Returns the first GHook in a GHookList which has not been destroyed. The reference count for the GHook is incremented, so you must call g_hook_unref() to restore it when no longer needed. (Or call g_hook_next_valid() if you are stepping through the GHookList.)

hook_list :

 a GHookList

may_be_in_call :

 TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to FALSE, these are skipped

Returns :

 the first valid GHook, or NULL if none are valid

g_hook_next_valid ()

GHook*              g_hook_next_valid                   (GHookList *hook_list,
                                                         GHook *hook,
                                                         gboolean may_be_in_call);

Returns the next GHook in a GHookList which has not been destroyed. The reference count for the GHook is incremented, so you must call g_hook_unref() to restore it when no longer needed. (Or continue to call g_hook_next_valid() until NULL is returned.)

hook_list :

 a GHookList

hook :

 the current GHook

may_be_in_call :

 TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to FALSE, these are skipped

Returns :

 the next valid GHook, or NULL if none are valid

enum GHookFlagMask

typedef enum
{
  G_HOOK_FLAG_ACTIVE	    = 1 << 0,
  G_HOOK_FLAG_IN_CALL	    = 1 << 1,
  G_HOOK_FLAG_MASK	    = 0x0f
} GHookFlagMask;

Flags used internally in the GHook implementation.

G_HOOK_FLAG_ACTIVE

 set if the hook has not been destroyed

G_HOOK_FLAG_IN_CALL

 set if the hook is currently being run

G_HOOK_FLAG_MASK

 A mask covering all bits reserved for hook flags; see G_HOOK_FLAGS_USER_SHIFT

G_HOOK_FLAGS()

#define	G_HOOK_FLAGS(hook)		(G_HOOK (hook)->flags)

Returns the flags of a hook.

hook :

 a GHook

G_HOOK_FLAG_USER_SHIFT

#define G_HOOK_FLAG_USER_SHIFT	(4)

The position of the first bit which is not reserved for internal use be the GHook implementation, i.e. 1 << G_HOOK_FLAG_USER_SHIFT is the first bit which can be used for application-defined flags.

G_HOOK()

#define	G_HOOK(hook)			((GHook*) (hook))

Casts a pointer to a GHook*.

hook :

 a pointer

G_HOOK_IS_VALID()

#define             G_HOOK_IS_VALID(hook)

Returns TRUE if the GHook is valid, i.e. it is in a GHookList, it is active and it has not been destroyed.

hook :

 a GHook

Returns :

 TRUE if the GHook is valid

G_HOOK_ACTIVE()

#define             G_HOOK_ACTIVE(hook)

Returns TRUE if the GHook is active, which is normally TRUE until the GHook is destroyed.

hook :

 a GHook

Returns :

 TRUE if the GHook is active

G_HOOK_IN_CALL()

#define             G_HOOK_IN_CALL(hook)

Returns TRUE if the GHook function is currently executing.

hook :

 a GHook

Returns :

 TRUE if the GHook function is currently executing

G_HOOK_IS_UNLINKED()

#define             G_HOOK_IS_UNLINKED(hook)

Returns TRUE if the GHook is not in a GHookList.

hook :

 a GHook

Returns :

 TRUE if the GHook is not in a GHookList

g_hook_ref ()

GHook*              g_hook_ref                          (GHookList *hook_list,
                                                         GHook *hook);

Increments the reference count for a GHook.

hook_list :

 a GHookList

hook :

 the GHook to increment the reference count of

Returns :

 the hook that was passed in (since 2.6)

g_hook_unref ()

void                g_hook_unref                        (GHookList *hook_list,
                                                         GHook *hook);

Decrements the reference count of a GHook. If the reference count falls to 0, the GHook is removed from the GHookList and g_hook_free() is called to free it.

hook_list :

 a GHookList

hook :

 the GHook to unref

g_hook_free ()

void                g_hook_free                         (GHookList *hook_list,
                                                         GHook *hook);

Calls the GHookList finalize_hook function if it exists, and frees the memory allocated for the GHook.

hook_list :

 a GHookList

hook :

 the GHook to free

g_hook_destroy ()

gboolean            g_hook_destroy                      (GHookList *hook_list,
                                                         gulong hook_id);

Destroys a GHook, given its ID.

hook_list :

 a GHookList

hook_id :

 a hook ID

Returns :

 TRUE if the GHook was found in the GHookList and destroyed

g_hook_destroy_link ()

void                g_hook_destroy_link                 (GHookList *hook_list,
                                                         GHook *hook);

Removes one GHook from a GHookList, marking it inactive and calling g_hook_unref() on it.

hook_list :

 a GHookList

hook :

 the GHook to remove