glib/docs/reference/glib/tmpl/hooks.sgml

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

<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>

<row>
<entry>#guint seq_id;</entry>
<entry>the next free #GHook id.</entry>
</row>

<row>
<entry>#guint hook_size;</entry>
<entry>the size of the #GHookList elements, in bytes.</entry>
</row>

<row>
<entry>#guint is_setup : 1;</entry>
<entry>1 if the #GHookList has been initialized.</entry>
</row>

<row>
<entry>#GHook *hooks;</entry>
<entry>the first #GHook element in the list.</entry>
</row>

<row>
<entry>#GMemChunk *hook_memchunk;</entry>
<entry>the #GMemChunk used for allocating the #GHook elements.</entry>
</row>

<row>
<entry>#GHookFinalizeFunc finalize_hook;</entry>
<entry>the function to call to finalize a #GHook element. 
The default behaviour is to call the hooks <function>destroy</function> 
function.</entry>
</row>

</tbody></tgroup></informaltable>

</para>

@seq_id: 
@hook_size: 
@is_setup: 
@hooks: 
@hook_memchunk: 
@finalize_hook: 


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

<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>

<row>
<entry>#gpointer data;</entry>
<entry>data which is passed to func when this hook is invoked.</entry>
</row>

<row>
<entry>#GHook *next;</entry>
<entry>pointer to the next hook in the list.</entry>
</row>

<row>
<entry>#GHook *prev;</entry>
<entry>pointer to the previous hook in the list.</entry>
</row>

<row>
<entry>#guint ref_count;</entry>
<entry>the reference count of this hook.</entry>
</row>

<row>
<entry>#guint hook_id;</entry>
<entry>the id of this hook, which is unique within its list.</entry>
</row>

<row>
<entry>#guint flags;</entry>
<entry>flags which are set for this hook. See #GHookFlagMask for
predefined flags.</entry>
</row>

<row>
<entry>#gpointer func;</entry>
<entry>the function to call when this hook is invoked. The possible 
signatures for this function are #GHookFunc and #GHookCheckFunc.</entry>
</row>

<row>
<entry>#GDestroyNotify destroy;</entry>
<entry>the default <function>finalize_hook</function> function of a 
#GHookList calls this member of the hook that is being finalized.</entry>
</row>

</tbody></tgroup></informaltable>
</para>

@data: 
@next: 
@prev: 
@ref_count: 
@hook_id: 
@flags: 
@func: 
@destroy: 

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

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