[glib] GThread doc additions

[Matthias Clasen <matthiasc src gnome org>]

commit d6b0af99d711584ca4e44f218a4cd2151a9ccef4
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Sep 24 19:00:19 2011 -0400

    GThread doc additions

 docs/reference/glib/glib-sections.txt |   41 +++-
 glib/deprecated/gthread.h             |    3 +
 glib/gthread-posix.c                  |  406 ++++++++++++++++++++++++++++++---
 glib/gthread.c                        |   66 ++++--
 4 files changed, 458 insertions(+), 58 deletions(-)
---
diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index 8f5fa13..17e2e72 100644
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -606,11 +606,35 @@ g_thread_foreach
 
 <SUBSECTION>
 GMutex
+G_MUTEX_INIT
+g_mutex_init
+g_mutex_clear
 g_mutex_new
+g_mutex_free
 g_mutex_lock
 g_mutex_trylock
 g_mutex_unlock
-g_mutex_free
+
+<SUBSECTION>
+GRecMutex
+G_REC_MUTEX_INIT
+g_rec_mutex_init
+g_rec_mutex_clear
+g_rec_mutex_lock
+g_rec_mutex_trylock
+g_rec_mutex_unlock
+
+<SUBSECTION>
+GRWLock
+G_RW_LOCK_INIT
+g_rw_lock_init
+g_rw_lock_clear
+g_rw_lock_writer_lock
+g_rw_lock_writer_trylock
+g_rw_lock_writer_unlock
+g_rw_lock_reader_lock
+g_rw_lock_reader_trylock
+g_rw_lock_reader_unlock
 
 <SUBSECTION>
 GStaticMutex
@@ -655,12 +679,16 @@ g_static_rw_lock_free
 
 <SUBSECTION>
 GCond
+G_COND_INIT
 g_cond_new
-g_cond_signal
-g_cond_broadcast
+g_cond_free
+g_cond_init
+g_cond_clear
 g_cond_wait
 g_cond_timed_wait
-g_cond_free
+g_cond_timedwait
+g_cond_signal
+g_cond_broadcast
 
 <SUBSECTION>
 GPrivate
@@ -693,13 +721,8 @@ g_pointer_bit_trylock
 g_pointer_bit_unlock
 
 <SUBSECTION Private>
-G_THREAD_ECF
-G_THREAD_CF
-G_THREAD_UF
 g_static_mutex_get_mutex_impl
 g_static_mutex_get_mutex_impl_shortcut
-G_MUTEX_DEBUG_MAGIC
-g_thread_init_with_errorcheck_mutexes
 G_LOCK_NAME
 glib_dummy_decl
 GSystemThread
diff --git a/glib/deprecated/gthread.h b/glib/deprecated/gthread.h
index 9b09e1d..668064a 100644
--- a/glib/deprecated/gthread.h
+++ b/glib/deprecated/gthread.h
@@ -107,6 +107,9 @@ GThread* g_thread_create_full  (GThreadFunc            func,
                                 GThreadPriority        priority,
                                 GError               **error);
 
+void g_thread_set_priority     (GThread         *thread,
+                                GThreadPriority  priority);
+
 #ifdef G_OS_WIN32
 typedef GMutex * GStaticMutex;
 #define G_STATIC_MUTEX_INIT NULL
diff --git a/glib/gthread-posix.c b/glib/gthread-posix.c
index ca2703c..ce04ce4 100644
--- a/glib/gthread-posix.c
+++ b/glib/gthread-posix.c
@@ -63,6 +63,19 @@ g_thread_abort (gint         status,
 /* {{{1 GMutex */
 
 /**
+ * G_MUTEX_INIT:
+ *
+ * Initializer for statically allocated #GMutexes.
+ * Alternatively, g_mutex_init() can be used.
+ *
+ * |[
+ *   GMutex mutex = G_MUTEX_INIT;
+ * ]|
+ *
+ * Since: 2.32
+ */
+
+/**
  * g_mutex_init:
  * @mutex: an uninitialized #GMutex
  *
@@ -71,25 +84,27 @@ g_thread_abort (gint         status,
  * This function is useful to initialize a mutex that has been
  * allocated on the stack, or as part of a larger structure.
  * It is not necessary to initialize a mutex that has been
- * created with g_mutex_new(). Also see #G_MUTEX_INITIALIZER
- * for an alternative way to initialize statically allocated mutexes.
+ * created with g_mutex_new(). Also see #G_MUTEX_INIT for an
+ * alternative way to initialize statically allocated mutexes.
  *
  * |[
  *   typedef struct {
  *     GMutex m;
- *     /&ast; ... &ast;/
+ *     ...
  *   } Blob;
  *
  * Blob *b;
  *
  * b = g_new (Blob, 1);
  * g_mutex_init (&b->m);
- * /&ast; ... &ast;/
  * ]|
  *
  * To undo the effect of g_mutex_init() when a mutex is no longer
  * needed, use g_mutex_clear().
  *
+ * Calling g_mutex_init() on an already initialized #GMutex leads
+ * to undefined behaviour.
+ *
  * Since: 2.32
  */
 void
@@ -121,6 +136,9 @@ g_mutex_init (GMutex *mutex)
  * #GMutexes that have have been created with g_mutex_new() should
  * be freed with g_mutex_free() instead.
  *
+ * Calling g_mutex_clear() on a locked mutex leads to undefined
+ * behaviour.
+ *
  * Sine: 2.32
  */
 void
@@ -146,7 +164,7 @@ g_mutex_clear (GMutex *mutex)
  * <note>#GMutex is neither guaranteed to be recursive nor to be
  * non-recursive, i.e. a thread could deadlock while calling
  * g_mutex_lock(), if it already has locked @mutex. Use
- * #GStaticRecMutex, if you need recursive mutexes.</note>
+ * #GRecMutex if you need recursive mutexes.</note>
  */
 void
 g_mutex_lock (GMutex *mutex)
@@ -162,7 +180,10 @@ g_mutex_lock (GMutex *mutex)
  * @mutex: a #GMutex
  *
  * Unlocks @mutex. If another thread is blocked in a g_mutex_lock()
- * call for @mutex, it will be woken and can lock @mutex itself.
+ * call for @mutex, it will become unblocked and can lock @mutex itself.
+ *
+ * Calling g_mutex_unlock() on a mutex that is not locked by the
+ * current thread leads to undefined behaviour.
  *
  * This function can be used even if g_thread_init() has not yet been
  * called, and, in that case, will do nothing.
@@ -190,10 +211,9 @@ g_mutex_unlock (GMutex *mutex)
  * <note>#GMutex is neither guaranteed to be recursive nor to be
  * non-recursive, i.e. the return value of g_mutex_trylock() could be
  * both %FALSE or %TRUE, if the current thread already has locked
- * @mutex. Use #GStaticRecMutex, if you need recursive
- * mutexes.</note>
+ * @mutex. Use #GRecMutex if you need recursive mutexes.</note>
 
- * Returns: %TRUE, if @mutex could be locked
+ * Returns: %TRUE if @mutex could be locked
  */
 gboolean
 g_mutex_trylock (GMutex *mutex)
@@ -211,6 +231,23 @@ g_mutex_trylock (GMutex *mutex)
 
 /* {{{1 GRecMutex */
 
+/**
+ * GRecMutex:
+ *
+ * The GRecMutex struct is an opaque data structure to represent a
+ * recursive mutex. It is similar to a #GMutex with the difference
+ * that it is possible to lock a GRecMutex multiple times in the same
+ * thread without deadlock. When doing so, care has to be taken to
+ * unlock the recursive mutex as often as it has been locked.
+ *
+ * A GRecMutex should only be accessed with the
+ * <function>g_rec_mutex_</function> functions. Before a GRecMutex
+ * can be used, it has to be initialized with #G_REC_MUTEX_INIT or
+ * g_rec_mutex_init().
+ *
+ * Since: 2.32
+ */
+
 static pthread_mutex_t *
 g_rec_mutex_impl_new (void)
 {
@@ -249,35 +286,135 @@ g_rec_mutex_get_impl (GRecMutex *mutex)
   return impl;
 }
 
+/**
+ * G_REC_MUTEX_INIT:
+ *
+ * Initializer for statically allocated #GRecMutexes.
+ * Alternatively, g_rec_mutex_init() can be used.
+ *
+ * |[
+ *   GRecMutex mutex = G_REC_MUTEX_INIT;
+ * ]|
+ *
+ * Since: 2.32
+ */
+
+/**
+ * g_rec_mutex_init:
+ * @rec_mutex: an uninitialized #GRecMutex
+ *
+ * Initializes a #GRecMutex so that it can be used.
+ *
+ * This function is useful to initialize a recursive mutex
+ * that has been allocated on the stack, or as part of a larger
+ * structure.
+ * It is not necessary to initialize a recursive mutex that has
+ * been created with g_rec_mutex_new(). Also see #G_REC_MUTEX_INIT
+ * for an alternative way to initialize statically allocated
+ * recursive mutexes.
+ *
+ * |[
+ *   typedef struct {
+ *     GRecMutex m;
+ *     ...
+ *   } Blob;
+ *
+ * Blob *b;
+ *
+ * b = g_new (Blob, 1);
+ * g_rec_mutex_init (&b->m);
+ * ]|
+ *
+ * Calling g_rec_mutex_init() on an already initialized #GRecMutex
+ * leads to undefined behaviour.
+ *
+ * To undo the effect of g_rec_mutex_init() when a recursive mutex
+ * is no longer needed, use g_rec_mutex_clear().
+ *
+ * Since: 2.32
+ */
 void
-g_rec_mutex_init (GRecMutex *mutex)
+g_rec_mutex_init (GRecMutex *rec_mutex)
 {
-  mutex->impl = g_rec_mutex_impl_new ();
+  rec_mutex->impl = g_rec_mutex_impl_new ();
 }
 
+/**
+ * g_rec_mutex_clear:
+ * @rec_mutex: an initialized #GRecMutex
+ *
+ * Frees the resources allocated to a recursive mutex with
+ * g_rec_mutex_init().
+ *
+ * #GRecMutexes that have have been created with g_rec_mutex_new()
+ * should be freed with g_rec_mutex_free() instead.
+ *
+ * Calling g_rec_mutex_clear() on a locked recursive mutex leads
+ * to undefined behaviour.
+ *
+ * Sine: 2.32
+ */
 void
-g_rec_mutex_clear (GRecMutex *mutex)
+g_rec_mutex_clear (GRecMutex *rec_mutex)
 {
-  if (mutex->impl)
-    g_rec_mutex_impl_free (mutex->impl);
+  if (rec_mutex->impl)
+    g_rec_mutex_impl_free (rec_mutex->impl);
 }
 
+/**
+ * g_rec_mutex_lock:
+ * @rec_mutex: a #GRecMutex
+ *
+ * Locks @rec_mutex. If @rec_mutex is already locked by another
+ * thread, the current thread will block until @rec_mutex is
+ * unlocked by the other thread. If @rec_mutex is already locked
+ * by the current thread, the 'lock count' of @rec_mutex is increased.
+ * The mutex will only become available again when it is unlocked
+ * as many times as it has been locked.
+ *
+ * Since: 2.32
+ */
 void
 g_rec_mutex_lock (GRecMutex *mutex)
 {
   pthread_mutex_lock (g_rec_mutex_get_impl (mutex));
 }
 
+/**
+ * g_rec_mutex_unlock:
+ * @rec_mutex: a #RecGMutex
+ *
+ * Unlocks @rec_mutex. If another thread is blocked in a
+ * g_rec_mutex_lock() call for @rec_mutex, it will become unblocked
+ * and can lock @rec_mutex itself.
+ *
+ * Calling g_rec_mutex_unlock() on a recursive mutex that is not
+ * locked by the current thread leads to undefined behaviour.
+ *
+ * Since: 2.32
+ */
 void
-g_rec_mutex_unlock (GRecMutex *mutex)
+g_rec_mutex_unlock (GRecMutex *rec_mutex)
 {
-  pthread_mutex_unlock (mutex->impl);
+  pthread_mutex_unlock (rec_mutex->impl);
 }
 
+/**
+ * g_rec_mutex_trylock:
+ * @rec_mutex: a #GRecMutex
+ *
+ * Tries to lock @rec_mutex. If @rec_mutex is already locked
+ * by another thread, it immediately returns %FALSE. Otherwise
+ * it locks @rec_mutex and returns %TRUE.
+ *
+ * Returns: %TRUE if @rec_mutex could be locked
+ *
+ * Since: 2.32
+ */
 gboolean
-g_rec_mutex_trylock (GRecMutex *mutex)
+g_rec_mutex_trylock (GRecMutex *rec_mutex)
 {
-  if (pthread_mutex_trylock (g_rec_mutex_get_impl (mutex)) != 0)
+  if (pthread_mutex_trylock (g_rec_mutex_get_impl (rec_mutex)) != 0)
     return FALSE;
 
   return TRUE;
@@ -285,24 +422,170 @@ g_rec_mutex_trylock (GRecMutex *mutex)
 
 /* {{{1 GRWLock */
 
+/**
+ * GRWLock:
+ *
+ * The GRWLock struct is an opaque data structure to represent a
+ * reader-writer lock. It is similar to a #GMutex in that it allows
+ * multiple threads to coordinate access to a shared resource.
+ *
+ * The difference to a mutex is that a reader-writer lock discriminates
+ * between read-only ('reader') and full ('writer') access. While only
+ * one thread at a time is allowed write access (by holding the 'writer'
+ * lock via g_rw_lock_writer_lock()), multiple threads can gain
+ * simultaneous read-only access (by holding the 'reader' lock via
+ * g_rw_lock_reader_lock()).
+ *
+ * <example>
+ *  <title>An array with access functions</title>
+ *  <programlisting>
+ *   GRWLock lock = G_RW_LOCK_INIT;
+ *   GPtrArray *array;
+ *
+ *   gpointer
+ *   my_array_get (guint index)
+ *   {
+ *     gpointer retval = NULL;
+ *
+ *     if (!array)
+ *       return NULL;
+ *
+ *     g_rw_lock_reader_lock (&amp;lock);
+ *     if (index &lt; array->len)
+ *       retval = g_ptr_array_index (array, index);
+ *     g_rw_lock_reader_unlock (&amp;lock);
+ *
+ *     return retval;
+ *   }
+ *
+ *   void
+ *   my_array_set (guint index, gpointer data)
+ *   {
+ *     g_rw_lock_writer_lock (&amp;lock);
+ *
+ *     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_rw_lock_writer_unlock (&amp;lock);
+ *   }
+ *  </programlisting>
+ *  <para>
+ *    This example shows an array which can be accessed by many readers
+ *    (the <function>my_array_get()</function> function) simultaneously,
+ *    whereas the writers (the <function>my_array_set()</function>
+ *    function) will only be allowed once at 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>
+ * </example>
+ *
+ * A GRWLock should only be accessed with the
+ * <function>g_rw_lock_</function> functions. Before it can be used,
+ * it has to be initialized with #G_RW_LOCK_INIT or g_rw_lock_init().
+ *
+ * Since: 2.32
+ */
+
+/**
+ * G_RW_LOCK_INIT:
+ *
+ * Initializer for statically allocated #GRWLocks.
+ * Alternatively, g_rw_lock_init_init() can be used.
+ *
+ * |[
+ *   GRWLock lock = G_RW_LOCK_INIT;
+ * ]|
+ *
+ * Since: 2.32
+ */
+
+/**
+ * g_rw_lock_init:
+ * @lock: an uninitialized #GRWLock
+ *
+ * Initializes a #GRWLock so that it can be used.
+ *
+ * This function is useful to initialize a lock that has been
+ * allocated on the stack, or as part of a larger structure.
+ * Also see #G_RW_LOCK_INIT for an alternative way to initialize
+ * statically allocated locks.
+ *
+ * |[
+ *   typedef struct {
+ *     GRWLock l;
+ *     ...
+ *   } Blob;
+ *
+ * Blob *b;
+ *
+ * b = g_new (Blob, 1);
+ * g_rw_lock_init (&b->l);
+ * ]|
+ *
+ * To undo the effect of g_rw_lock_init() when a lock is no longer
+ * needed, use g_rw_lock_clear().
+ *
+ * Calling g_rw_lock_init() on an already initialized #GRWLock leads
+ * to undefined behaviour.
+ *
+ * Since: 2.32
+ */
 void
 g_rw_lock_init (GRWLock *lock)
 {
   pthread_rwlock_init (&lock->impl, NULL);
 }
 
+/**
+ * g_rw_lock_clear:
+ * @lock: an initialized #GRWLock
+ *
+ * Frees the resources allocated to a lock with g_rw_lock_init().
+ *
+ * Calling g_rw_lock_clear() when any thread holds the lock
+ * leads to undefined behaviour.
+ *
+ * Sine: 2.32
+ */
 void
 g_rw_lock_clear (GRWLock *lock)
 {
   pthread_rwlock_destroy (&lock->impl);
 }
 
+/**
+ * g_rw_lock_writer_lock:
+ * @lock: a #GRWLock
+ *
+ * Obtain a write lock on @lock. If any thread already holds
+ * a read or write lock on @lock, the current thread will block
+ * until all other threads have dropped their locks on @lock.
+ *
+ * Since: 2.32
+ */
 void
 g_rw_lock_writer_lock (GRWLock *lock)
 {
   pthread_rwlock_wrlock (&lock->impl);
 }
 
+/**
+ * g_rw_lock_writer_trylock:
+ * @lock: a #GRWLock
+ *
+ * Tries to obtain a write lock on @lock. If any other thread holds
+ * a read or write lock on @lock, it immediately returns %FALSE.
+ * Otherwise it locks @lock and returns %TRUE.
+ *
+ * Returns: %TRUE if @lock could be locked
+ *
+ * Since: 2.32
+ */
 gboolean
 g_rw_lock_writer_trylock (GRWLock *lock)
 {
@@ -312,18 +595,54 @@ g_rw_lock_writer_trylock (GRWLock *lock)
   return TRUE;
 }
 
+/**
+ * g_rw_lock_writer_unlock:
+ * @lock: a #GRWLock
+ *
+ * Release a write lock on @lock.
+ *
+ * Calling g_rw_lock_writer_unlock() on a lock that is not held
+ * by the current thread leads to undefined behaviour.
+ *
+ * Since: 2.32
+ */
 void
 g_rw_lock_writer_unlock (GRWLock *lock)
 {
   pthread_rwlock_unlock (&lock->impl);
 }
 
+/**
+ * g_rw_lock_reader_lock:
+ * @lock: a #GRWLock
+ *
+ * Obtain a read lock on @lock. If another thread currently holds
+ * the write lock on @lock or blocks waiting for it, the current
+ * thread will block. Read locks can be taken recursively.
+ *
+ * It is implementation-defined how many threads are allowed to
+ * hold read locks on the same lock simultaneously.
+ *
+ * Since: 2.32
+ */
 void
 g_rw_lock_reader_lock (GRWLock *lock)
 {
   pthread_rwlock_rdlock (&lock->impl);
 }
 
+/**
+ * g_rw_lock_reader_trylock:
+ * @lock: a #GRWLock
+ *
+ * Tries to obtain a read lock on @lock and returns %TRUE if
+ * the read lock was successfully obtained. Otherwise it
+ * returns %FALSE.
+ *
+ * Returns: %TRUE if @lock could be locked
+ *
+ * Since: 2.32
+ */
 gboolean
 g_rw_lock_reader_trylock (GRWLock *lock)
 {
@@ -333,6 +652,17 @@ g_rw_lock_reader_trylock (GRWLock *lock)
   return TRUE;
 }
 
+/**
+ * g_rw_lock_reader_unlock:
+ * @lock: a #GRWLock
+ *
+ * Release a read lock on @lock.
+ *
+ * Calling g_rw_lock_reader_unlock() on a lock that is not held
+ * by the current thread leads to undefined behaviour.
+ *
+ * Since: 2.32
+ */
 void
 g_rw_lock_reader_unlock (GRWLock *lock)
 {
@@ -342,6 +672,19 @@ g_rw_lock_reader_unlock (GRWLock *lock)
 /* {{{1 GCond */
 
 /**
+ * G_COND_INIT:
+ *
+ * Initializer for statically allocated #GConds.
+ * Alternatively, g_cond_init() can be used.
+ *
+ * |[
+ *   GCond cond = G_COND_INIT;
+ * ]|
+ *
+ * Since: 2.32
+ */
+
+/**
  * g_cond_init:
  * @cond: an uninitialized #GCond
  *
@@ -350,9 +693,14 @@ g_rw_lock_reader_unlock (GRWLock *lock)
  * This function is useful to initialize a #GCond that has been
  * allocated on the stack, or as part of a larger structure.
  * It is not necessary to initialize a #GCond that has been
- * created with g_cond_new(). Also see #G_COND_INITIALIZER
- * for an alternative way to initialize statically allocated
- * #GConds.
+ * created with g_cond_new(). Also see #G_COND_INIT for an
+ * alternative way to initialize statically allocated #GConds.
+ *
+ * To undo the effect of g_cond_init() when a #GCond is no longer
+ * needed, use g_cond_clear().
+ *
+ * Calling g_cond_init() on an already initialized #GCond leads
+ * to undefined behaviour.
  *
  * Since: 2.32
  */
@@ -369,11 +717,14 @@ g_cond_init (GCond *cond)
  * g_cond_clear:
  * @cond: an initialized #GCond
  *
- * Frees the resources allocated ot a #GCond with g_cond_init().
+ * Frees the resources allocated to a #GCond with g_cond_init().
  *
  * #GConds that have been created with g_cond_new() should
  * be freed with g_cond_free() instead.
  *
+ * Calling g_cond_clear() for a #GCond on which threads are
+ * blocking leads to undefined behaviour.
+ *
  * Since: 2.32
  */
 void
@@ -390,9 +741,8 @@ g_cond_clear (GCond *cond)
  * @cond: a #GCond
  * @mutex: a #GMutex that is currently locked
  *
- * Waits until this thread is woken up on @cond.
- * The @mutex is unlocked before falling asleep
- * and locked again before resuming.
+ * Waits until this thread is woken up on @cond. The @mutex is unlocked
+ * before falling asleep and locked again before resuming.
  *
  * This function can be used even if g_thread_init() has not yet been
  * called, and, in that case, will immediately return.
@@ -411,7 +761,8 @@ g_cond_wait (GCond  *cond,
  * g_cond_signal:
  * @cond: a #GCond
  *
- * If threads are waiting for @cond, exactly one of them is woken up.
+ * If threads are waiting for @cond, at least one of them is unblocked.
+ * If no threads are waiting for @cond, this function has no effect.
  * It is good practice to hold the same lock as the waiting thread
  * while calling this function, though not required.
  *
@@ -431,7 +782,8 @@ g_cond_signal (GCond *cond)
  * g_cond_broadcast:
  * @cond: a #GCond
  *
- * If threads are waiting for @cond, all of them are woken up.
+ * If threads are waiting for @cond, all of them are unblocked.
+ * If no threads are waiting for @cond, this function has no effect.
  * It is good practice to lock the same mutex as the waiting threads
  * while calling this function, though not required.
  *
diff --git a/glib/gthread.c b/glib/gthread.c
index a4fbc56..372f8d4 100644
--- a/glib/gthread.c
+++ b/glib/gthread.c
@@ -21,6 +21,7 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/* {{{1 Prelude */
 /* Prelude {{{1 ----------------------------------------------------------- */
 
 /*
@@ -67,8 +68,8 @@
 /**
  * SECTION:threads
  * @title: Threads
- * @short_description: thread abstraction; including threads, different
- *                     mutexes, conditions and thread private data
+ * @short_description: portable support for threads, mutexes, locks,
+ *     conditions and thread private data
  * @see_also: #GThreadPool, #GAsyncQueue
  *
  * Threads act almost like processes, but unlike processes all threads
@@ -81,7 +82,7 @@
  * threads can be made, unless order is explicitly forced by the
  * programmer through synchronization primitives.
  *
- * The aim of the thread related functions in GLib is to provide a
+ * The aim of the thread-related functions in GLib is to provide a
  * portable means for writing multi-threaded software. There are
  * primitives for mutexes to protect the access to portions of memory
  * (#GMutex, #GRecMutex and #GRWLock). There is a facility to use
@@ -90,8 +91,7 @@
  * There are primitives for thread-private data - data that every thread
  * has a private instance of (#GPrivate, #GStaticPrivate). There are
  * facilities for one-time initialization (#GOnce, g_once_init_enter()).
- * Last but definitely not least there are primitives to portably create
- * and manage threads (#GThread).
+ * Finally there are primitives to create and manage threads (#GThread).
  *
  * The threading system is initialized with g_thread_init(), which
  * takes an optional custom thread implementation or %NULL for the
@@ -109,7 +109,7 @@
  *
  * Please note that since version 2.24 the GObject initialization
  * function g_type_init() initializes threads (with a %NULL argument),
- * so most applications, including those using Gtk+ will run with
+ * so most applications, including those using GTK+ will run with
  * threads enabled. If you want a special thread implementation, make
  * sure you call g_thread_init() before g_type_init() is called.
  *
@@ -133,7 +133,7 @@
  * G_THREADS_ENABLED:
  *
  * This macro is defined, for backward compatibility, to indicate that
- * GLib has been compiled with thread support. As of glib 2.28, it is
+ * GLib has been compiled with thread support. As of GLib 2.28, it is
  * always defined.
  **/
 
@@ -439,7 +439,7 @@ gboolean g_threads_got_initialized = FALSE;
  *   int
  *   give_me_next_number (void)
  *   {
- *     static GMutex mutex = G_MUTEX_INITIALIZER;
+ *     static GMutex mutex = G_MUTEX_INIT;
  *     static int current_number = 0;
  *     int ret_val;
  *
@@ -452,7 +452,8 @@ gboolean g_threads_got_initialized = FALSE;
  *  </programlisting>
  * </example>
  *
- * A #GMutex should only be accessed via the following functions.
+ * A #GMutex should only be accessed via <function>g_mutex_</function>
+ * functions.
  **/
 
 /* GCond Virtual Functions {{{2 ------------------------------------------ */
@@ -880,6 +881,7 @@ g_once_init_leave (volatile gsize *value_location,
  * GStaticMutex:
  *
  * A #GStaticMutex works like a #GMutex.
+ *
  * Prior to GLib 2.32, GStaticMutex had the significant advantage
  * that it doesn't need to be created at run-time, but can be defined
  * at compile-time. Since 2.32, #GMutex can be statically allocated
@@ -1898,7 +1900,7 @@ g_thread_join (GThread* thread)
  * This function does nothing.
  *
  * Deprecated:2.32: Thread priorities no longer have any effect.
- **/
+ */
 void
 g_thread_set_priority (GThread         *thread,
                        GThreadPriority  priority)
@@ -2024,6 +2026,8 @@ g_thread_self (void)
  * keep the lock for a considerable time justify a #GStaticRWLock. The
  * above example most probably would fare better with a
  * #GStaticMutex.</para></note>
+ *
+ * Deprecated: 2.32: Use a #GRWLock instead
  **/
 
 /**
@@ -2046,7 +2050,9 @@ g_thread_self (void)
  * A #GStaticRWLock must be initialized with this function before it
  * can be used. Alternatively you can initialize it with
  * #G_STATIC_RW_LOCK_INIT.
- **/
+ *
+ * Deprecated: 2.32: Use g_rw_lock_init() instead
+ */
 void
 g_static_rw_lock_init (GStaticRWLock* lock)
 {
@@ -2089,7 +2095,9 @@ g_static_rw_lock_signal (GStaticRWLock* lock)
  * #GStaticRWLock is not recursive. It might seem to be possible to
  * recursively lock for reading, but that can result in a deadlock, due
  * to writer preference.
- **/
+ *
+ * Deprecated: 2.32: Use g_rw_lock_reader_lock() instead
+ */
 void
 g_static_rw_lock_reader_lock (GStaticRWLock* lock)
 {
@@ -2117,7 +2125,9 @@ g_static_rw_lock_reader_lock (GStaticRWLock* lock)
  * lock @lock for writing, immediately returns %FALSE. Otherwise locks
  * @lock for reading and returns %TRUE. This lock has to be unlocked by
  * g_static_rw_lock_reader_unlock().
- **/
+ *
+ * Deprectated: 2.32: Use g_rw_lock_reader_trylock() instead
+ */
 gboolean
 g_static_rw_lock_reader_trylock (GStaticRWLock* lock)
 {
@@ -2145,7 +2155,9 @@ g_static_rw_lock_reader_trylock (GStaticRWLock* lock)
  * Unlocks @lock. If a thread waits to lock @lock for writing and all
  * locks for reading have been unlocked, the waiting thread is woken up
  * and can lock @lock for writing.
- **/
+ *
+ * Deprectated: 2.32: Use g_rw_lock_reader_unlock() instead
+ */
 void
 g_static_rw_lock_reader_unlock  (GStaticRWLock* lock)
 {
@@ -2172,7 +2184,9 @@ g_static_rw_lock_reader_unlock  (GStaticRWLock* lock)
  * reading. When @lock is locked for writing, no other thread can lock
  * @lock (neither for reading nor writing). This lock has to be
  * unlocked by g_static_rw_lock_writer_unlock().
- **/
+ *
+ * Deprectated: 2.32: Use g_rw_lock_writer_lock() instead
+ */
 void
 g_static_rw_lock_writer_lock (GStaticRWLock* lock)
 {
@@ -2199,7 +2213,9 @@ g_static_rw_lock_writer_lock (GStaticRWLock* lock)
  * either reading or writing) by another thread, it immediately returns
  * %FALSE. Otherwise it locks @lock for writing and returns %TRUE. This
  * lock has to be unlocked by g_static_rw_lock_writer_unlock().
- **/
+ *
+ * Deprectated: 2.32: Use g_rw_lock_writer_trylock() instead
+ */
 gboolean
 g_static_rw_lock_writer_trylock (GStaticRWLock* lock)
 {
@@ -2230,7 +2246,9 @@ g_static_rw_lock_writer_trylock (GStaticRWLock* lock)
  * lock @lock for writing, and some thread or threads are waiting to
  * lock @lock for reading, the waiting threads are woken up and can
  * lock @lock for reading.
- **/
+ *
+ * Deprectated: 2.32: Use g_rw_lock_writer_unlock() instead
+ */
 void
 g_static_rw_lock_writer_unlock (GStaticRWLock* lock)
 {
@@ -2255,7 +2273,9 @@ g_static_rw_lock_writer_unlock (GStaticRWLock* lock)
  * unbounded lifetime, i.e. objects declared 'static', but if you have
  * a #GStaticRWLock as a member of a structure, and the structure is
  * freed, you should also free the #GStaticRWLock.
- **/
+ *
+ * Deprecated: 2.32: Use a #GRWLock instead
+ */
 void
 g_static_rw_lock_free (GStaticRWLock* lock)
 {
@@ -2340,7 +2360,7 @@ g_thread_get_initialized ()
 /**
  * g_mutex_new:
  *
- * Creates a new #GMutex.
+ * Allocated and initializes a new #GMutex.
  *
  * Returns: a newly allocated #GMutex. Use g_mutex_free() to free
  */
@@ -2361,8 +2381,8 @@ g_mutex_new (void)
  *
  * Destroys a @mutex that has been created with g_mutex_new().
  *
- * <note>Calling g_mutex_free() on a locked mutex may result
- * in undefined behaviour.</note>
+ * Calling g_mutex_free() on a locked mutex may result
+ * in undefined behaviour.
  */
 void
 g_mutex_free (GMutex *mutex)
@@ -2374,7 +2394,7 @@ g_mutex_free (GMutex *mutex)
 /**
  * g_cond_new:
  *
- * Creates a new #GCond.
+ * Allocates and initializes a new #GCond.
  *
  * Returns: a newly allocated #GCond. Free with g_cond_free()
  */
@@ -2463,3 +2483,5 @@ GThreadFunctions g_thread_functions_for_glib_use =
   NULL,
   NULL,
 };
+
+/* vim: set foldmethod=marker: */