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

# Hook Functions

## Name

Hook Functions -- support for manipulating lists of hook functions.

## Synopsis

    #include <glib.h>

    struct      GHookList;
    struct      GHook;
    void        (*GHookFunc)                    (gpointer data);
    gboolean    (*GHookCheckFunc)               (gpointer data);
    void        (*GHookMarshaller)              (GHook *hook,
                                                 gpointer data);
    gboolean    (*GHookCheckMarshaller)         (GHook *hook,
                                                 gpointer data);
    void        (*GHookFreeFunc)                (GHookList *hook_list,
                                                 GHook *hook);
    #define     G_HOOK_DEFERRED_DESTROY

    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 data);
    void        g_hook_list_marshal_check       (GHookList *hook_list,
                                                 gboolean may_recurse,
                                                 GHookCheckMarshaller marshaller,
                                                 gpointer 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,
                                                 guint hook_id);
    GHook*      g_hook_find                     (GHookList *hook_list,
                                                 gboolean need_valids,
                                                 GHookFindFunc func,
                                                 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);
    gboolean    (*GHookFindFunc)                (GHook *hook,
                                                 gpointer data);
    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_FLAG_USER_SHIFT

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

    void        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,
                                                 guint 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

### struct GHookList

    struct GHookList
    {
      guint		 seq_id;
      guint		 hook_size;
      guint		 is_setup : 1;
      GHook		*hooks;
      GMemChunk	*hook_memchunk;
      GHookFreeFunc	 hook_free; /* virtual function */
      GHookFreeFunc	 hook_destroy; /* virtual function */
    };

guint seq_id; | the next free GHook id.
guint hook_size; | 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.
GHookFreeFunc hook_free; | the function to call to free a GHook element.
GHookFreeFunc hook_destroy; | the function to call to destory a GHook element.

### struct GHook

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

gpointer data; | .
GHook *next; | .
GHook *prev; | .
guint ref_count; | .
guint hook_id; | .
guint flags; | .
gpointer data; | .
GDestroyNotify destroy; | .

### GHookFunc ()

    void        (*GHookFunc)                    (gpointer data);

`data` : |

### GHookCheckFunc ()

    gboolean    (*GHookCheckFunc)               (gpointer data);

`data` : |
Returns : |

### GHookMarshaller ()

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

`hook` : |
`data` : |

### GHookCheckMarshaller ()

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

`hook` : |
`data` : |
Returns : |

### GHookFreeFunc ()

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

`hook_list` : |
`hook` : |

### G_HOOK_DEFERRED_DESTROY

    #define	G_HOOK_DEFERRED_DESTROY	((GHookFreeFunc) 0x01)

### 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 data);

`hook_list` : | a GHookList.
`may_recurse` : |
`marshaller` : |
`data` : |

### g_hook_list_marshal_check ()

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

`hook_list` : | a GHookList.
`may_recurse` : |
`marshaller` : |
`data` : |

### 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,
                                                 guint 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 passed to `func`.
Returns : | the found GHook or NULL if no matching GHook is 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.

### GHookFindFunc ()

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

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

`hook` : | a GHook.
`data` : | user data passed to g_hook_find_func().
Returns : | TRUE if the required GHook has been 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;

### G_HOOK_FLAG_USER_SHIFT

    #define G_HOOK_FLAG_USER_SHIFT	(4)

### 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` : |

### 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,
                                                 guint 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, calling the `hook_destroy` function in the GHookList, and the `destroy` function of the GHook, if they exist.

`hook_list` : | a GHookList.
`hook` : | the GHook to remove.

<<< Previous Page | Home | Up | Next Page >>>
Date and Time Functions | Miscellaneous Utility Functions