mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-25 15:06:14 +01:00
More markup fixes and completions.
* glib/tmpl/iochannels.sgml, glib/tmpl/shell.sgml, glib/tmpl/spawn.sgml, glib/tmpl/memory.sgml, glib/tmpl/macros.sgml, glib/tmpl/completion.sgml, glib/tmpl/main.sgml, glib/tmpl/messages.sgml, glib/tmpl/misc_utils.sgml, glib/tmpl/threads.sgml, glib/tmpl/trees-nary.sgml, glib/tmpl/string_utils.sgml: More markup fixes and completions.
This commit is contained in:
Matthias Clasen
parent
5c75cc9617
commit
e9d05783f6
@ -1,3 +1,13 @@
|
||||
2001-10-01 Matthias Clasen <matthiasc@poet.de>
|
||||
|
||||
* glib/tmpl/iochannels.sgml, glib/tmpl/shell.sgml,
|
||||
glib/tmpl/spawn.sgml, glib/tmpl/memory.sgml,
|
||||
glib/tmpl/macros.sgml, glib/tmpl/completion.sgml,
|
||||
glib/tmpl/main.sgml, glib/tmpl/messages.sgml,
|
||||
glib/tmpl/misc_utils.sgml, glib/tmpl/threads.sgml,
|
||||
glib/tmpl/trees-nary.sgml, glib/tmpl/string_utils.sgml:
|
||||
More markup fixes and completions.
|
||||
|
||||
Mon Oct 1 15:59:46 2001 Owen Taylor <otaylor@redhat.com>
|
||||
|
||||
* glib/tmpl/strings.sgml docs/glib-sections.txt: Rename
|
||||
|
||||
@ -38,7 +38,7 @@ The data structure used for automatic completion.
|
||||
<structfield>items</structfield> is the list of target items (strings
|
||||
or data structures).
|
||||
<structfield>func</structfield> is the function called to get the string
|
||||
associated with a target item. It is NULL if the target items are strings.
|
||||
associated with a target item. It is %NULL if the target items are strings.
|
||||
<structfield>prefix</structfield> is the last prefix passed to
|
||||
g_completion_complete().
|
||||
<structfield>cache</structfield> is the list of items which begin with
|
||||
|
||||
@ -276,32 +276,34 @@ operation.
|
||||
|
||||
<!-- ##### ENUM GIOStatus ##### -->
|
||||
<para>
|
||||
|
||||
Stati returned by most of the #GIOFuncs functions.
|
||||
</para>
|
||||
|
||||
@G_IO_STATUS_ERROR:
|
||||
@G_IO_STATUS_NORMAL:
|
||||
@G_IO_STATUS_EOF:
|
||||
@G_IO_STATUS_AGAIN:
|
||||
@G_IO_STATUS_ERROR: An error occurred.
|
||||
@G_IO_STATUS_NORMAL: Success.
|
||||
@G_IO_STATUS_EOF: End of file.
|
||||
@G_IO_STATUS_AGAIN: Resource temporarily unavailable.
|
||||
|
||||
<!-- ##### ENUM GIOChannelError ##### -->
|
||||
<para>
|
||||
|
||||
Error codes returned by #GIOChannel operations.
|
||||
</para>
|
||||
|
||||
@G_IO_CHANNEL_ERROR_FBIG:
|
||||
@G_IO_CHANNEL_ERROR_INVAL:
|
||||
@G_IO_CHANNEL_ERROR_IO:
|
||||
@G_IO_CHANNEL_ERROR_ISDIR:
|
||||
@G_IO_CHANNEL_ERROR_NOSPC:
|
||||
@G_IO_CHANNEL_ERROR_NXIO:
|
||||
@G_IO_CHANNEL_ERROR_FBIG: File too large.
|
||||
@G_IO_CHANNEL_ERROR_INVAL: Invalid argument.
|
||||
@G_IO_CHANNEL_ERROR_IO: IO error.
|
||||
@G_IO_CHANNEL_ERROR_ISDIR: File is a directory.
|
||||
@G_IO_CHANNEL_ERROR_NOSPC: No space left on device.
|
||||
@G_IO_CHANNEL_ERROR_NXIO: No such device or address.
|
||||
@G_IO_CHANNEL_ERROR_OVERFLOW:
|
||||
@G_IO_CHANNEL_ERROR_PIPE:
|
||||
@G_IO_CHANNEL_ERROR_FAILED:
|
||||
@G_IO_CHANNEL_ERROR_PIPE: Broken pipe.
|
||||
@G_IO_CHANNEL_ERROR_FAILED: Some other error.
|
||||
|
||||
<!-- ##### MACRO G_IO_CHANNEL_ERROR ##### -->
|
||||
<para>
|
||||
|
||||
Error domain for #GIOChannel operations. Errors in this domain will
|
||||
be from the #IOChannelError enumeration. See #GError for information on
|
||||
error domains.
|
||||
</para>
|
||||
|
||||
|
||||
@ -444,7 +446,7 @@ g_io_add_watch_full(), which is called when the requested condition on a
|
||||
@source: the #GIOChannel event source.
|
||||
@condition: the condition which has been satisfied.
|
||||
@data: user data set in g_io_add_watch() or g_io_add_watch_full().
|
||||
@Returns: the function should return FALSE if the event source should be
|
||||
@Returns: the function should return %FALSE if the event source should be
|
||||
removed.
|
||||
|
||||
|
||||
|
||||
@ -62,7 +62,7 @@ UNIX-specific code in "#ifdef G_OS_UNIX".
|
||||
<!-- ##### MACRO GLIB_CHECK_VERSION ##### -->
|
||||
<para>
|
||||
Checks the version of the GLib library.
|
||||
It returns TRUE if the GLib library is the same or newer than the given
|
||||
It returns %TRUE if the GLib library is the same or newer than the given
|
||||
version.
|
||||
|
||||
<example>
|
||||
|
||||
@ -176,8 +176,8 @@ Creates a new #GMainLoop for the default main loop. A compatibility
|
||||
macro, see g_main_loop_new().
|
||||
</para>
|
||||
|
||||
@is_running: set to TRUE to indicate that the loop is running. This is not
|
||||
very important since calling g_main_run() will set this to TRUE anyway.
|
||||
@is_running: set to %TRUE to indicate that the loop is running. This is not
|
||||
very important since calling g_main_run() will set this to %TRUE anyway.
|
||||
@Returns: a new #GMainLoop.
|
||||
|
||||
|
||||
@ -316,11 +316,11 @@ Runs a single iteration for the default #GMainContext.
|
||||
A compatibility macro, see g_main_context_iteration().
|
||||
</para>
|
||||
|
||||
@may_block: set to TRUE if it should block (i.e. wait) until an event source
|
||||
@may_block: set to %TRUE if it should block (i.e. wait) until an event source
|
||||
becomes ready. It will return after an event source has been processed.
|
||||
If set to FALSE it will return immediately if no event source is ready to be
|
||||
If set to %FALSE it will return immediately if no event source is ready to be
|
||||
processed.
|
||||
@Returns: TRUE if more events are pending.
|
||||
@Returns: %TRUE if more events are pending.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_main_context_pending ##### -->
|
||||
@ -573,8 +573,6 @@ g_main_context_set_poll_func() for full details.
|
||||
@data:
|
||||
@notify:
|
||||
@Returns:
|
||||
<!-- # Unused Parameters # -->
|
||||
@destroy:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_idle_remove_by_data ##### -->
|
||||
@ -609,7 +607,7 @@ you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use
|
||||
<row>
|
||||
<entry>#gushort revents;</entry>
|
||||
<entry>a bitwise combination of flags from #GIOCondition, returned from the
|
||||
poll() function to indicate which events occurred.
|
||||
<function>poll()</function> function to indicate which events occurred.
|
||||
</entry>
|
||||
</row>
|
||||
</tbody></tgroup></informaltable>
|
||||
@ -680,25 +678,26 @@ Called when the source is destroyed.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For idle sources, the prepare and check functions always return TRUE to
|
||||
For idle sources, the prepare and check functions always return %TRUE to
|
||||
indicate that the source is always ready to be processed.
|
||||
The prepare function also returns a timeout value of 0 to ensure that the
|
||||
poll() call doesn't block (since that would be time wasted which could have
|
||||
been spent running the idle function).
|
||||
<function>poll()</function> call doesn't block (since that would be time
|
||||
wasted which could have been spent running the idle function).
|
||||
</para>
|
||||
<para>
|
||||
For timeout sources, the prepare and check functions both return TRUE if the
|
||||
timeout interval has expired.
|
||||
The prepare function also returns a timeout value to ensure that the poll()
|
||||
call doesn't block too long and miss the next timeout.
|
||||
For timeout sources, the prepare and check functions both return %TRUE if the
|
||||
timeout interval has expired. The prepare function also returns a timeout
|
||||
value to ensure that the <function>poll()</function> call doesn't block too
|
||||
long and miss the next timeout.
|
||||
</para>
|
||||
<para>
|
||||
For file descriptor sources, the prepare function typically returns FALSE,
|
||||
since it must wait until poll() has been called before it knows whether any
|
||||
events need to be processed. It sets the returned timeout to -1 to indicate
|
||||
that it doesn't mind how long the poll() call blocks.
|
||||
In the check function, it tests the results of the poll() call to see if
|
||||
the required condition has been met, and returns TRUE if so.
|
||||
For file descriptor sources, the prepare function typically returns %FALSE,
|
||||
since it must wait until <function>poll()</function> has been called before
|
||||
it knows whether any events need to be processed. It sets the returned
|
||||
timeout to -1 to indicate that it doesn't mind how long the
|
||||
<function>poll()</function> call blocks.
|
||||
In the check function, it tests the results of the <function>poll()</function>
|
||||
call to see if the required condition has been met, and returns %TRUE if so.
|
||||
</para>
|
||||
|
||||
@prepare:
|
||||
@ -842,7 +841,7 @@ g_idle_add(), and g_idle_add_full().
|
||||
|
||||
@data: data passed to the function, set when the source was created with one
|
||||
of the above functions.
|
||||
@Returns: it should return FALSE if the source should be removed.
|
||||
@Returns: it should return %FALSE if the source should be removed.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_source_set_callback_indirect ##### -->
|
||||
|
||||
@ -154,7 +154,7 @@ from @mem. If @mem is %NULL it returns %NULL.
|
||||
|
||||
@mem: the memory to copy.
|
||||
@byte_size: the number of bytes to copy.
|
||||
@Returns: a pointer to the newly allocated copy of the memory, or %NULL if @mem
|
||||
@Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
|
||||
is %NULL.
|
||||
|
||||
|
||||
|
||||
@ -23,7 +23,7 @@ These can be extended with user-defined levels.
|
||||
<!-- ##### MACRO G_LOG_DOMAIN ##### -->
|
||||
<para>
|
||||
Defines the log domain.
|
||||
For applications, this is typically left as the default NULL (or "") domain.
|
||||
For applications, this is typically left as the default %NULL (or "") domain.
|
||||
Libraries should define this so that any messages which they log can
|
||||
be differentiated from messages from other libraries and application code.
|
||||
But be careful not to define it in any public header files.
|
||||
@ -181,10 +181,10 @@ to set a handler for this log level you must combine it with G_LOG_FLAG_FATAL.
|
||||
</programlisting>
|
||||
</example>
|
||||
|
||||
@log_domain: the log domain, or NULL for the default "" application domain.
|
||||
@log_domain: the log domain, or %NULL for the default "" application domain.
|
||||
@log_levels: the log levels to apply the log handler for. To handle fatal
|
||||
and recursive messages as well, combine the log levels with the
|
||||
G_LOG_FLAG_FATAL and G_LOG_FLAG_RECURSIVE bit flags.
|
||||
#G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSIVE bit flags.
|
||||
@log_func: the log handler function.
|
||||
@user_data: data passed to the log handler.
|
||||
@Returns: the id of the new handler.
|
||||
|
||||
@ -127,7 +127,7 @@ or 'C:/windows' on windows systems.
|
||||
</para>
|
||||
|
||||
@file_name: a file name.
|
||||
@Returns: TRUE if @file_name is an absolute path.
|
||||
@Returns: %TRUE if @file_name is an absolute path.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_path_skip_root ##### -->
|
||||
|
||||
@ -16,16 +16,18 @@ Shell-related Utilities
|
||||
|
||||
<!-- ##### ENUM GShellError ##### -->
|
||||
<para>
|
||||
|
||||
Error codes returned by shell functions.
|
||||
</para>
|
||||
|
||||
@G_SHELL_ERROR_BAD_QUOTING:
|
||||
@G_SHELL_ERROR_EMPTY_STRING:
|
||||
@G_SHELL_ERROR_FAILED:
|
||||
@G_SHELL_ERROR_BAD_QUOTING: Mismatched or otherwise mangled quoting.
|
||||
@G_SHELL_ERROR_EMPTY_STRING: String to be parsed was empty.
|
||||
@G_SHELL_ERROR_FAILED: Some other error.
|
||||
|
||||
<!-- ##### MACRO G_SHELL_ERROR ##### -->
|
||||
<para>
|
||||
|
||||
Error domain for shell functions. Errors in this domain will
|
||||
be from the #GShellError enumeration. See #GError for information on
|
||||
error domains.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
@ -16,33 +16,35 @@ Spawning Processes (fork/exec)
|
||||
|
||||
<!-- ##### ENUM GSpawnError ##### -->
|
||||
<para>
|
||||
|
||||
Error codes returned by spawning processes.
|
||||
</para>
|
||||
|
||||
@G_SPAWN_ERROR_FORK:
|
||||
@G_SPAWN_ERROR_READ:
|
||||
@G_SPAWN_ERROR_CHDIR:
|
||||
@G_SPAWN_ERROR_ACCES:
|
||||
@G_SPAWN_ERROR_PERM:
|
||||
@G_SPAWN_ERROR_2BIG:
|
||||
@G_SPAWN_ERROR_NOEXEC:
|
||||
@G_SPAWN_ERROR_NAMETOOLONG:
|
||||
@G_SPAWN_ERROR_NOENT:
|
||||
@G_SPAWN_ERROR_NOMEM:
|
||||
@G_SPAWN_ERROR_NOTDIR:
|
||||
@G_SPAWN_ERROR_LOOP:
|
||||
@G_SPAWN_ERROR_TXTBUSY:
|
||||
@G_SPAWN_ERROR_IO:
|
||||
@G_SPAWN_ERROR_NFILE:
|
||||
@G_SPAWN_ERROR_MFILE:
|
||||
@G_SPAWN_ERROR_INVAL:
|
||||
@G_SPAWN_ERROR_ISDIR:
|
||||
@G_SPAWN_ERROR_LIBBAD:
|
||||
@G_SPAWN_ERROR_FAILED:
|
||||
@G_SPAWN_ERROR_FORK: Fork failed due to lack of memory.
|
||||
@G_SPAWN_ERROR_READ: Read or select on pipes failed.
|
||||
@G_SPAWN_ERROR_CHDIR: Changing to working directory failed.
|
||||
@G_SPAWN_ERROR_ACCES: <function>execv()</function> returned %EACCES.
|
||||
@G_SPAWN_ERROR_PERM: <function>execv()</function> returned %EPERM.
|
||||
@G_SPAWN_ERROR_2BIG: <function>execv()</function> returned %E2BIG.
|
||||
@G_SPAWN_ERROR_NOEXEC: <function>execv()</function> returned %ENOEXEC.
|
||||
@G_SPAWN_ERROR_NAMETOOLONG: <function>execv()</function> returned %ENAMETOOLONG.
|
||||
@G_SPAWN_ERROR_NOENT: <function>execv()</function> returned %ENOENT.
|
||||
@G_SPAWN_ERROR_NOMEM: <function>execv()</function> returned %ENOMEM.
|
||||
@G_SPAWN_ERROR_NOTDIR: <function>execv()</function> returned %ENOTDIR.
|
||||
@G_SPAWN_ERROR_LOOP: <function>execv()</function> returned %ELOOP.
|
||||
@G_SPAWN_ERROR_TXTBUSY: <function>execv()</function> returned %ETXTBUSY.
|
||||
@G_SPAWN_ERROR_IO: <function>execv()</function> returned %EIO.
|
||||
@G_SPAWN_ERROR_NFILE: <function>execv()</function> returned %ENFILE.
|
||||
@G_SPAWN_ERROR_MFILE: <function>execv()</function> returned %EMFILE.
|
||||
@G_SPAWN_ERROR_INVAL: <function>execv()</function> returned %EINVAL.
|
||||
@G_SPAWN_ERROR_ISDIR: <function>execv()</function> returned %EISDIR.
|
||||
@G_SPAWN_ERROR_LIBBAD: <function>execv()</function> returned %ELIBBAD.
|
||||
@G_SPAWN_ERROR_FAILED: Some other fatal failure, <literal>error->message</literal> should explain.
|
||||
|
||||
<!-- ##### MACRO G_SPAWN_ERROR ##### -->
|
||||
<para>
|
||||
|
||||
Error domain for spawning processes. Errors in this domain will
|
||||
be from the #GSpawnError enumeration. See #GError for information on
|
||||
error domains.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
@ -28,15 +28,15 @@ The returned string should be freed when no longer needed.
|
||||
<!-- ##### FUNCTION g_strndup ##### -->
|
||||
<para>
|
||||
Duplicates the first @n characters of a string, returning a newly-allocated
|
||||
buffer @n + 1 characters long which will always be null-terminated.
|
||||
If @str is less than @n characters long the buffer is padded with nulls.
|
||||
buffer @n + 1 characters long which will always be nul-terminated.
|
||||
If @str is less than @n characters long the buffer is padded with nuls.
|
||||
The returned value should be freed when no longer needed.
|
||||
</para>
|
||||
|
||||
@str: the string to duplicate part of.
|
||||
@n: the maximum number of characters to copy from @str.
|
||||
@Returns: a newly-allocated buffer containing the first @n characters of @str,
|
||||
null-terminated.
|
||||
nul-terminated.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_strdupv ##### -->
|
||||
@ -165,7 +165,7 @@ The returned string should be freed when no longer needed.
|
||||
<para>
|
||||
A safer form of the standard <function>sprintf()</function> function.
|
||||
The output is guaranteed to not exceed @n characters (including the
|
||||
terminating NULL character), so it is easy to ensure that a buffer overflow
|
||||
terminating nul character), so it is easy to ensure that a buffer overflow
|
||||
cannot occur.
|
||||
</para>
|
||||
<para>
|
||||
@ -174,7 +174,7 @@ See also g_strdup_printf().
|
||||
<note>
|
||||
<para>
|
||||
In versions of GLib prior to 1.2.3, this function may return -1 if the output
|
||||
was truncated, and the truncated string may not be NULL-terminated.
|
||||
was truncated, and the truncated string may not be nul-terminated.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@ -191,7 +191,7 @@ documentation.
|
||||
<para>
|
||||
A safer form of the standard <function>vsprintf()</function> function.
|
||||
The output is guaranteed to not exceed @n characters (including the
|
||||
terminating NULL character), so it is easy to ensure that a buffer overflow
|
||||
terminating nul character), so it is easy to ensure that a buffer overflow
|
||||
cannot occur.
|
||||
</para>
|
||||
<para>
|
||||
@ -200,7 +200,7 @@ See also g_strdup_vprintf().
|
||||
<note>
|
||||
<para>
|
||||
In versions of GLib prior to 1.2.3, this function may return -1 if the output
|
||||
was truncated, and the truncated string may not be NULL-terminated.
|
||||
was truncated, and the truncated string may not be nul-terminated.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@ -612,7 +612,7 @@ to the @new_delimiter character.
|
||||
</para>
|
||||
|
||||
@string: the string to convert.
|
||||
@delimiters: a string containing the current delimiters, or NULL to use the
|
||||
@delimiters: a string containing the current delimiters, or %NULL to use the
|
||||
standard delimiters defined in #G_STR_DELIMITERS.
|
||||
@new_delimiter: the new delimiter character.
|
||||
@Returns:
|
||||
@ -641,7 +641,7 @@ g_strcompress() does the reverse conversion.
|
||||
|
||||
@source: a string to escape.
|
||||
@exceptions: a string of characters not to escape in @source.
|
||||
@Returns: a newly allocated copy of @source with certain
|
||||
@Returns: a newly-allocated copy of @source with certain
|
||||
characters escaped. See above.
|
||||
|
||||
|
||||
@ -652,7 +652,7 @@ does the reverse conversion of g_strescape().
|
||||
</para>
|
||||
|
||||
@source: a string to compress.
|
||||
@Returns: a newly allocated copy of @source with all escaped
|
||||
@Returns: a newly-allocated copy of @source with all escaped
|
||||
character compressed.
|
||||
|
||||
|
||||
@ -661,13 +661,13 @@ character compressed.
|
||||
For each character in @string, if the character is not in @valid_chars,
|
||||
replaces the character with @substitutor. Modifies @string in place,
|
||||
and return @string itself, not a copy. The return value is to allow
|
||||
nesting such as g_strup (g_strcanon (str)).
|
||||
nesting such as <literal>g_strup (g_strcanon (str))</literal>.
|
||||
</para>
|
||||
|
||||
@string: a nul-terminated array of bytes
|
||||
@valid_chars: bytes permitted in @string
|
||||
@substitutor: replacement character for disallowed bytes
|
||||
@Returns: @string
|
||||
@string: a nul-terminated array of bytes.
|
||||
@valid_chars: bytes permitted in @string.
|
||||
@substitutor: replacement character for disallowed bytes.
|
||||
@Returns: @string.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_strsplit ##### -->
|
||||
@ -682,10 +682,10 @@ nesting such as g_strup (g_strcanon (str)).
|
||||
|
||||
<!-- ##### FUNCTION g_strfreev ##### -->
|
||||
<para>
|
||||
Frees a NULL-terminated array of strings, and the array itself.
|
||||
Frees a %NULL-terminated array of strings, and the array itself.
|
||||
</para>
|
||||
|
||||
@str_array: a NULL-terminated array of strings to free.
|
||||
@str_array: a %NULL-terminated array of strings to free.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_strconcat ##### -->
|
||||
@ -696,8 +696,8 @@ END WITH %NULL. If you forget the %NULL, g_strconcat() will start appending
|
||||
random memory junk to your string.
|
||||
</para>
|
||||
|
||||
@string1: The first string to add, which must not be NULL.
|
||||
@Varargs: a NULL-terminated list of strings to append to the string.
|
||||
@string1: The first string to add, which must not be %NULL.
|
||||
@Varargs: a %NULL-terminated list of strings to append to the string.
|
||||
@Returns: a newly-allocated string containing all the string arguments.
|
||||
|
||||
|
||||
@ -707,8 +707,8 @@ Joins a number of strings together to form one long string, with the optional
|
||||
@separator inserted between each of them.
|
||||
</para>
|
||||
|
||||
@separator: a string to insert between each of the strings, or NULL.
|
||||
@Varargs: a NULL-terminated list of strings to join.
|
||||
@separator: a string to insert between each of the strings, or %NULL.
|
||||
@Varargs: a %NULL-terminated list of strings to join.
|
||||
@Returns: a newly-allocated string containing all of the strings joined
|
||||
together, with @separator between them.
|
||||
|
||||
@ -719,8 +719,8 @@ Joins a number of strings together to form one long string, with the optional
|
||||
@separator inserted between each of them.
|
||||
</para>
|
||||
|
||||
@separator: a string to insert between each of the strings, or NULL.
|
||||
@str_array: a NULL-terminated array of strings to join.
|
||||
@separator: a string to insert between each of the strings, or %NULL.
|
||||
@str_array: a %NULL-terminated array of strings to join.
|
||||
@Returns: a newly-allocated string containing all of the strings joined
|
||||
together, with @separator between them.
|
||||
|
||||
|
||||
@ -145,13 +145,13 @@ This struct should only be used, if you know, what you are doing.
|
||||
Before you use a thread related function in GLib, you should
|
||||
initialize the thread system. This is done by calling
|
||||
g_thread_init(). Most of the time you will only have to call
|
||||
g_thread_init(NULL).
|
||||
<literal>g_thread_init(NULL)</literal>.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
You should only call g_thread_init() with a non-NULL parameter, if you
|
||||
really know, what you are doing.
|
||||
You should only call g_thread_init() with a non-%NULL parameter if you
|
||||
really know what you are doing.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@ -184,8 +184,8 @@ will abort, if no thread system is available in GLib, i.e. either
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If no thread system is available and @vtable is NULL or if not all
|
||||
elements of @vtable are non-NULL, then g_thread_init() will abort.
|
||||
If no thread system is available and @vtable is %NULL or if not all
|
||||
elements of @vtable are non-%NULL, then g_thread_init() will abort.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
@ -199,7 +199,7 @@ libraries.
|
||||
</note>
|
||||
|
||||
@vtable: a function table of type #GThreadFunctions, that provides the
|
||||
entry points to the thread system to be used
|
||||
entry points to the thread system to be used.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_thread_supported ##### -->
|
||||
@ -215,7 +215,7 @@ you can however use it as if it was a function.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@Returns: TRUE, if the thread system is initialized
|
||||
@Returns: %TRUE, if the thread system is initialized.
|
||||
|
||||
|
||||
<!-- ##### USER_FUNCTION GThreadFunc ##### -->
|
||||
@ -224,9 +224,9 @@ Specifies the type of the @func functions passed to
|
||||
g_thread_create() or g_thread_create_full().
|
||||
</para>
|
||||
|
||||
@data: data passed to the thread
|
||||
@data: data passed to the thread.
|
||||
@Returns: the return value of the thread, which will be returned by
|
||||
g_thread_join()
|
||||
g_thread_join().
|
||||
|
||||
|
||||
<!-- ##### ENUM GThreadPriority ##### -->
|
||||
@ -274,7 +274,7 @@ This function creates a new thread with the priority @priority.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If @joinable is #TRUE, you can wait for this threads termination
|
||||
If @joinable is %TRUE, you can wait for this threads termination
|
||||
calling g_thread_wait(). Otherwise the thread will just disappear, when
|
||||
ready.
|
||||
</para>
|
||||
@ -285,15 +285,15 @@ The new thread executes the function @func with the argument
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@error can be NULL to ignore errors, or non-NULL to report errors. The
|
||||
error is set, if and only if the function returns #NULL.
|
||||
@error can be %NULL to ignore errors, or non-%NULL to report errors. The
|
||||
error is set, if and only if the function returns %NULL.
|
||||
</para>
|
||||
|
||||
@func: a function to execute in the new thread
|
||||
@data: an argument to supply to the new thread
|
||||
@func: a function to execute in the new thread.
|
||||
@data: an argument to supply to the new thread.
|
||||
@joinable: should this thread be joinable?
|
||||
@error: return location for error.
|
||||
@Returns: the new #GThread on success
|
||||
@Returns: the new #GThread on success.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_thread_create_full ##### -->
|
||||
@ -304,9 +304,9 @@ platform, if @stack_size is 0.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If @joinable is #TRUE, you can wait for this threads termination
|
||||
If @joinable is %TRUE, you can wait for this threads termination
|
||||
calling g_thread_wait(). Otherwise the thread will just disappear, when
|
||||
ready. If @bound is #TRUE, this thread will be scheduled in the system
|
||||
ready. If @bound is %TRUE, this thread will be scheduled in the system
|
||||
scope, otherwise the implementation is free to do scheduling in the
|
||||
process scope. The first variant is more expensive resource-wise, but
|
||||
generally faster. On some systems (e.g. Linux) all threads are bound.
|
||||
@ -318,8 +318,8 @@ The new thread executes the function @func with the argument
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@error can be NULL to ignore errors, or non-NULL to report errors. The
|
||||
error is set, if and only if the function returns #NULL.
|
||||
@error can be %NULL to ignore errors, or non-%NULL to report errors. The
|
||||
error is set, if and only if the function returns %NULL.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
@ -342,14 +342,14 @@ used for cases, where it is inevitable.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@func: a function to execute in the new thread
|
||||
@data: an argument to supply to the new thread
|
||||
@stack_size: a stack size for the new thread
|
||||
@func: a function to execute in the new thread.
|
||||
@data: an argument to supply to the new thread.
|
||||
@stack_size: a stack size for the new thread.
|
||||
@joinable: should this thread be joinable?
|
||||
@bound: should this thread be bound to a system thread?
|
||||
@priority: a priority for the thread
|
||||
@priority: a priority for the thread.
|
||||
@error: return location for error.
|
||||
@Returns: the new #GThread on success
|
||||
@Returns: the new #GThread on success.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_thread_self ##### -->
|
||||
@ -357,7 +357,7 @@ used for cases, where it is inevitable.
|
||||
This functions returns the #GThread corresponding to the calling thread.
|
||||
</para>
|
||||
|
||||
@Returns: the current thread
|
||||
@Returns: the current thread.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_thread_join ##### -->
|
||||
@ -365,13 +365,13 @@ This functions returns the #GThread corresponding to the calling thread.
|
||||
Waits until @thread finishes, i.e. the function @func, as given
|
||||
to g_thread_create, returns or g_thread_exit() is called by
|
||||
@thread. All resources of @thread including the #GThread struct are
|
||||
released. @thread must have been created with @joinable=#TRUE in
|
||||
released. @thread must have been created with @joinable=%TRUE in
|
||||
g_thread_create(). The value returned by @func or given to
|
||||
g_thread_exit() by @thread is returned by this function.
|
||||
</para>
|
||||
|
||||
@thread: a #GThread to be waited for
|
||||
@Returns: the return value of the thread
|
||||
@thread: a #GThread to be waited for.
|
||||
@Returns: the return value of the thread.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_thread_set_priority ##### -->
|
||||
@ -389,8 +389,8 @@ being dependent on priorities.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@thread: a #GThread
|
||||
@priority: a new priority for @thread
|
||||
@thread: a #GThread.
|
||||
@priority: a new priority for @thread.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_thread_yield ##### -->
|
||||
@ -447,7 +447,7 @@ results.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@retval: the return value of this thread
|
||||
@retval: the return value of this thread.
|
||||
|
||||
|
||||
<!-- ##### STRUCT GMutex ##### -->
|
||||
@ -550,8 +550,9 @@ A #GMutex should only be accessed via the following functions.
|
||||
|
||||
<note>
|
||||
<para>
|
||||
All of the g_mutex_* functions are actually macros. Apart from taking
|
||||
the addresses of them, you can however use them as if they were functions.
|
||||
All of the <function>g_mutex_*</function> functions are actually macros.
|
||||
Apart from taking their addresses, you can however use them as if they
|
||||
were functions.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@ -568,7 +569,7 @@ This function will abort, if g_thread_init() has not been called yet.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@Returns: a new #GMutex
|
||||
@Returns: a new #GMutex.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_mutex_lock ##### -->
|
||||
@ -592,32 +593,32 @@ has locked @mutex while calling g_mutex_lock(). Use
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@mutex: a #GMutex
|
||||
@mutex: a #GMutex.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_mutex_trylock ##### -->
|
||||
|
||||
<para>
|
||||
Tries to lock @mutex. If @mutex is already locked by another
|
||||
thread, it immediately returns FALSE. Otherwise it locks @mutex
|
||||
and returns TRUE.
|
||||
thread, it immediately returns %FALSE. Otherwise it locks @mutex
|
||||
and returns %TRUE.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This function can also be used, if g_thread_init() has not yet been
|
||||
called and will immediately return TRUE then.
|
||||
called and will immediately return %TRUE then.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
#GMutex is not recursive, i.e. g_mutex_trylock() will return FALSE,
|
||||
#GMutex is not recursive, i.e. g_mutex_trylock() will return %FALSE,
|
||||
if the current thread already has locked @mutex. Use
|
||||
#GStaticRecMutex instead, if you need recursive mutexes.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@mutex: a #GMutex
|
||||
@Returns: TRUE, if @mutex could be locked
|
||||
@mutex: a #GMutex.
|
||||
@Returns: %TRUE, if @mutex could be locked.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_mutex_unlock ##### -->
|
||||
@ -632,7 +633,7 @@ This function can also be used, if g_thread_init() has not yet been
|
||||
called and will do nothing then.
|
||||
</para>
|
||||
|
||||
@mutex: a #GMutex
|
||||
@mutex: a #GMutex.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_mutex_free ##### -->
|
||||
@ -641,7 +642,7 @@ called and will do nothing then.
|
||||
Destroys @mutex.
|
||||
</para>
|
||||
|
||||
@mutex: a #GMutex
|
||||
@mutex: a #GMutex.
|
||||
|
||||
|
||||
<!-- ##### STRUCT GStaticMutex ##### -->
|
||||
@ -680,7 +681,7 @@ use g_mutex_new() and thus #GMutex, as that requires a prior call to
|
||||
g_thread_init(). In theses cases you can also use a #GStaticMutex. It
|
||||
must be initialized with g_static_mutex_init() before using it and
|
||||
freed with with g_static_mutex_free() when not needed anymore to free
|
||||
up any allocated recourses.
|
||||
up any allocated resources.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -690,15 +691,15 @@ platforms.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
All of the g_static_mutex_* functions can also be used, if
|
||||
g_thread_init() has not yet been called.
|
||||
All of the <function>g_static_mutex_*</function> functions can also be
|
||||
used, if g_thread_init() has not yet been called.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
All of the g_static_mutex_* functions are actually macros. Apart from
|
||||
taking the addresses of them, you can however use them as if they were
|
||||
functions.
|
||||
All of the <function>g_static_mutex_*</function> functions are actually
|
||||
macros. Apart from taking their addresses, you can however use them
|
||||
as if they were functions.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@ -728,7 +729,7 @@ Initializes @mutex. Alternatively you can initialize it with
|
||||
#G_STATIC_MUTEX_INIT.
|
||||
</para>
|
||||
|
||||
@mutex: a #GStaticMutex to be initialized
|
||||
@mutex: a #GStaticMutex to be initialized.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_mutex_lock ##### -->
|
||||
@ -736,7 +737,7 @@ Initializes @mutex. Alternatively you can initialize it with
|
||||
Works like g_mutex_lock(), but for a #GStaticMutex.
|
||||
</para>
|
||||
|
||||
@mutex: a #GStaticMutex
|
||||
@mutex: a #GStaticMutex.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_mutex_trylock ##### -->
|
||||
@ -745,8 +746,8 @@ Works like g_mutex_lock(), but for a #GStaticMutex.
|
||||
Works like g_mutex_trylock(), but for a #GStaticMutex.
|
||||
</para>
|
||||
|
||||
@mutex: a #GStaticMutex
|
||||
@Returns: TRUE, if the #GStaticMutex could be locked
|
||||
@mutex: a #GStaticMutex.
|
||||
@Returns: %TRUE, if the #GStaticMutex could be locked.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_mutex_unlock ##### -->
|
||||
@ -755,7 +756,7 @@ Works like g_mutex_trylock(), but for a #GStaticMutex.
|
||||
Works like g_mutex_unlock(), but for a #GStaticMutex.
|
||||
</para>
|
||||
|
||||
@mutex: a #GStaticMutex
|
||||
@mutex: a #GStaticMutex.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_mutex_get_mutex ##### -->
|
||||
@ -766,8 +767,8 @@ instead of a #GStaticMutex. This function will return the
|
||||
corresponding #GMutex for @mutex.
|
||||
</para>
|
||||
|
||||
@mutex: a #GStaticMutex
|
||||
@Returns: the #GMutex corresponding to @mutex
|
||||
@mutex: a #GStaticMutex.
|
||||
@Returns: the #GMutex corresponding to @mutex.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_mutex_free ##### -->
|
||||
@ -782,13 +783,13 @@ unbounded lifetime, i.e. objects declared 'static', but if you have a
|
||||
you should also free the #GStaticMutex.
|
||||
</para>
|
||||
|
||||
@mutex: a #GStaticMutex to be freed
|
||||
@mutex: a #GStaticMutex to be freed.
|
||||
|
||||
|
||||
<!-- ##### MACRO G_LOCK_DEFINE ##### -->
|
||||
|
||||
<para>
|
||||
The G_LOCK_* macros provide a convenient interface to #GStaticMutex
|
||||
The %G_LOCK_* macros provide a convenient interface to #GStaticMutex
|
||||
with the advantage that they will expand to nothing in programs
|
||||
compiled against a thread-disabled GLib, saving code and memory
|
||||
there. #G_LOCK_DEFINE defines a lock. It can appear, where variable
|
||||
@ -797,7 +798,7 @@ function or outside of functions. The @name parameter will be mangled
|
||||
to get the name of the #GStaticMutex. This means, that you can use
|
||||
names of existing variables as the parameter, e.g. the name of the
|
||||
variable you intent to protect with the lock. Look at our
|
||||
give_me_next_number() example using the G_LOCK_* macros:
|
||||
<function>give_me_next_number()</function> example using the %G_LOCK_* macros:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -820,7 +821,7 @@ int give_me_next_number ()
|
||||
</example>
|
||||
</para>
|
||||
|
||||
@name: the name of the lock
|
||||
@name: the name of the lock.
|
||||
|
||||
|
||||
<!-- ##### MACRO G_LOCK_DEFINE_STATIC ##### -->
|
||||
@ -829,7 +830,7 @@ int give_me_next_number ()
|
||||
This works like #G_LOCK_DEFINE, but it creates a static object.
|
||||
</para>
|
||||
|
||||
@name: the name of the lock
|
||||
@name: the name of the lock.
|
||||
|
||||
|
||||
<!-- ##### MACRO G_LOCK_EXTERN ##### -->
|
||||
@ -838,7 +839,7 @@ This works like #G_LOCK_DEFINE, but it creates a static object.
|
||||
This declares a lock, that is defined with #G_LOCK_DEFINE in another module.
|
||||
</para>
|
||||
|
||||
@name: the name of the lock
|
||||
@name: the name of the lock.
|
||||
|
||||
|
||||
<!-- ##### MACRO G_LOCK ##### -->
|
||||
@ -847,7 +848,7 @@ This declares a lock, that is defined with #G_LOCK_DEFINE in another module.
|
||||
Works like g_mutex_lock(), but for a lock defined with #G_LOCK_DEFINE.
|
||||
</para>
|
||||
|
||||
@name: the name of the lock
|
||||
@name: the name of the lock.
|
||||
|
||||
|
||||
<!-- ##### MACRO G_TRYLOCK ##### -->
|
||||
@ -856,8 +857,8 @@ Works like g_mutex_lock(), but for a lock defined with #G_LOCK_DEFINE.
|
||||
Works like g_mutex_trylock(), but for a lock defined with #G_LOCK_DEFINE.
|
||||
</para>
|
||||
|
||||
@name: the name of the lock
|
||||
@Returns: TRUE, if the lock could be locked
|
||||
@name: the name of the lock.
|
||||
@Returns: %TRUE, if the lock could be locked.
|
||||
|
||||
|
||||
<!-- ##### MACRO G_UNLOCK ##### -->
|
||||
@ -866,7 +867,7 @@ Works like g_mutex_trylock(), but for a lock defined with #G_LOCK_DEFINE.
|
||||
Works like g_mutex_unlock(), but for a lock defined with #G_LOCK_DEFINE.
|
||||
</para>
|
||||
|
||||
@name: the name of the lock
|
||||
@name: the name of the lock.
|
||||
|
||||
|
||||
<!-- ##### STRUCT GStaticRecMutex ##### -->
|
||||
@ -886,8 +887,8 @@ the following functions.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
All of the g_static_rec_mutex_* functions can also be used, if
|
||||
g_thread_init() has not been called.
|
||||
All of the <function>g_static_rec_mutex_*</function> functions can also
|
||||
be used, if g_thread_init() has not been called.
|
||||
</para>
|
||||
|
||||
@mutex:
|
||||
@ -919,7 +920,7 @@ can be used. Alternatively you can initialize it with
|
||||
#G_STATIC_REC_MUTEX_INIT.
|
||||
</para>
|
||||
|
||||
@mutex: a #GStaticRecMutex to be initialized
|
||||
@mutex: a #GStaticRecMutex to be initialized.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_rec_mutex_lock ##### -->
|
||||
@ -930,19 +931,19 @@ thread. If @mutex is already locked by the calling thread, this
|
||||
functions increases the depth of @mutex and returns immediately.
|
||||
</para>
|
||||
|
||||
@mutex: a #GStaticRecMutex to lock
|
||||
@mutex: a #GStaticRecMutex to lock.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_rec_mutex_trylock ##### -->
|
||||
<para>
|
||||
Tries to lock @mutex. If @mutex is already locked by another thread,
|
||||
it immediately returns #FALSE. Otherwise it locks @mutex and returns
|
||||
#TRUE. If @mutex is already locked by the calling thread, this
|
||||
functions increases the depth of @mutex and immediately returns #TRUE.
|
||||
it immediately returns %FALSE. Otherwise it locks @mutex and returns
|
||||
%TRUE. If @mutex is already locked by the calling thread, this
|
||||
functions increases the depth of @mutex and immediately returns %TRUE.
|
||||
</para>
|
||||
|
||||
@mutex: a #GStaticRecMutex to lock
|
||||
@Returns: TRUE, if @mutex could be locked
|
||||
@mutex: a #GStaticRecMutex to lock.
|
||||
@Returns: %TRUE, if @mutex could be locked.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_rec_mutex_unlock ##### -->
|
||||
@ -954,16 +955,16 @@ g_static_rec_mutex_lock() call for @mutex, it will be woken and can
|
||||
lock @mutex itself.
|
||||
</para>
|
||||
|
||||
@mutex: a #GStaticRecMutex to unlock
|
||||
@mutex: a #GStaticRecMutex to unlock.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_rec_mutex_lock_full ##### -->
|
||||
<para>
|
||||
Works like calling g_static_rec_mutex_lock() for @mutex n times.
|
||||
Works like calling g_static_rec_mutex_lock() for @mutex @depth times.
|
||||
</para>
|
||||
|
||||
@mutex: a #GStaticRecMutex to lock
|
||||
@depth: number of times this mutex has to be unlocked to be completely unlocked
|
||||
@mutex: a #GStaticRecMutex to lock.
|
||||
@depth: number of times this mutex has to be unlocked to be completely unlocked.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_rec_mutex_unlock_full ##### -->
|
||||
@ -977,8 +978,8 @@ g_static_rec_mutex_lock_full() with the depth returned by this
|
||||
function.
|
||||
</para>
|
||||
|
||||
@mutex: a #GStaticRecMutex to completely unlock
|
||||
@Returns: number of times @mutex has been locked by the current thread
|
||||
@mutex: a #GStaticRecMutex to completely unlock.
|
||||
@Returns: number of times @mutex has been locked by the current thread.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_rec_mutex_free ##### -->
|
||||
@ -993,7 +994,7 @@ unbounded lifetime, i.e. objects declared 'static', but if you have a
|
||||
freed, you should also free the #GStaticRecMutex.
|
||||
</para>
|
||||
|
||||
@mutex: a #GStaticRecMutex to be freed
|
||||
@mutex: a #GStaticRecMutex to be freed.
|
||||
|
||||
|
||||
<!-- ##### STRUCT GStaticRWLock ##### -->
|
||||
@ -1049,11 +1050,11 @@ example:
|
||||
|
||||
<para>
|
||||
This example shows an array, which can be accessed by many readers
|
||||
(the my_array_get function) simultaneously, whereas the writers (the
|
||||
my_array_set function) only will be allowed once a time and only if no
|
||||
readers currently access the array. This is because of the potentially
|
||||
dangerous resizing of the array. Using that functions is fully
|
||||
multi-thread safe now.
|
||||
(the <function>my_array_get()</function> function) simultaneously,
|
||||
whereas the writers (the <function>my_array_set()</function> function)
|
||||
will only be allowed once a time and only if no readers currently access
|
||||
the array. This is because of the potentially dangerous resizing of the
|
||||
array. Using these functions is fully multi-thread safe now.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -1071,8 +1072,8 @@ the following functions.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
All of the g_static_rw_lock_* functions can also be used, if
|
||||
g_thread_init() has not been called.
|
||||
All of the <function>g_static_rw_lock_*</function> functions can also be
|
||||
used, if g_thread_init() has not been called.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
@ -1121,7 +1122,7 @@ be used. Alternatively you can initialize it with
|
||||
#G_STATIC_RW_LOCK_INIT.
|
||||
</para>
|
||||
|
||||
@lock: a #GStaticRWLock to be initialized
|
||||
@lock: a #GStaticRWLock to be initialized.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_rw_lock_reader_lock ##### -->
|
||||
@ -1141,20 +1142,20 @@ recursivly lock for reading, but that can result in a deadlock as
|
||||
well, due to writer preference.
|
||||
</para>
|
||||
|
||||
@lock: a #GStaticRWLock to lock for reading
|
||||
@lock: a #GStaticRWLock to lock for reading.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_rw_lock_reader_trylock ##### -->
|
||||
<para>
|
||||
Tries to lock @lock for reading. If @lock is already locked for
|
||||
writing by another thread or if another thread is already waiting to
|
||||
lock @lock for writing, it immediately returns #FALSE. Otherwise it
|
||||
locks @lock for reading and returns TRUE. This lock has to be unlocked
|
||||
lock @lock for writing, it immediately returns %FALSE. Otherwise it
|
||||
locks @lock for reading and returns %TRUE. This lock has to be unlocked
|
||||
by g_static_rw_lock_reader_unlock().
|
||||
</para>
|
||||
|
||||
@lock: a #GStaticRWLock to lock for reading
|
||||
@Returns: TRUE, if @lock could be locked for reading
|
||||
@lock: a #GStaticRWLock to lock for reading.
|
||||
@Returns: %TRUE, if @lock could be locked for reading.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_rw_lock_reader_unlock ##### -->
|
||||
@ -1164,7 +1165,7 @@ locks for reading have been unlocked, the waiting thread is woken up
|
||||
and can lock @lock for writing.
|
||||
</para>
|
||||
|
||||
@lock: a #GStaticRWLock to unlock after reading
|
||||
@lock: a #GStaticRWLock to unlock after reading.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_rw_lock_writer_lock ##### -->
|
||||
@ -1178,19 +1179,19 @@ reading. When @lock is locked for writing, no other thread can lock
|
||||
by g_static_rw_lock_writer_unlock().
|
||||
</para>
|
||||
|
||||
@lock: a #GStaticRWLock to lock for writing
|
||||
@lock: a #GStaticRWLock to lock for writing.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_rw_lock_writer_trylock ##### -->
|
||||
<para>
|
||||
Tries to lock @lock for writing. If @lock is already locked (for
|
||||
either reading or writing) by another thread, it immediately returns
|
||||
#FALSE. Otherwise it locks @lock for writing and returns TRUE. This
|
||||
%FALSE. Otherwise it locks @lock for writing and returns %TRUE. This
|
||||
lock has to be unlocked by g_static_rw_lock_writer_unlock().
|
||||
</para>
|
||||
|
||||
@lock: a #GStaticRWLock to lock for writing
|
||||
@Returns: TRUE, if @lock could be locked for writing
|
||||
@lock: a #GStaticRWLock to lock for writing.
|
||||
@Returns: %TRUE, if @lock could be locked for writing.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_rw_lock_writer_unlock ##### -->
|
||||
@ -1202,7 +1203,7 @@ writing and threads wait to lock @lock for reading, the waiting
|
||||
threads are woken up and can lock @lock for reading.
|
||||
</para>
|
||||
|
||||
@lock: a #GStaticRWLock to unlock after writing
|
||||
@lock: a #GStaticRWLock to unlock after writing.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_rw_lock_free ##### -->
|
||||
@ -1217,7 +1218,7 @@ unbounded lifetime, i.e. objects declared 'static', but if you have a
|
||||
you should also free the #GStaticRWLock.
|
||||
</para>
|
||||
|
||||
@lock: a #GStaticRWLock to be freed
|
||||
@lock: a #GStaticRWLock to be freed.
|
||||
|
||||
|
||||
<!-- ##### STRUCT GCond ##### -->
|
||||
@ -1263,9 +1264,9 @@ gpointer pop_data ()
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Whenever a thread calls pop_data() now, it will wait until
|
||||
current_data is non-NULL, i.e. until some other thread has called
|
||||
push_data().
|
||||
Whenever a thread calls <function>pop_data()</function> now, it will
|
||||
wait until current_data is non-%NULL, i.e. until some other thread
|
||||
has called <function>push_data()</function>.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
@ -1286,8 +1287,9 @@ A #GCond should only be accessed via the following functions.
|
||||
|
||||
<note>
|
||||
<para>
|
||||
All of the g_cond_* functions are actually macros. Apart from taking
|
||||
the addresses of them, you can however use them as if they were functions.
|
||||
All of the <function>g_cond_*</function> functions are actually macros.
|
||||
Apart from taking their addresses, you can however use them as if they
|
||||
were functions.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@ -1299,7 +1301,7 @@ Creates a new #GCond. This function will abort, if g_thread_init()
|
||||
has not been called yet.
|
||||
</para>
|
||||
|
||||
@Returns: a new #GCond
|
||||
@Returns: a new #GCond.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_cond_signal ##### -->
|
||||
@ -1314,7 +1316,7 @@ This function can also be used, if g_thread_init() has
|
||||
not yet been called and will do nothing then.
|
||||
</para>
|
||||
|
||||
@cond: a #GCond
|
||||
@cond: a #GCond.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_cond_broadcast ##### -->
|
||||
@ -1330,7 +1332,7 @@ This function can also be used, if g_thread_init() has
|
||||
not yet been called and will do nothing then.
|
||||
</para>
|
||||
|
||||
@cond: a #GCond
|
||||
@cond: a #GCond.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_cond_wait ##### -->
|
||||
@ -1345,8 +1347,8 @@ This function can also be used, if g_thread_init() has not yet been
|
||||
called and will immediately return then.
|
||||
</para>
|
||||
|
||||
@cond: a #GCond
|
||||
@mutex: a #GMutex, that is currently locked
|
||||
@cond: a #GCond.
|
||||
@mutex: a #GMutex, that is currently locked.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_cond_timed_wait ##### -->
|
||||
@ -1358,12 +1360,12 @@ unlocked before falling asleep and locked again before resuming.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If @abs_time is NULL, g_cond_timed_wait() acts like g_cond_wait().
|
||||
If @abs_time is %NULL, g_cond_timed_wait() acts like g_cond_wait().
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This function can also be used, if g_thread_init() has not yet been
|
||||
called and will immediately return TRUE then.
|
||||
called and will immediately return %TRUE then.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -1371,10 +1373,10 @@ To easily calculate @abs_time a combination of g_get_current_time()
|
||||
and g_time_val_add() can be used.
|
||||
</para>
|
||||
|
||||
@cond: a #GCond
|
||||
@mutex: a #GMutex, that is currently locked
|
||||
@abs_time: a #GTimeVal, determining the final time
|
||||
@Returns: TRUE, if the thread is woken up in time
|
||||
@cond: a #GCond.
|
||||
@mutex: a #GMutex, that is currently locked.
|
||||
@abs_time: a #GTimeVal, determining the final time.
|
||||
@Returns: %TRUE, if the thread is woken up in time.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_cond_free ##### -->
|
||||
@ -1383,15 +1385,16 @@ and g_time_val_add() can be used.
|
||||
Destroys the #GCond.
|
||||
</para>
|
||||
|
||||
@cond: a #GCond
|
||||
@cond: a #GCond.
|
||||
|
||||
|
||||
<!-- ##### STRUCT GPrivate ##### -->
|
||||
<para>
|
||||
The #GPrivate struct is an opaque data structure to represent a thread
|
||||
private data key. Threads can thereby obtain and set a pointer, which
|
||||
is private to the current thread. Take our give_me_next_number()
|
||||
example from above. Now we don't want current_number to be shared
|
||||
is private to the current thread.
|
||||
Take our <function>give_me_next_number()</function> example from above.
|
||||
Now we don't want <literal>current_number</literal> to be shared
|
||||
between the threads, but to be private to each thread. This can be
|
||||
done as follows:
|
||||
|
||||
@ -1419,11 +1422,10 @@ done as follows:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Here the pointer belonging to the key current_number_key is read. If
|
||||
it is NULL, it has not been set yet. Then get memory for an integer
|
||||
value, assign this memory to the pointer and write the pointer
|
||||
back. Now we have an integer value, that is private to the current
|
||||
thread.
|
||||
Here the pointer belonging to the key <literal>current_number_key</literal>
|
||||
is read. If it is %NULL, it has not been set yet. Then get memory for an
|
||||
integer value, assign this memory to the pointer and write the pointer
|
||||
back. Now we have an integer value, that is private to the current thread.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -1432,8 +1434,9 @@ The #GPrivate struct should only be accessed via the following functions.
|
||||
|
||||
<note>
|
||||
<para>
|
||||
All of the g_private_* functions are actually macros. Apart from taking
|
||||
the addresses of them, you can however use them as if they were functions.
|
||||
All of the <function>g_private_*</function> functions are actually macros.
|
||||
Apart from taking their addresses, you can however use them as if they were
|
||||
functions.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@ -1441,9 +1444,9 @@ the addresses of them, you can however use them as if they were functions.
|
||||
<!-- ##### FUNCTION g_private_new ##### -->
|
||||
|
||||
<para>
|
||||
Creates a new #GPrivate. If @destructor is non-NULL, it is a pointer
|
||||
Creates a new #GPrivate. If @destructor is non-%NULL, it is a pointer
|
||||
to a destructor function. Whenever a thread ends and the corresponding
|
||||
pointer keyed to this instance of #GPrivate is non-NULL, the
|
||||
pointer keyed to this instance of #GPrivate is non-%NULL, the
|
||||
destructor is called with this pointer as the argument.
|
||||
</para>
|
||||
|
||||
@ -1468,15 +1471,15 @@ This function will abort, if g_thread_init() has not been called yet.
|
||||
</note>
|
||||
|
||||
@destructor: a function to handle the data keyed to #GPrivate, when a
|
||||
thread ends
|
||||
@Returns: a new #GPrivate
|
||||
thread ends.
|
||||
@Returns: a new #GPrivate.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_private_get ##### -->
|
||||
|
||||
<para>
|
||||
Returns the pointer keyed to @private_key for the current thread. This
|
||||
pointer is NULL, when g_private_set() hasn't been called for the
|
||||
pointer is %NULL, when g_private_set() hasn't been called for the
|
||||
current @private_key and thread yet.
|
||||
</para>
|
||||
|
||||
@ -1485,8 +1488,8 @@ This function can also be used, if g_thread_init() has not yet been
|
||||
called and will return the value of @private_key casted to #gpointer then.
|
||||
</para>
|
||||
|
||||
@private_key: a #GPrivate
|
||||
@Returns: the corresponding pointer
|
||||
@private_key: a #GPrivate.
|
||||
@Returns: the corresponding pointer.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_private_set ##### -->
|
||||
@ -1500,8 +1503,8 @@ This function can also be used, if g_thread_init() has not yet been
|
||||
called and will set @private_key to @data casted to #GPrivate* then.
|
||||
</para>
|
||||
|
||||
@private_key: a #GPrivate
|
||||
@data: the new pointer
|
||||
@private_key: a #GPrivate.
|
||||
@data: the new pointer.
|
||||
|
||||
|
||||
<!-- ##### STRUCT GStaticPrivate ##### -->
|
||||
@ -1511,7 +1514,7 @@ A #GStaticPrivate works almost like a #GPrivate, but it has one
|
||||
significant advantage. It doesn't need to be created at run-time like
|
||||
a #GPrivate, but can be defined at compile-time. This is similar to
|
||||
the difference between #GMutex and #GStaticMutex. Now look at our
|
||||
give_me_next_number() example with #GStaticPrivate:
|
||||
<function>give_me_next_number()</function> example with #GStaticPrivate:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -1560,7 +1563,7 @@ Initializes @private_key. Alternatively you can initialize it with
|
||||
#G_STATIC_PRIVATE_INIT.
|
||||
</para>
|
||||
|
||||
@private_key: a #GStaticPrivate to be initialized
|
||||
@private_key: a #GStaticPrivate to be initialized.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_private_get ##### -->
|
||||
@ -1572,14 +1575,14 @@ Works like g_private_get() only for a #GStaticPrivate.
|
||||
This function also works, if g_thread_init() has not yet been called.
|
||||
</para>
|
||||
|
||||
@private_key: a #GStaticPrivate
|
||||
@Returns: the corresponding pointer
|
||||
@private_key: a #GStaticPrivate.
|
||||
@Returns: the corresponding pointer.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_private_set ##### -->
|
||||
<para>
|
||||
Sets the pointer keyed to @private_key for the current thread and the
|
||||
function @notify to be called with that pointer (NULL or non-NULL),
|
||||
function @notify to be called with that pointer (%NULL or non-%NULL),
|
||||
whenever the pointer is set again or whenever the current thread ends.
|
||||
</para>
|
||||
|
||||
@ -1597,10 +1600,10 @@ g_private_new().
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@private_key: a #GStaticPrivate
|
||||
@data: the new pointer
|
||||
@private_key: a #GStaticPrivate.
|
||||
@data: the new pointer.
|
||||
@notify: a function to be called with the pointer, whenever the
|
||||
current thread ends or sets this pointer again
|
||||
current thread ends or sets this pointer again.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_static_private_free ##### -->
|
||||
@ -1615,6 +1618,5 @@ unbounded lifetime, i.e. objects declared 'static', but if you have a
|
||||
you should also free the #GStaticPrivate.
|
||||
</para>
|
||||
|
||||
@private_key: a #GStaticPrivate to be freed
|
||||
|
||||
@private_key: a #GStaticPrivate to be freed.
|
||||
|
||||
|
||||
@ -58,7 +58,7 @@ The <structfield>next</structfield> and <structfield>prev</structfield>
|
||||
fields point to the node's siblings (a sibling is another #GNode with the
|
||||
same parent).
|
||||
The <structfield>parent</structfield> field points to the parent of the #GNode,
|
||||
or is NULL if the #GNode is the root of the tree.
|
||||
or is %NULL if the #GNode is the root of the tree.
|
||||
The <structfield>children</structfield> field points to the first child of the
|
||||
#GNode. The other children are accessed by using the
|
||||
<structfield>next</structfield> pointer of each child.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user