<!-- ##### 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> <!-- ##### 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. @hook_memchunk: the #GMemChunk used for allocating the #GHook elements. @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: <!-- ##### 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. <!-- ##### 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.