Hook Functions

GLib Reference Manual
<<< Previous Page	Home	Up	Next Page >>>

Details

struct GHookList

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

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.
GMemChunk *`hook_memchunk`	the GMemChunk used for allocating the GHook elements.
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]

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.

struct GHook

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

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 TRUE 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`

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 ()

void        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.

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 hook_free 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.