| <!-- ##### SECTION Title ##### --> |
| Hook Functions |
| |
| <!-- ##### SECTION Short_Description ##### --> |
| support for manipulating lists of hook functions. |
| |
| <!-- ##### SECTION Long_Description ##### --> |
| <para> |
| 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. |
| |
| </para> |
| |
| <!-- ##### SECTION See_Also ##### --> |
| <para> |
| |
| </para> |
| |
| <!-- ##### SECTION Stability_Level ##### --> |
| |
| |
| <!-- ##### STRUCT GHookList ##### --> |
| <para> |
| The <structname>GHookList</structname> struct represents a |
| list of hook functions. |
| </para> |
| |
| @seq_id: the next free #GHook id. |
| @hook_size: the size of the #GHookList elements, in bytes. |
| @is_setup: 1 if the #GHookList has been initialized. |
| @hooks: the first #GHook element in the list. |
| @dummy3: |
| @finalize_hook: the function to call to finalize a #GHook element. The |
| default behaviour is to call the hooks <function>destroy</function> function. |
| @dummy: |
| |
| <!-- ##### USER_FUNCTION GHookFinalizeFunc ##### --> |
| <para> |
| Defines the type of function to be called when a hook in a |
| list of hooks gets finalized. |
| </para> |
| |
| @hook_list: a #GHookList. |
| @hook: the hook in @hook_list that gets finalized. |
| |
| |
| <!-- ##### STRUCT GHook ##### --> |
| <para> |
| The <structname>GHook</structname> struct represents a single hook |
| function in a #GHookList. |
| </para> |
| |
| @data: data which is passed to func when this hook is invoked. |
| @next: pointer to the next hook in the list. |
| @prev: pointer to the previous hook in the list. |
| @ref_count: the reference count of this hook. |
| @hook_id: the id of this hook, which is unique within its list. |
| @flags: flags which are set for this hook. See #GHookFlagMask for |
| predefined flags. |
| @func: the function to call when this hook is invoked. The possible |
| signatures for this function are #GHookFunc and #GHookCheckFunc. |
| @destroy: the default <function>finalize_hook</function> function of a |
| #GHookList calls this member of the hook that is being finalized. |
| |
| <!-- ##### USER_FUNCTION GHookFunc ##### --> |
| <para> |
| Defines the type of a hook function that can be invoked |
| by g_hook_list_invoke(). |
| </para> |
| |
| @data: the data field of the #GHook is passed to the hook function here. |
| |
| |
| <!-- ##### USER_FUNCTION GHookCheckFunc ##### --> |
| <para> |
| Defines the type of a hook function that can be invoked |
| by g_hook_list_invoke_check(). |
| </para> |
| |
| @data: the data field of the #GHook is passed to the hook function here. |
| @Returns: %FALSE if the #GHook should be destroyed. |
| |
| |
| <!-- ##### FUNCTION g_hook_list_init ##### --> |
| <para> |
| Initializes a #GHookList. |
| This must be called before the #GHookList is used. |
| </para> |
| |
| @hook_list: a #GHookList. |
| @hook_size: the size of each element in the #GHookList, typically |
| <literal>sizeof (GHook)</literal>. |
| |
| |
| <!-- ##### FUNCTION g_hook_list_invoke ##### --> |
| <para> |
| Calls all of the #GHook functions in a #GHookList. |
| </para> |
| |
| @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. |
| |
| |
| <!-- ##### FUNCTION g_hook_list_invoke_check ##### --> |
| <para> |
| Calls all of the #GHook functions in a #GHookList. |
| Any function which returns %TRUE is removed from the #GHookList. |
| </para> |
| |
| @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. |
| |
| |
| <!-- ##### FUNCTION g_hook_list_marshal ##### --> |
| <para> |
| Calls a function on each valid #GHook. |
| </para> |
| |
| @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. |
| |
| |
| <!-- ##### USER_FUNCTION GHookMarshaller ##### --> |
| <para> |
| Defines the type of function used by g_hook_list_marshal(). |
| </para> |
| |
| @hook: a #GHook. |
| @marshal_data: user data. |
| |
| |
| <!-- ##### FUNCTION g_hook_list_marshal_check ##### --> |
| <para> |
| Calls a function on each valid #GHook and destroys it if the |
| function returns %FALSE. |
| </para> |
| |
| @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. |
| |
| |
| <!-- ##### USER_FUNCTION GHookCheckMarshaller ##### --> |
| <para> |
| Defines the type of function used by g_hook_list_marshal_check(). |
| </para> |
| |
| @hook: a #GHook. |
| @marshal_data: user data. |
| @Returns: %FALSE if @hook should be destroyed. |
| |
| |
| <!-- ##### FUNCTION g_hook_list_clear ##### --> |
| <para> |
| Removes all the #GHook elements from a #GHookList. |
| </para> |
| |
| @hook_list: a #GHookList. |
| |
| |
| <!-- ##### FUNCTION g_hook_alloc ##### --> |
| <para> |
| Allocates space for a #GHook and initializes it. |
| </para> |
| |
| @hook_list: a #GHookList. |
| @Returns: a new #GHook. |
| |
| |
| <!-- ##### MACRO g_hook_append ##### --> |
| <para> |
| Appends a #GHook onto the end of a #GHookList. |
| </para> |
| |
| @hook_list: a #GHookList. |
| @hook: the #GHook to add to the end of @hook_list. |
| |
| |
| <!-- ##### FUNCTION g_hook_prepend ##### --> |
| <para> |
| Prepends a #GHook on the start of a #GHookList. |
| </para> |
| |
| @hook_list: a #GHookList. |
| @hook: the #GHook to add to the start of @hook_list. |
| |
| |
| <!-- ##### FUNCTION g_hook_insert_before ##### --> |
| <para> |
| Inserts a #GHook into a #GHookList, before a given #GHook. |
| </para> |
| |
| @hook_list: a #GHookList. |
| @sibling: the #GHook to insert the new #GHook before. |
| @hook: the #GHook to insert. |
| |
| |
| <!-- ##### FUNCTION g_hook_insert_sorted ##### --> |
| <para> |
| Inserts a #GHook into a #GHookList, sorted by the given function. |
| </para> |
| |
| @hook_list: a #GHookList. |
| @hook: the #GHook to insert. |
| @func: the comparison function used to sort the #GHook elements. |
| |
| |
| <!-- ##### USER_FUNCTION GHookCompareFunc ##### --> |
| <para> |
| Defines the type of function used to compare #GHook elements in |
| g_hook_insert_sorted(). |
| </para> |
| |
| @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. |
| |
| |
| <!-- ##### FUNCTION g_hook_compare_ids ##### --> |
| <para> |
| Compares the ids of two #GHook elements, returning a negative value |
| if the second id is greater than the first. |
| </para> |
| |
| @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. |
| |
| |
| <!-- ##### FUNCTION g_hook_get ##### --> |
| <para> |
| Returns the #GHook with the given id, or %NULL if it is not found. |
| </para> |
| |
| @hook_list: a #GHookList. |
| @hook_id: a hook id. |
| @Returns: the #GHook with the given id, or %NULL if it is not found. |
| |
| |
| <!-- ##### FUNCTION g_hook_find ##### --> |
| <para> |
| Finds a #GHook in a #GHookList using the given function to test for a match. |
| </para> |
| |
| @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. |
| |
| |
| <!-- ##### USER_FUNCTION GHookFindFunc ##### --> |
| <para> |
| Defines the type of the function passed to g_hook_find(). |
| </para> |
| |
| @hook: a #GHook. |
| @data: user data passed to g_hook_find_func(). |
| @Returns: %TRUE if the required #GHook has been found. |
| |
| |
| <!-- ##### FUNCTION g_hook_find_data ##### --> |
| <para> |
| Finds a #GHook in a #GHookList with the given data. |
| </para> |
| |
| @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. |
| |
| |
| <!-- ##### FUNCTION g_hook_find_func ##### --> |
| <para> |
| Finds a #GHook in a #GHookList with the given function. |
| </para> |
| |
| @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. |
| |
| |
| <!-- ##### FUNCTION g_hook_find_func_data ##### --> |
| <para> |
| Finds a #GHook in a #GHookList with the given function and data. |
| </para> |
| |
| @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. |
| |
| |
| <!-- ##### FUNCTION g_hook_first_valid ##### --> |
| <para> |
| 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.) |
| </para> |
| |
| @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. |
| |
| |
| <!-- ##### FUNCTION g_hook_next_valid ##### --> |
| <para> |
| 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.) |
| |
| </para> |
| |
| @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 ##### --> |
| <para> |
| Flags used internally in the #GHook implementation. |
| </para> |
| |
| @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 |
| |
| <!-- ##### MACRO G_HOOK_FLAGS ##### --> |
| <para> |
| Returns the flags of a hook. |
| </para> |
| |
| @hook: a #GHook. |
| |
| |
| <!-- ##### MACRO G_HOOK_FLAG_USER_SHIFT ##### --> |
| <para> |
| The position of the first bit which is not reserved for internal |
| use be the #GHook implementation, i.e. |
| <literal>1 << G_HOOK_FLAG_USER_SHIFT</literal> is the first bit |
| which can be used for application-defined flags. |
| </para> |
| |
| |
| |
| <!-- ##### MACRO G_HOOK ##### --> |
| <para> |
| Casts a pointer to a <literal>GHook*</literal>. |
| </para> |
| |
| @hook: a pointer. |
| |
| |
| <!-- ##### MACRO G_HOOK_IS_VALID ##### --> |
| <para> |
| Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList, it is active |
| and it has not been destroyed. |
| </para> |
| |
| @hook: a #GHook. |
| @Returns: %TRUE if the #GHook is valid. |
| |
| |
| <!-- ##### MACRO G_HOOK_ACTIVE ##### --> |
| <para> |
| Returns %TRUE if the #GHook is active, which is normally %TRUE until the #GHook |
| is destroyed. |
| </para> |
| |
| @hook: a #GHook. |
| @Returns: %TRUE if the #GHook is active. |
| |
| |
| <!-- ##### MACRO G_HOOK_IN_CALL ##### --> |
| <para> |
| Returns %TRUE if the #GHook function is currently executing. |
| </para> |
| |
| @hook: a #GHook. |
| @Returns: %TRUE if the #GHook function is currently executing. |
| |
| |
| <!-- ##### MACRO G_HOOK_IS_UNLINKED ##### --> |
| <para> |
| Returns %TRUE if the #GHook is not in a #GHookList. |
| |
| </para> |
| |
| @hook: a #GHook. |
| @Returns: %TRUE if the #GHook is not in a #GHookList. |
| |
| |
| <!-- ##### FUNCTION g_hook_ref ##### --> |
| <para> |
| Increments the reference count for a #GHook. |
| </para> |
| |
| @hook_list: a #GHookList. |
| @hook: the #GHook to increment the reference count of. |
| @Returns: the @hook that was passed in (since 2.6) |
| |
| |
| <!-- ##### FUNCTION g_hook_unref ##### --> |
| <para> |
| 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. |
| </para> |
| |
| @hook_list: a #GHookList. |
| @hook: the #GHook to unref. |
| |
| |
| <!-- ##### FUNCTION g_hook_free ##### --> |
| <para> |
| Calls the #GHookList @hook_free function if it exists, and frees the memory |
| allocated for the #GHook. |
| </para> |
| |
| @hook_list: a #GHookList. |
| @hook: the #GHook to free. |
| |
| |
| <!-- ##### FUNCTION g_hook_destroy ##### --> |
| <para> |
| Destroys a #GHook, given its ID. |
| </para> |
| |
| @hook_list: a #GHookList. |
| @hook_id: a hook ID. |
| @Returns: %TRUE if the #GHook was found in the #GHookList and destroyed. |
| |
| |
| <!-- ##### FUNCTION g_hook_destroy_link ##### --> |
| <para> |
| Removes one #GHook from a #GHookList, marking it inactive and calling |
| g_hook_unref() on it. |
| </para> |
| |
| @hook_list: a #GHookList. |
| @hook: the #GHook to remove. |
| |
| |