<!-- ##### 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 ##### -->
<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>
<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>
<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>
<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>
</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:
@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.
</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.
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 ##### -->
<!-- ##### 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 ##### -->
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.
@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.
@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.
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>
</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>
</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 ##### -->
</para>
</note>
-@Returns: TRUE, if the thread system is initialized
+@Returns: %TRUE, if the thread system is initialized.
<!-- ##### USER_FUNCTION GThreadFunc ##### -->
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 ##### -->
</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>
</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 ##### -->
</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.
</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>
</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 ##### -->
This functions returns the #GThread corresponding to the calling thread.
</para>
-@Returns: the current thread
+@Returns: the current thread.
<!-- ##### FUNCTION g_thread_join ##### -->
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 ##### -->
</para>
</note>
-@thread: a #GThread
-@priority: a new priority for @thread
+@thread: a #GThread.
+@priority: a new priority for @thread.
<!-- ##### FUNCTION g_thread_yield ##### -->
</para>
</note>
-@retval: the return value of this thread
+@retval: the return value of this thread.
<!-- ##### STRUCT GMutex ##### -->
<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>
</para>
</note>
-@Returns: a new #GMutex
+@Returns: a new #GMutex.
<!-- ##### FUNCTION g_mutex_lock ##### -->
</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 ##### -->
called and will do nothing then.
</para>
-@mutex: a #GMutex
+@mutex: a #GMutex.
<!-- ##### FUNCTION g_mutex_free ##### -->
Destroys @mutex.
</para>
-@mutex: a #GMutex
+@mutex: a #GMutex.
<!-- ##### STRUCT GStaticMutex ##### -->
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>
</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>
#G_STATIC_MUTEX_INIT.
</para>
-@mutex: a #GStaticMutex to be initialized
+@mutex: a #GStaticMutex to be initialized.
<!-- ##### FUNCTION g_static_mutex_lock ##### -->
Works like g_mutex_lock(), but for a #GStaticMutex.
</para>
-@mutex: a #GStaticMutex
+@mutex: a #GStaticMutex.
<!-- ##### FUNCTION g_static_mutex_trylock ##### -->
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 ##### -->
Works like g_mutex_unlock(), but for a #GStaticMutex.
</para>
-@mutex: a #GStaticMutex
+@mutex: a #GStaticMutex.
<!-- ##### FUNCTION g_static_mutex_get_mutex ##### -->
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 ##### -->
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
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>
</example>
</para>
-@name: the name of the lock
+@name: the name of the lock.
<!-- ##### MACRO G_LOCK_DEFINE_STATIC ##### -->
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 ##### -->
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 ##### -->
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 ##### -->
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 ##### -->
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 ##### -->
</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:
#G_STATIC_REC_MUTEX_INIT.
</para>
-@mutex: a #GStaticRecMutex to be initialized
+@mutex: a #GStaticRecMutex to be initialized.
<!-- ##### FUNCTION g_static_rec_mutex_lock ##### -->
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 ##### -->
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 ##### -->
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 ##### -->
freed, you should also free the #GStaticRecMutex.
</para>
-@mutex: a #GStaticRecMutex to be freed
+@mutex: a #GStaticRecMutex to be freed.
<!-- ##### STRUCT GStaticRWLock ##### -->
<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>
</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>
#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 ##### -->
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 ##### -->
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 ##### -->
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 ##### -->
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 ##### -->
you should also free the #GStaticRWLock.
</para>
-@lock: a #GStaticRWLock to be freed
+@lock: a #GStaticRWLock to be freed.
<!-- ##### STRUCT GCond ##### -->
</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>
<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>
has not been called yet.
</para>
-@Returns: a new #GCond
+@Returns: a new #GCond.
<!-- ##### FUNCTION g_cond_signal ##### -->
not yet been called and will do nothing then.
</para>
-@cond: a #GCond
+@cond: a #GCond.
<!-- ##### FUNCTION g_cond_broadcast ##### -->
not yet been called and will do nothing then.
</para>
-@cond: a #GCond
+@cond: a #GCond.
<!-- ##### FUNCTION g_cond_wait ##### -->
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 ##### -->
</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>
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 ##### -->
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:
</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>
<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>
<!-- ##### 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>
</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>
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 ##### -->
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 ##### -->
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>
#G_STATIC_PRIVATE_INIT.
</para>
-@private_key: a #GStaticPrivate to be initialized
+@private_key: a #GStaticPrivate to be initialized.
<!-- ##### FUNCTION g_static_private_get ##### -->
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>
</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 ##### -->
you should also free the #GStaticPrivate.
</para>
-@private_key: a #GStaticPrivate to be freed
-
+@private_key: a #GStaticPrivate to be freed.
projects / platform / upstream / glib.git / commitdiff