Hook Functions: GLib Reference Manual

## Hook Functions Hook Functions — support for manipulating lists of hook functions |

## Functions

void | (*GHookFinalizeFunc) ()
void | (*GHookFunc) ()
gboolean | (*GHookCheckFunc) ()
void | g_hook_list_init ()
void | g_hook_list_invoke ()
void | g_hook_list_invoke_check ()
void | g_hook_list_marshal ()
void | (*GHookMarshaller) ()
void | g_hook_list_marshal_check ()
gboolean | (*GHookCheckMarshaller) ()
void | g_hook_list_clear ()
GHook * | g_hook_alloc ()
#define | g_hook_append()
void | g_hook_prepend ()
void | g_hook_insert_before ()
void | g_hook_insert_sorted ()
gint | (*GHookCompareFunc) ()
gint | g_hook_compare_ids ()
GHook * | g_hook_get ()
GHook * | g_hook_find ()
gboolean | (*GHookFindFunc) ()
GHook * | g_hook_find_data ()
GHook * | g_hook_find_func ()
GHook * | g_hook_find_func_data ()
GHook * | g_hook_first_valid ()
GHook * | g_hook_next_valid ()
#define | G_HOOK_FLAGS()
#define | G_HOOK()
#define | G_HOOK_IS_VALID()
#define | G_HOOK_ACTIVE()
#define | G_HOOK_IN_CALL()
#define | G_HOOK_IS_UNLINKED()
GHook * | g_hook_ref ()
void | g_hook_unref ()
void | g_hook_free ()
gboolean | g_hook_destroy ()
void | g_hook_destroy_link ()

## Types and Values

struct | GHookList
struct | GHook
enum | GHookFlagMask
#define | G_HOOK_FLAG_USER_SHIFT

## Includes

    #include <glib.h>
    #include <glib/gprintf.h>

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

## Functions

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

#### Parameters

hook_list | a GHookList |
hook | the hook in `hook_list` that gets finalized |

### GHookFunc ()

    void
    (*GHookFunc) (gpointer data);

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

hook_list | a GHookList |

### g_hook_alloc ()

    GHook *
    g_hook_alloc (GHookList *hook_list);

Allocates space for a GHook and initializes it.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

hook_list | a GHookList |
sibling | the GHook to insert the new GHook before. | [nullable]
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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

hook_list | a GHookList |
need_valids | `TRUE` if GHook elements which have been destroyed should be skipped |
func | the function to find. | [not nullable]
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.)

#### Parameters

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

#### Parameters

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

### G_HOOK_FLAGS()

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

Gets the flags of a hook.

#### Parameters

hook | a GHook |

### G_HOOK()

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

Casts a pointer to a `GHook*`.

#### Parameters

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.

#### Parameters

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 the case until the GHook is destroyed.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

hook_list | a GHookList |
hook | the GHook to remove |

## Types and Values

### struct GHookList

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

The GHookList struct represents a list of hook functions.

#### Members

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 |

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

#### Members

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 |

### enum GHookFlagMask

Flags used internally in the GHook implementation.

#### Members

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

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