luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-26 15:36:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

Fix up gthread.c documentation

Browse Source 
The last incomplete commit got pushed accidentally.  This finishes it up.
This commit is contained in:
Ryan Lortie 2010-01-30 21:55:03 -05:00
parent 0f246e28ca
commit d87712d3e6
1 changed files with 151 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

214
glib/gthread.c
View File

@ -169,12 +169,25 @@
* <function>give_me_next_number()</function> example using the * <function>give_me_next_number()</function> example using the
* %G_LOCK_* macros: * %G_LOCK_* macros:
* *
* <example> <title>Using the %G_LOCK_* convenience macros</title> * <example>
* <programlisting> G_LOCK_DEFINE (current_number); int * <title>Using the %G_LOCK_* convenience macros</title>
* give_me_next_number (<!-- -->) { static int current_number = 0; int * <programlisting>
* ret_val; G_LOCK (current_number); ret_val = current_number = * G_LOCK_DEFINE (current_number);
* calc_next_number (current_number); G_UNLOCK (current_number); return *
* ret_val; } </programlisting> </example> * int
* give_me_next_number (void)
* {
* static int current_number = 0;
* int ret_val;
*
* G_LOCK (current_number);
* ret_val = current_number = calc_next_number (current_number);
* G_UNLOCK (current_number);
*
* return ret_val;
* }
* </programlisting>
* </example>
**/ **/
/** /**
@ -351,9 +364,9 @@ GThreadFunctions g_thread_functions_for_glib_use = {
* { * {
* static int current_number = 0; * static int current_number = 0;
* *
* /&#x2a; now do a very complicated calculation to calculate the new * /<!-- -->* now do a very complicated calculation to calculate the new
* * number, this might for example be a random number generator * * number, this might for example be a random number generator
* &#x2a;/ * *<!-- -->/
* current_number = calc_next_number (current_number); * current_number = calc_next_number (current_number);
* *
* return current_number; * return current_number;
@ -396,11 +409,11 @@ GThreadFunctions g_thread_functions_for_glib_use = {
* <programlisting> * <programlisting>
* static GMutex *give_me_next_number_mutex = NULL; * static GMutex *give_me_next_number_mutex = NULL;
* *
* /&#x2a; this function must be called before any call to * /<!-- -->* this function must be called before any call to
* * give_me_next_number(<!-- -->) * * give_me_next_number(<!-- -->)
* * * *
* * it must be called exactly once. * * it must be called exactly once.
* &#x2a;/ * *<!-- -->/
* void * void
* init_give_me_next_number (void) * init_give_me_next_number (void)
* { * {
@ -525,8 +538,8 @@ GThreadFunctions g_thread_functions_for_glib_use = {
* Using GCond to block a thread until a condition is satisfied * Using GCond to block a thread until a condition is satisfied
* </title> * </title>
* <programlisting> * <programlisting>
* GCond* data_cond = NULL; /&#x2a; Must be initialized somewhere &#x2a;/ * GCond* data_cond = NULL; /<!-- -->* Must be initialized somewhere *<!-- -->/
* GMutex* data_mutex = NULL; /&#x2a; Must be initialized somewhere &#x2a;/ * GMutex* data_mutex = NULL; /<!-- -->* Must be initialized somewhere *<!-- -->/
* gpointer current_data = NULL; * gpointer current_data = NULL;
* *
* void * void
@ -668,8 +681,8 @@ GThreadFunctions g_thread_functions_for_glib_use = {
* <example> * <example>
* <title>Using GPrivate for per-thread data</title> * <title>Using GPrivate for per-thread data</title>
* <programlisting> * <programlisting>
* GPrivate* current_number_key = NULL; /&#x2a; Must be initialized somewhere * GPrivate* current_number_key = NULL; /<!-- -->* Must be initialized somewhere
* with g_private_new (g_free); &#2a;/ * with g_private_new (g_free); *<!-- -->/
* *
* int * int
* give_me_next_number (void) * give_me_next_number (void)
@ -956,9 +969,11 @@ g_thread_init_glib (void)
* *
* A #GOnce must be initialized with this macro before it can be used. * A #GOnce must be initialized with this macro before it can be used.
* *
* <informalexample><programlisting> * <informalexample>
* <programlisting>
* GOnce my_once = G_ONCE_INIT; * GOnce my_once = G_ONCE_INIT;
* </programlisting></informalexample> * </programlisting>
* </informalexample>
* *
* Since: 2.4 * Since: 2.4
**/ **/
@ -996,13 +1011,19 @@ g_thread_init_glib (void)
* <note><para>Calling g_once() recursively on the same #GOnce struct in * <note><para>Calling g_once() recursively on the same #GOnce struct in
* @func will lead to a deadlock.</para></note> * @func will lead to a deadlock.</para></note>
* *
* <informalexample><programlisting> * <informalexample>
* gpointer get_debug_flags () { * <programlisting>
* gpointer
* get_debug_flags (void)
* {
* static GOnce my_once = G_ONCE_INIT; * static GOnce my_once = G_ONCE_INIT;
*
* g_once (&my_once, parse_debug_flags, NULL); * g_once (&my_once, parse_debug_flags, NULL);
*
* return my_once.retval; * return my_once.retval;
* } * }
* </programlisting></informalexample> * </programlisting>
* </informalexample>
* *
* Since: 2.4 * Since: 2.4
**/ **/
@ -1056,12 +1077,12 @@ g_once_impl (GOnce *once,
* *
* if (g_once_init_enter (&amp;initialization_value)) * if (g_once_init_enter (&amp;initialization_value))
* { * {
* gsize setup_value = 42; /&#x2a; initialization code here &#x2a;/ * gsize setup_value = 42; /<!-- -->* initialization code here *<!-- -->/
* *
* g_once_init_leave (&amp;initialization_value, setup_value); * g_once_init_leave (&amp;initialization_value, setup_value);
* } * }
* *
* /&#x2a; use initialization_value here &#x2a;/ * /<!-- -->* use initialization_value here *<!-- -->/
* </programlisting> * </programlisting>
* </informalexample> * </informalexample>
* *
@ -1128,13 +1149,27 @@ g_once_init_leave (volatile gsize *value_location,
* safer version of our <function>give_me_next_number()</function> * safer version of our <function>give_me_next_number()</function>
* example: * example:
* *
* <example> <title>Using <structname>GStaticMutex</structname> to * <example>
* simplify thread-safe programming</title> <programlisting> int * <title>
* give_me_next_number (<!-- -->) { static int current_number = 0; int * Using <structname>GStaticMutex</structname>
* ret_val; static GStaticMutex mutex = G_STATIC_MUTEX_INIT; * to simplify thread-safe programming
* g_static_mutex_lock (&amp;mutex); ret_val = current_number = * </title>
* calc_next_number (current_number); g_static_mutex_unlock * <programlisting>
* (&amp;mutex); return ret_val; } </programlisting> </example> * int
* give_me_next_number (void)
* {
* static int current_number = 0;
* int ret_val;
* static GStaticMutex mutex = G_STATIC_MUTEX_INIT;
*
* g_static_mutex_lock (&amp;mutex);
* ret_val = current_number = calc_next_number (current_number);
* g_static_mutex_unlock (&amp;mutex);
*
* return ret_val;
* }
* </programlisting>
* </example>
* *
* Sometimes you would like to dynamically create a mutex. If you don't * Sometimes you would like to dynamically create a mutex. If you don't
* want to require prior calling to g_thread_init(), because your code * want to require prior calling to g_thread_init(), because your code
@ -1168,8 +1203,11 @@ g_once_init_leave (volatile gsize *value_location,
* cannot be assigned to a variable. In that case you have to use * cannot be assigned to a variable. In that case you have to use
* g_static_mutex_init(). * g_static_mutex_init().
* *
* <informalexample> <programlisting> GStaticMutex my_mutex = * <informalexample>
* G_STATIC_MUTEX_INIT; </programlisting> </informalexample> * <programlisting>
* GStaticMutex my_mutex = G_STATIC_MUTEX_INIT;
* </programlisting>
* </informalexample>
**/ **/
/** /**
@ -1328,8 +1366,11 @@ g_static_mutex_free (GStaticMutex* mutex)
* cannot be assigned to a variable. In that case you have to use * cannot be assigned to a variable. In that case you have to use
* g_static_rec_mutex_init(). * g_static_rec_mutex_init().
* *
* <informalexample> <programlisting> GStaticRecMutex my_mutex = * <informalexample>
* G_STATIC_REC_MUTEX_INIT; </programlisting> </informalexample> * <programlisting>
* GStaticRecMutex my_mutex = G_STATIC_REC_MUTEX_INIT;
* </programlisting>
</informalexample>
**/ **/
/** /**
@ -1542,14 +1583,28 @@ g_static_rec_mutex_free (GStaticRecMutex *mutex)
* look at our <function>give_me_next_number()</function> example with * look at our <function>give_me_next_number()</function> example with
* #GStaticPrivate: * #GStaticPrivate:
* *
* <example> <title>Using GStaticPrivate for per-thread data</title> * <example>
* <programlisting> int give_me_next_number (<!-- -->) { static * <title>Using GStaticPrivate for per-thread data</title>
* GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT; int * <programlisting>
* *current_number = g_static_private_get (&amp;current_number_key); if * int
* (!current_number) { current_number = g_new (int,1); *current_number * give_me_next_number (<!-- -->)
* = 0; g_static_private_set (&amp;current_number_key, current_number, * {
* g_free); } *current_number = calc_next_number (*current_number); * static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT;
* return *current_number; } </programlisting> </example> * int *current_number = g_static_private_get (&amp;current_number_key);
*
* if (!current_number)
* {
* current_number = g_new (int,1);
* *current_number = 0;
* g_static_private_set (&amp;current_number_key, current_number, g_free);
* }
*
* *current_number = calc_next_number (*current_number);
*
* return *current_number;
* }
* </programlisting>
* </example>
**/ **/
/** /**
@ -1558,8 +1613,11 @@ g_static_rec_mutex_free (GStaticRecMutex *mutex)
* Every #GStaticPrivate must be initialized with this macro, before it * Every #GStaticPrivate must be initialized with this macro, before it
* can be used. * can be used.
* *
* <informalexample> <programlisting> GStaticPrivate my_private = * <informalexample>
* G_STATIC_PRIVATE_INIT; </programlisting> </informalexample> * <programlisting>
* GStaticPrivate my_private = G_STATIC_PRIVATE_INIT;
* </programlisting>
* </informalexample>
**/ **/
/** /**
@ -1932,15 +1990,14 @@ g_thread_create_full (GThreadFunc func,
* of g_thread_join(). If the current thread is not joinable, @retval * of g_thread_join(). If the current thread is not joinable, @retval
* is ignored. Calling * is ignored. Calling
* *
* <informalexample> <programlisting> g_thread_exit (retval); * <informalexample>
* </programlisting> </informalexample> * <programlisting>
* * g_thread_exit (retval);
* is equivalent to calling * </programlisting>
*
* <informalexample> <programlisting> return retval; </programlisting>
* </informalexample> * </informalexample>
* *
* in the function @func, as given to g_thread_create(). * is equivalent to returning @retval from the function @func, as given
* to g_thread_create().
* *
* <note><para>Never call g_thread_exit() from within a thread of a * <note><para>Never call g_thread_exit() from within a thread of a
* #GThreadPool, as that will mess up the bookkeeping and lead to funny * #GThreadPool, as that will mess up the bookkeeping and lead to funny
@ -2088,18 +2145,46 @@ g_thread_self (void)
* read from, while others also write. In such situations it is * read from, while others also write. In such situations it is
* desirable that several readers can read at once, whereas of course * desirable that several readers can read at once, whereas of course
* only one writer may write at a time. Take a look at the following * only one writer may write at a time. Take a look at the following
* example: <example> <title>An array with access functions</title> * example:
* <programlisting> GStaticRWLock rwlock = G_STATIC_RW_LOCK_INIT; *
* GPtrArray *array; gpointer my_array_get (guint index) { gpointer * <example>
* retval = NULL; if (!array) return NULL; g_static_rw_lock_reader_lock * <title>An array with access functions</title>
* (&amp;rwlock); if (index &lt; array->len) retval = g_ptr_array_index * <programlisting>
* (array, index); g_static_rw_lock_reader_unlock (&amp;rwlock); return * GStaticRWLock rwlock = G_STATIC_RW_LOCK_INIT;
* retval; } void my_array_set (guint index, gpointer data) { * GPtrArray *array;
* g_static_rw_lock_writer_lock (&amp;rwlock); if (!array) array = *
* g_ptr_array_new (<!-- -->); if (index >= array->len) * gpointer
* g_ptr_array_set_size (array, index+1); g_ptr_array_index (array, * my_array_get (guint index)
* index) = data; g_static_rw_lock_writer_unlock (&amp;rwlock); } * {
* </programlisting> </example> * gpointer retval = NULL;
*
* if (!array)
* return NULL;
*
* g_static_rw_lock_reader_lock (&amp;rwlock);
* if (index &lt; array->len)
* retval = g_ptr_array_index (array, index);
* g_static_rw_lock_reader_unlock (&amp;rwlock);
*
* return retval;
* }
*
* void
* my_array_set (guint index, gpointer data)
* {
* g_static_rw_lock_writer_lock (&amp;rwlock);
*
* if (!array)
* array = g_ptr_array_new (<!-- -->);
*
* if (index >= array->len)
* g_ptr_array_set_size (array, index+1);
* g_ptr_array_index (array, index) = data;
*
* g_static_rw_lock_writer_unlock (&amp;rwlock);
* }
* </programlisting>
* </example>
* *
* This example shows an array which can be accessed by many readers * This example shows an array which can be accessed by many readers
* (the <function>my_array_get()</function> function) simultaneously, * (the <function>my_array_get()</function> function) simultaneously,
@ -2143,8 +2228,11 @@ g_thread_self (void)
* cannot be assigned to a variable. In that case you have to use * cannot be assigned to a variable. In that case you have to use
* g_static_rw_lock_init(). * g_static_rw_lock_init().
* *
* <informalexample> <programlisting> GStaticRWLock my_lock = * <informalexample>
* G_STATIC_RW_LOCK_INIT; </programlisting> </informalexample> * <programlisting>
* GStaticRWLock my_lock = G_STATIC_RW_LOCK_INIT;
* </programlisting>
* </informalexample>
**/ **/
/** /**