luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-04-23 07:39:17 +02:00
Code Issues Packages Projects Releases Wiki Activity

Fixes and corrections

Browse Source 
svn path=/trunk/; revision=5838
This commit is contained in:
Matthias Clasen 2007-11-09 03:21:27 +00:00
parent 6fec255f17
commit f1675bbcc7
2 changed files with 116 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/reference/ChangeLog
View File

@ -1,3 +1,7 @@
2007-11-08 Matthias Clasen <mclasen@redhat.com>
* glib/tmpl/hooks.sgml: Cleanups and fixes
2007-11-08 Matthias Clasen <mclasen@redhat.com> 2007-11-08 Matthias Clasen <mclasen@redhat.com>
* glib/tmpl/thread_pools.sgml: Fix the GThreadPool docs. * glib/tmpl/thread_pools.sgml: Fix the GThreadPool docs.

222
docs/reference/glib/tmpl/hooks.sgml
View File

@ -26,13 +26,13 @@ The <structname>GHookList</structname> struct represents a
list of hook functions. list of hook functions.
</para> </para>
@seq_id: the next free #GHook id. @seq_id: the next free #GHook id
@hook_size: the size of the #GHookList elements, in bytes. @hook_size: the size of the #GHookList elements, in bytes
@is_setup: 1 if the #GHookList has been initialized. @is_setup: 1 if the #GHookList has been initialized
@hooks: the first #GHook element in the list. @hooks: the first #GHook element in the list
@dummy3: unused @dummy3: unused
@finalize_hook: the function to call to finalize a #GHook element. The @finalize_hook: the function to call to finalize a #GHook element. The
default behaviour is to call the hooks <function>destroy</function> function. default behaviour is to call the hooks <function>destroy</function> function
@dummy: unused @dummy: unused
<!-- ##### USER_FUNCTION GHookFinalizeFunc ##### --> <!-- ##### USER_FUNCTION GHookFinalizeFunc ##### -->
@ -41,8 +41,8 @@ Defines the type of function to be called when a hook in a
list of hooks gets finalized. list of hooks gets finalized.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@hook: the hook in @hook_list that gets finalized. @hook: the hook in @hook_list that gets finalized
<!-- ##### STRUCT GHook ##### --> <!-- ##### STRUCT GHook ##### -->
@ -51,17 +51,17 @@ The <structname>GHook</structname> struct represents a single hook
function in a #GHookList. function in a #GHookList.
</para> </para>
@data: data which is passed to func when this hook is invoked. @data: data which is passed to func when this hook is invoked
@next: pointer to the next hook in the list. @next: pointer to the next hook in the list
@prev: pointer to the previous hook in the list. @prev: pointer to the previous hook in the list
@ref_count: the reference count of this hook. @ref_count: the reference count of this hook
@hook_id: the id of this hook, which is unique within its list. @hook_id: the id of this hook, which is unique within its list
@flags: flags which are set for this hook. See #GHookFlagMask for @flags: flags which are set for this hook. See #GHookFlagMask for
predefined flags. predefined flags
@func: the function to call when this hook is invoked. The possible @func: the function to call when this hook is invoked. The possible
signatures for this function are #GHookFunc and #GHookCheckFunc. signatures for this function are #GHookFunc and #GHookCheckFunc
@destroy: the default <function>finalize_hook</function> function of a @destroy: the default <function>finalize_hook</function> function of a
#GHookList calls this member of the hook that is being finalized. #GHookList calls this member of the hook that is being finalized
<!-- ##### USER_FUNCTION GHookFunc ##### --> <!-- ##### USER_FUNCTION GHookFunc ##### -->
<para> <para>
@ -69,7 +69,7 @@ Defines the type of a hook function that can be invoked
by g_hook_list_invoke(). by g_hook_list_invoke().
</para> </para>
@data: the data field of the #GHook is passed to the hook function here. @data: the data field of the #GHook is passed to the hook function here
<!-- ##### USER_FUNCTION GHookCheckFunc ##### --> <!-- ##### USER_FUNCTION GHookCheckFunc ##### -->
@ -78,8 +78,8 @@ Defines the type of a hook function that can be invoked
by g_hook_list_invoke_check(). by g_hook_list_invoke_check().
</para> </para>
@data: the data field of the #GHook is passed to the hook function here. @data: the data field of the #GHook is passed to the hook function here
@Returns: %FALSE if the #GHook should be destroyed. @Returns: %FALSE if the #GHook should be destroyed
<!-- ##### FUNCTION g_hook_list_init ##### --> <!-- ##### FUNCTION g_hook_list_init ##### -->
@ -88,9 +88,9 @@ Initializes a #GHookList.
This must be called before the #GHookList is used. This must be called before the #GHookList is used.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@hook_size: the size of each element in the #GHookList, typically @hook_size: the size of each element in the #GHookList, typically
<literal>sizeof (GHook)</literal>. <literal>sizeof (GHook)</literal>
<!-- ##### FUNCTION g_hook_list_invoke ##### --> <!-- ##### FUNCTION g_hook_list_invoke ##### -->
@ -98,9 +98,9 @@ This must be called before the #GHookList is used.
Calls all of the #GHook functions in a #GHookList. Calls all of the #GHook functions in a #GHookList.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@may_recurse: %TRUE if functions which are already running (e.g. in another @may_recurse: %TRUE if functions which are already running (e.g. in another
thread) can be called. If set to %FALSE, these are skipped. thread) can be called. If set to %FALSE, these are skipped
<!-- ##### FUNCTION g_hook_list_invoke_check ##### --> <!-- ##### FUNCTION g_hook_list_invoke_check ##### -->
@ -109,9 +109,9 @@ Calls all of the #GHook functions in a #GHookList.
Any function which returns %TRUE is removed from the #GHookList. Any function which returns %TRUE is removed from the #GHookList.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@may_recurse: %TRUE if functions which are already running (e.g. in another @may_recurse: %TRUE if functions which are already running (e.g. in another
thread) can be called. If set to %FALSE, these are skipped. thread) can be called. If set to %FALSE, these are skipped
<!-- ##### FUNCTION g_hook_list_marshal ##### --> <!-- ##### FUNCTION g_hook_list_marshal ##### -->
@ -119,11 +119,11 @@ thread) can be called. If set to %FALSE, these are skipped.
Calls a function on each valid #GHook. Calls a function on each valid #GHook.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@may_recurse: %TRUE if hooks which are currently running (e.g. in another @may_recurse: %TRUE if hooks which are currently running (e.g. in another
thread) are considered valid. If set to %FALSE, these are skipped. thread) are considered valid. If set to %FALSE, these are skipped
@marshaller: the function to call for each #GHook. @marshaller: the function to call for each #GHook
@marshal_data: data to pass to @marshaller. @marshal_data: data to pass to @marshaller
<!-- ##### USER_FUNCTION GHookMarshaller ##### --> <!-- ##### USER_FUNCTION GHookMarshaller ##### -->
@ -131,8 +131,8 @@ thread) are considered valid. If set to %FALSE, these are skipped.
Defines the type of function used by g_hook_list_marshal(). Defines the type of function used by g_hook_list_marshal().
</para> </para>
@hook: a #GHook. @hook: a #GHook
@marshal_data: user data. @marshal_data: user data
<!-- ##### FUNCTION g_hook_list_marshal_check ##### --> <!-- ##### FUNCTION g_hook_list_marshal_check ##### -->
@ -141,11 +141,11 @@ Calls a function on each valid #GHook and destroys it if the
function returns %FALSE. function returns %FALSE.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@may_recurse: %TRUE if hooks which are currently running (e.g. in another @may_recurse: %TRUE if hooks which are currently running (e.g. in another
thread) are considered valid. If set to %FALSE, these are skipped. thread) are considered valid. If set to %FALSE, these are skipped
@marshaller: the function to call for each #GHook. @marshaller: the function to call for each #GHook
@marshal_data: data to pass to @marshaller. @marshal_data: data to pass to @marshaller
<!-- ##### USER_FUNCTION GHookCheckMarshaller ##### --> <!-- ##### USER_FUNCTION GHookCheckMarshaller ##### -->
@ -153,9 +153,9 @@ thread) are considered valid. If set to %FALSE, these are skipped.
Defines the type of function used by g_hook_list_marshal_check(). Defines the type of function used by g_hook_list_marshal_check().
</para> </para>
@hook: a #GHook. @hook: a #GHook
@marshal_data: user data. @marshal_data: user data
@Returns: %FALSE if @hook should be destroyed. @Returns: %FALSE if @hook should be destroyed
<!-- ##### FUNCTION g_hook_list_clear ##### --> <!-- ##### FUNCTION g_hook_list_clear ##### -->
@ -163,7 +163,7 @@ Defines the type of function used by g_hook_list_marshal_check().
Removes all the #GHook elements from a #GHookList. Removes all the #GHook elements from a #GHookList.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
<!-- ##### FUNCTION g_hook_alloc ##### --> <!-- ##### FUNCTION g_hook_alloc ##### -->
@ -171,8 +171,8 @@ Removes all the #GHook elements from a #GHookList.
Allocates space for a #GHook and initializes it. Allocates space for a #GHook and initializes it.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@Returns: a new #GHook. @Returns: a new #GHook
<!-- ##### MACRO g_hook_append ##### --> <!-- ##### MACRO g_hook_append ##### -->
@ -180,8 +180,8 @@ Allocates space for a #GHook and initializes it.
Appends a #GHook onto the end of a #GHookList. Appends a #GHook onto the end of a #GHookList.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@hook: the #GHook to add to the end of @hook_list. @hook: the #GHook to add to the end of @hook_list
<!-- ##### FUNCTION g_hook_prepend ##### --> <!-- ##### FUNCTION g_hook_prepend ##### -->
@ -189,8 +189,8 @@ Appends a #GHook onto the end of a #GHookList.
Prepends a #GHook on the start of a #GHookList. Prepends a #GHook on the start of a #GHookList.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@hook: the #GHook to add to the start of @hook_list. @hook: the #GHook to add to the start of @hook_list
<!-- ##### FUNCTION g_hook_insert_before ##### --> <!-- ##### FUNCTION g_hook_insert_before ##### -->
@ -198,9 +198,9 @@ Prepends a #GHook on the start of a #GHookList.
Inserts a #GHook into a #GHookList, before a given #GHook. Inserts a #GHook into a #GHookList, before a given #GHook.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@sibling: the #GHook to insert the new #GHook before. @sibling: the #GHook to insert the new #GHook before
@hook: the #GHook to insert. @hook: the #GHook to insert
<!-- ##### FUNCTION g_hook_insert_sorted ##### --> <!-- ##### FUNCTION g_hook_insert_sorted ##### -->
@ -208,9 +208,9 @@ Inserts a #GHook into a #GHookList, before a given #GHook.
Inserts a #GHook into a #GHookList, sorted by the given function. Inserts a #GHook into a #GHookList, sorted by the given function.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@hook: the #GHook to insert. @hook: the #GHook to insert
@func: the comparison function used to sort the #GHook elements. @func: the comparison function used to sort the #GHook elements
<!-- ##### USER_FUNCTION GHookCompareFunc ##### --> <!-- ##### USER_FUNCTION GHookCompareFunc ##### -->
@ -219,9 +219,9 @@ Defines the type of function used to compare #GHook elements in
g_hook_insert_sorted(). g_hook_insert_sorted().
</para> </para>
@new_hook: the #GHook being inserted. @new_hook: the #GHook being inserted
@sibling: the #GHook to compare with @new_hook. @sibling: the #GHook to compare with @new_hook
@Returns: a value &lt;= 0 if @new_hook should be before @sibling. @Returns: a value &lt;= 0 if @new_hook should be before @sibling
<!-- ##### FUNCTION g_hook_compare_ids ##### --> <!-- ##### FUNCTION g_hook_compare_ids ##### -->
@ -230,9 +230,9 @@ Compares the ids of two #GHook elements, returning a negative value
if the second id is greater than the first. if the second id is greater than the first.
</para> </para>
@new_hook: a #GHook. @new_hook: a #GHook
@sibling: a #GHook to compare with @new_hook. @sibling: a #GHook to compare with @new_hook
@Returns: a value &lt;= 0 if the id of @sibling is >= the id of @new_hook. @Returns: a value &lt;= 0 if the id of @sibling is >= the id of @new_hook
<!-- ##### FUNCTION g_hook_get ##### --> <!-- ##### FUNCTION g_hook_get ##### -->
@ -240,9 +240,9 @@ if the second id is greater than the first.
Returns the #GHook with the given id, or %NULL if it is not found. Returns the #GHook with the given id, or %NULL if it is not found.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@hook_id: a hook id. @hook_id: a hook id
@Returns: the #GHook with the given id, or %NULL if it is not found. @Returns: the #GHook with the given id, or %NULL if it is not found
<!-- ##### FUNCTION g_hook_find ##### --> <!-- ##### FUNCTION g_hook_find ##### -->
@ -250,13 +250,13 @@ Returns the #GHook with the given id, or %NULL if it is not found.
Finds a #GHook in a #GHookList using the given function to test for a match. Finds a #GHook in a #GHookList using the given function to test for a match.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@need_valids: %TRUE if #GHook elements which have been destroyed should be @need_valids: %TRUE if #GHook elements which have been destroyed should be
skipped. skipped
@func: the function to call for each #GHook, which should return %TRUE when @func: the function to call for each #GHook, which should return %TRUE when
the #GHook has been found. the #GHook has been found
@data: the data to pass to @func. @data: the data to pass to @func
@Returns: the found #GHook or %NULL if no matching #GHook is found. @Returns: the found #GHook or %NULL if no matching #GHook is found
<!-- ##### USER_FUNCTION GHookFindFunc ##### --> <!-- ##### USER_FUNCTION GHookFindFunc ##### -->
@ -264,9 +264,9 @@ the #GHook has been found.
Defines the type of the function passed to g_hook_find(). Defines the type of the function passed to g_hook_find().
</para> </para>
@hook: a #GHook. @hook: a #GHook
@data: user data passed to g_hook_find_func(). @data: user data passed to g_hook_find_func()
@Returns: %TRUE if the required #GHook has been found. @Returns: %TRUE if the required #GHook has been found
<!-- ##### FUNCTION g_hook_find_data ##### --> <!-- ##### FUNCTION g_hook_find_data ##### -->
@ -274,12 +274,12 @@ Defines the type of the function passed to g_hook_find().
Finds a #GHook in a #GHookList with the given data. Finds a #GHook in a #GHookList with the given data.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@need_valids: %TRUE if #GHook elements which have been destroyed should be @need_valids: %TRUE if #GHook elements which have been destroyed should be
skipped. skipped
@data: the data to find. @data: the data to find
@Returns: the #GHook with the given @data or %NULL if no matching @Returns: the #GHook with the given @data or %NULL if no matching
#GHook is found. #GHook is found
<!-- ##### FUNCTION g_hook_find_func ##### --> <!-- ##### FUNCTION g_hook_find_func ##### -->
@ -287,12 +287,12 @@ skipped.
Finds a #GHook in a #GHookList with the given function. Finds a #GHook in a #GHookList with the given function.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@need_valids: %TRUE if #GHook elements which have been destroyed should be @need_valids: %TRUE if #GHook elements which have been destroyed should be
skipped. skipped
@func: the function to find. @func: the function to find
@Returns: the #GHook with the given @func or %NULL if no matching @Returns: the #GHook with the given @func or %NULL if no matching
#GHook is found. #GHook is found
<!-- ##### FUNCTION g_hook_find_func_data ##### --> <!-- ##### FUNCTION g_hook_find_func_data ##### -->
@ -300,13 +300,13 @@ skipped.
Finds a #GHook in a #GHookList with the given function and data. Finds a #GHook in a #GHookList with the given function and data.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@need_valids: %TRUE if #GHook elements which have been destroyed should be @need_valids: %TRUE if #GHook elements which have been destroyed should be
skipped. skipped
@func: the function to find. @func: the function to find
@data: the data to find. @data: the data to find
@Returns: the #GHook with the given @func and @data or %NULL if no matching @Returns: the #GHook with the given @func and @data or %NULL if no matching
#GHook is found. #GHook is found
<!-- ##### FUNCTION g_hook_first_valid ##### --> <!-- ##### FUNCTION g_hook_first_valid ##### -->
@ -317,10 +317,10 @@ g_hook_unref() to restore it when no longer needed. (Or call
g_hook_next_valid() if you are stepping through the #GHookList.) g_hook_next_valid() if you are stepping through the #GHookList.)
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@may_be_in_call: %TRUE if hooks which are currently running (e.g. in another @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. thread) are considered valid. If set to %FALSE, these are skipped
@Returns: the first valid #GHook, or %NULL if none are valid. @Returns: the first valid #GHook, or %NULL if none are valid
<!-- ##### FUNCTION g_hook_next_valid ##### --> <!-- ##### FUNCTION g_hook_next_valid ##### -->
@ -332,11 +332,11 @@ g_hook_next_valid() until %NULL is returned.)
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@hook: the current #GHook. @hook: the current #GHook
@may_be_in_call: %TRUE if hooks which are currently running (e.g. in another @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. thread) are considered valid. If set to %FALSE, these are skipped
@Returns: the next valid #GHook, or %NULL if none are valid. @Returns: the next valid #GHook, or %NULL if none are valid
<!-- ##### ENUM GHookFlagMask ##### --> <!-- ##### ENUM GHookFlagMask ##### -->
@ -344,8 +344,8 @@ thread) are considered valid. If set to %FALSE, these are skipped.
Flags used internally in the #GHook implementation. Flags used internally in the #GHook implementation.
</para> </para>
@G_HOOK_FLAG_ACTIVE: set if the hook has not been destroyed. @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_IN_CALL: set if the hook is currently being run
@G_HOOK_FLAG_MASK: A mask covering all bits reserved for @G_HOOK_FLAG_MASK: A mask covering all bits reserved for
hook flags; see #G_HOOK_FLAGS_USER_SHIFT hook flags; see #G_HOOK_FLAGS_USER_SHIFT
@ -354,7 +354,7 @@ Flags used internally in the #GHook implementation.
Returns the flags of a hook. Returns the flags of a hook.
</para> </para>
@hook: a #GHook. @hook: a #GHook
<!-- ##### MACRO G_HOOK_FLAG_USER_SHIFT ##### --> <!-- ##### MACRO G_HOOK_FLAG_USER_SHIFT ##### -->
@ -372,7 +372,7 @@ which can be used for application-defined flags.
Casts a pointer to a <literal>GHook*</literal>. Casts a pointer to a <literal>GHook*</literal>.
</para> </para>
@hook: a pointer. @hook: a pointer
<!-- ##### MACRO G_HOOK_IS_VALID ##### --> <!-- ##### MACRO G_HOOK_IS_VALID ##### -->
@ -381,8 +381,8 @@ Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList, it is active
and it has not been destroyed. and it has not been destroyed.
</para> </para>
@hook: a #GHook. @hook: a #GHook
@Returns: %TRUE if the #GHook is valid. @Returns: %TRUE if the #GHook is valid
<!-- ##### MACRO G_HOOK_ACTIVE ##### --> <!-- ##### MACRO G_HOOK_ACTIVE ##### -->
@ -391,8 +391,8 @@ Returns %TRUE if the #GHook is active, which is normally %TRUE until the #GHook
is destroyed. is destroyed.
</para> </para>
@hook: a #GHook. @hook: a #GHook
@Returns: %TRUE if the #GHook is active. @Returns: %TRUE if the #GHook is active
<!-- ##### MACRO G_HOOK_IN_CALL ##### --> <!-- ##### MACRO G_HOOK_IN_CALL ##### -->
@ -400,8 +400,8 @@ is destroyed.
Returns %TRUE if the #GHook function is currently executing. Returns %TRUE if the #GHook function is currently executing.
</para> </para>
@hook: a #GHook. @hook: a #GHook
@Returns: %TRUE if the #GHook function is currently executing. @Returns: %TRUE if the #GHook function is currently executing
<!-- ##### MACRO G_HOOK_IS_UNLINKED ##### --> <!-- ##### MACRO G_HOOK_IS_UNLINKED ##### -->
@ -410,8 +410,8 @@ Returns %TRUE if the #GHook is not in a #GHookList.
</para> </para>
@hook: a #GHook. @hook: a #GHook
@Returns: %TRUE if the #GHook is not in a #GHookList. @Returns: %TRUE if the #GHook is not in a #GHookList
<!-- ##### FUNCTION g_hook_ref ##### --> <!-- ##### FUNCTION g_hook_ref ##### -->
@ -419,8 +419,8 @@ Returns %TRUE if the #GHook is not in a #GHookList.
Increments the reference count for a #GHook. Increments the reference count for a #GHook.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@hook: the #GHook to increment the reference count of. @hook: the #GHook to increment the reference count of
@Returns: the @hook that was passed in (since 2.6) @Returns: the @hook that was passed in (since 2.6)
@ -431,18 +431,18 @@ If the reference count falls to 0, the #GHook is removed from the #GHookList
and g_hook_free() is called to free it. and g_hook_free() is called to free it.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@hook: the #GHook to unref. @hook: the #GHook to unref
<!-- ##### FUNCTION g_hook_free ##### --> <!-- ##### FUNCTION g_hook_free ##### -->
<para> <para>
Calls the #GHookList @hook_free function if it exists, and frees the memory Calls the #GHookList @finalize_hook function if it exists, and frees the memory
allocated for the #GHook. allocated for the #GHook.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@hook: the #GHook to free. @hook: the #GHook to free
<!-- ##### FUNCTION g_hook_destroy ##### --> <!-- ##### FUNCTION g_hook_destroy ##### -->
@ -450,9 +450,9 @@ allocated for the #GHook.
Destroys a #GHook, given its ID. Destroys a #GHook, given its ID.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@hook_id: a hook ID. @hook_id: a hook ID
@Returns: %TRUE if the #GHook was found in the #GHookList and destroyed. @Returns: %TRUE if the #GHook was found in the #GHookList and destroyed
<!-- ##### FUNCTION g_hook_destroy_link ##### --> <!-- ##### FUNCTION g_hook_destroy_link ##### -->
@ -461,7 +461,7 @@ Removes one #GHook from a #GHookList, marking it inactive and calling
g_hook_unref() on it. g_hook_unref() on it.
</para> </para>
@hook_list: a #GHookList. @hook_list: a #GHookList
@hook: the #GHook to remove. @hook: the #GHook to remove