[glib] Cleanup thread documentation

From: Ryan Lortie <ryanl src gnome org>
To: commits-list gnome org
Cc:
Subject: [glib] Cleanup thread documentation
Date: Thu, 6 Oct 2011 16:02:04 +0000 (UTC)
commit 94b7d2ee6cb9f1e0416c82e2bf0615fd2d0c848a
Author: Ryan Lortie <desrt desrt ca>
Date:   Thu Oct 6 12:01:53 2011 -0400

    Cleanup thread documentation

 docs/reference/glib/Makefile.am        |    3 +
 docs/reference/glib/glib-docs.sgml     |    9 ++-
 docs/reference/glib/glib-overrides.txt |    2 +-
 docs/reference/glib/glib-sections.txt  |   92 +++++++++++++++--------------
 glib/deprecated/gthread-deprecated.c   |   18 ++++++
 glib/gthread-posix.c                   |   40 +++++++------
 glib/gthread.c                         |  101 +++++--------------------------
 7 files changed, 114 insertions(+), 151 deletions(-)
---
diff --git a/docs/reference/glib/Makefile.am b/docs/reference/glib/Makefile.am
index ee67a19..aee0baa 100644
--- a/docs/reference/glib/Makefile.am
+++ b/docs/reference/glib/Makefile.am
@@ -24,10 +24,13 @@ CFILE_GLOB=$(top_srcdir)/glib/*.c $(top_srcdir)/gmodule/*.c
 
 # Ignore some private headers
 IGNORE_HFILES = \
+	gallocator.h		\
 	gdatasetprivate.h	\
 	glibintl.h		\
 	gbsearcharray.h		\
+	glib-private.h		\
 	gmoduleconf.h		\
+	gthreadprivate.h	\
 	gunibreak.h		\
 	gunicomp.h		\
 	gunidecomp.h		\
diff --git a/docs/reference/glib/glib-docs.sgml b/docs/reference/glib/glib-docs.sgml
index 1ac4d5d..b58f633 100644
--- a/docs/reference/glib/glib-docs.sgml
+++ b/docs/reference/glib/glib-docs.sgml
@@ -83,7 +83,6 @@ synchronize their operation.
       <xi:include href="xml/hooks.xml" />
       <xi:include href="xml/misc_utils.xml" />
       <xi:include href="xml/scanner.xml" />
-      <xi:include href="xml/completion.xml" />
       <xi:include href="xml/timers.xml" />
       <xi:include href="xml/spawn.xml" />
       <xi:include href="xml/fileutils.xml" />
@@ -120,7 +119,6 @@ synchronize their operation.
       <xi:include href="xml/quarks.xml" />
       <xi:include href="xml/datalist.xml" />
       <xi:include href="xml/datasets.xml" />
-      <xi:include href="xml/relations.xml" />
       <xi:include href="xml/caches.xml" />
       <xi:include href="xml/gvarianttype.xml"/>
       <xi:include href="xml/gvariant.xml"/>
@@ -128,6 +126,13 @@ synchronize their operation.
       <xi:include href="gvariant-text.xml"/>
   </chapter>
 
+  <chapter id="deprecated">
+      <title>Deprecated APIs</title>
+      <xi:include href="xml/threads-deprecated.xml"/>
+      <xi:include href="xml/relations.xml" />
+      <xi:include href="xml/completion.xml" />
+  </chapter>
+
   <chapter id="tools">
     <title>GLib Tools</title>
     <xi:include href="glib-gettextize.xml" />
diff --git a/docs/reference/glib/glib-overrides.txt b/docs/reference/glib/glib-overrides.txt
index 7d9d1c7..40adade 100644
--- a/docs/reference/glib/glib-overrides.txt
+++ b/docs/reference/glib/glib-overrides.txt
@@ -9,7 +9,7 @@
 </MACRO>
 
 <MACRO>
-<NAME>G_THREADS_IMPL_NONE</NAME>
+<NAME>G_THREADS_IMPL_WIN32</NAME>
 #define G_THREADS_IMPL_NONE
 </MACRO>
 
diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index 540265b..96bc090 100644
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -572,25 +572,17 @@ g_child_watch_funcs
 GSourcePrivate
 </SECTION>
 
+
 <SECTION>
 <TITLE>Threads</TITLE>
 <FILE>threads</FILE>
 <SUBSECTION>
-G_THREADS_IMPL_POSIX
-G_THREADS_IMPL_WIN32
-
-<SUBSECTION>
 G_THREAD_ERROR
 GThreadError
 
 <SUBSECTION>
-g_thread_init
-g_thread_supported
-g_thread_get_initialized
-
-<SUBSECTION>
-GThreadFunc
 GThread
+GThreadFunc
 g_thread_new
 g_thread_new_full
 g_thread_self
@@ -598,32 +590,23 @@ g_thread_join
 g_thread_yield
 g_thread_exit
 
-<SUBSECTION Deprecated>
-g_thread_create
-g_thread_create_full
-GThreadPriority
-g_thread_set_priority
-g_thread_foreach
+<SUBSECTION>
+G_LOCK_DEFINE
+G_LOCK_DEFINE_STATIC
+G_LOCK_EXTERN
+G_LOCK
+G_TRYLOCK
+G_UNLOCK
 
 <SUBSECTION>
 GMutex
 g_mutex_init
 g_mutex_clear
-g_mutex_new
-g_mutex_free
 g_mutex_lock
 g_mutex_trylock
 g_mutex_unlock
 
 <SUBSECTION>
-G_LOCK_DEFINE
-G_LOCK_DEFINE_STATIC
-G_LOCK_EXTERN
-G_LOCK
-G_TRYLOCK
-G_UNLOCK
-
-<SUBSECTION>
 GRecMutex
 g_rec_mutex_init
 g_rec_mutex_clear
@@ -644,8 +627,6 @@ g_rw_lock_reader_unlock
 
 <SUBSECTION>
 GCond
-g_cond_new
-g_cond_free
 g_cond_init
 g_cond_clear
 g_cond_wait
@@ -661,9 +642,6 @@ g_private_get
 g_private_set
 g_private_replace
 
-<SUBSECTION Deprecated>
-g_private_new
-
 <SUBSECTION>
 GOnce
 GOnceStatus
@@ -680,7 +658,41 @@ g_pointer_bit_lock
 g_pointer_bit_trylock
 g_pointer_bit_unlock
 
-<SUBSECTION Deprecated>
+<SUBSECTION Private>
+G_LOCK_NAME
+atexit
+g_thread_error_quark
+g_once_impl
+</SECTION>
+
+<SECTION>
+<TITLE>Deprecated Thread APIs</TITLE>
+<FILE>threads-deprecated</FILE>
+
+<SUBSECTION>
+G_THREADS_IMPL_POSIX
+G_THREADS_IMPL_WIN32
+
+<SUBSECTION>
+g_thread_init
+g_thread_supported
+g_thread_get_initialized
+
+<SUBSECTION>
+g_thread_create
+g_thread_create_full
+GThreadPriority
+g_thread_set_priority
+g_thread_foreach
+
+<SUBSECTION>
+g_mutex_new
+g_mutex_free
+g_cond_new
+g_cond_free
+g_private_new
+
+<SUBSECTION>
 GStaticMutex
 G_STATIC_MUTEX_INIT
 g_static_mutex_init
@@ -690,7 +702,7 @@ g_static_mutex_unlock
 g_static_mutex_get_mutex
 g_static_mutex_free
 
-<SUBSECTION Deprecated>
+<SUBSECTION>
 GStaticRecMutex
 G_STATIC_REC_MUTEX_INIT
 g_static_rec_mutex_init
@@ -701,7 +713,7 @@ g_static_rec_mutex_lock_full
 g_static_rec_mutex_unlock_full
 g_static_rec_mutex_free
 
-<SUBSECTION Deprecated>
+<SUBSECTION>
 GStaticRWLock
 G_STATIC_RW_LOCK_INIT
 g_static_rw_lock_init
@@ -713,7 +725,7 @@ g_static_rw_lock_writer_trylock
 g_static_rw_lock_writer_unlock
 g_static_rw_lock_free
 
-<SUBSECTION Deprecated>
+<SUBSECTION>
 GStaticPrivate
 G_STATIC_PRIVATE_INIT
 g_static_private_init
@@ -725,22 +737,12 @@ g_static_private_free
 GThreadFunctions
 G_THREADS_ENABLED
 g_static_mutex_get_mutex_impl
-g_static_mutex_get_mutex_impl_shortcut
-G_LOCK_NAME
-glib_dummy_decl
 GSystemThread
 g_thread_use_default_impl
 g_threads_got_initialized
 g_thread_functions_for_glib_use
 g_thread_gettime
-g_thread_init_glib
-g_thread_error_quark
-g_once_impl
 g_once_init_enter_impl
-atexit
-g_system_thread_assign
-g_system_thread_equal
-g_system_thread_equal_simple
 </SECTION>
 
 <SECTION>
diff --git a/glib/deprecated/gthread-deprecated.c b/glib/deprecated/gthread-deprecated.c
index 2b322d6..a883434 100644
--- a/glib/deprecated/gthread-deprecated.c
+++ b/glib/deprecated/gthread-deprecated.c
@@ -74,6 +74,24 @@
  * to initialize the thread system.
  */
 
+/**
+ * G_THREADS_IMPL_POSIX:
+ *
+ * This macro is defined if POSIX style threads are used.
+ *
+ * Deprecated:2.32:POSIX threads are in use on all non-Windows systems.
+ *                 Use G_OS_WIN32 to detect Windows.
+ */
+
+/**
+ * G_THREADS_IMPL_WIN32:
+ *
+ * This macro is defined if Windows style threads are used.
+ *
+ * Deprecated:2.32:Use G_OS_WIN32 to detect Windows.
+ */
+
+
 /* {{{1 Exported Variables */
 
 gboolean g_thread_use_default_impl = TRUE;
diff --git a/glib/gthread-posix.c b/glib/gthread-posix.c
index 1788a0f..9e86179 100644
--- a/glib/gthread-posix.c
+++ b/glib/gthread-posix.c
@@ -139,7 +139,7 @@ g_mutex_get_impl (GMutex *mutex)
  * 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() or that has been statically allocated.
+ * created that has been statically allocated.
  *
  * |[
  *   typedef struct {
@@ -173,8 +173,8 @@ g_mutex_init (GMutex *mutex)
  *
  * Frees the resources allocated to a mutex with g_mutex_init().
  *
- * #GMutexes that have have been created with g_mutex_new() should
- * be freed with g_mutex_free() instead.
+ * This function should not be used with a #GMutex that has been
+ * statically allocated.
  *
  * Calling g_mutex_clear() on a locked mutex leads to undefined
  * behaviour.
@@ -199,9 +199,9 @@ g_mutex_clear (GMutex *mutex)
  * called, and, in that case, will do nothing.
  *
  * <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
- * #GRecMutex if you need recursive mutexes.</note>
+ * non-recursive.  As such, calling g_mutex_lock() on a #GMutex that has
+ * already been locked by the same thread results in undefined behaviour
+ * (including but not limited to deadlocks).</note>
  */
 void
 g_mutex_lock (GMutex *mutex)
@@ -246,9 +246,10 @@ g_mutex_unlock (GMutex *mutex)
  * called, and, in that case, will immediately return %TRUE.
  *
  * <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 #GRecMutex if you need recursive mutexes.</note>
+ * non-recursive.  As such, calling g_mutex_lock() on a #GMutex that has
+ * already been locked by the same thread results in undefined behaviour
+ * (including but not limited to deadlocks or arbitrary return values).
+ * </note>
 
  * Returns: %TRUE if @mutex could be locked
  */
@@ -315,9 +316,9 @@ g_rec_mutex_get_impl (GRecMutex *rec_mutex)
  * 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(). It is not necessary to
- * initialise a recursive mutex that has been statically allocated.
+ *
+ * It is not necessary to initialise a recursive mutex that has been
+ * statically allocated.
  *
  * |[
  *   typedef struct {
@@ -352,8 +353,8 @@ g_rec_mutex_init (GRecMutex *rec_mutex)
  * 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.
+ * This function should not be used with a #GRecMutex that has been
+ * statically allocated.
  *
  * Calling g_rec_mutex_clear() on a locked recursive mutex leads
  * to undefined behaviour.
@@ -509,6 +510,9 @@ g_rw_lock_init (GRWLock *rw_lock)
  *
  * Frees the resources allocated to a lock with g_rw_lock_init().
  *
+ * This function should not be used with a #GRWLock that has been
+ * statically allocated.
+ *
  * Calling g_rw_lock_clear() when any thread holds the lock
  * leads to undefined behaviour.
  *
@@ -681,7 +685,7 @@ g_cond_get_impl (GCond *cond)
  * 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() or that has been statically allocated.
+ * statically allocated.
  *
  * To undo the effect of g_cond_init() when a #GCond is no longer
  * needed, use g_cond_clear().
@@ -703,8 +707,8 @@ g_cond_init (GCond *cond)
  *
  * 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.
+ * This function should not be used with a #GCond that has been
+ * statically allocated.
  *
  * Calling g_cond_clear() for a #GCond on which threads are
  * blocking leads to undefined behaviour.
@@ -1116,8 +1120,6 @@ g_system_thread_create (GThreadFunc       thread_func,
  * that other threads can run.
  *
  * This function is often used as a method to make busy wait less evil.
- * But in most cases you will encounter, there are better methods to do
- * that. So in general you shouldn't use this function.
  */
 void
 g_thread_yield (void)
diff --git a/glib/gthread.c b/glib/gthread.c
index 7ee385f..dcb0add 100644
--- a/glib/gthread.c
+++ b/glib/gthread.c
@@ -106,18 +106,6 @@
  * are also thread-safe.
  */
 
-/**
- * G_THREADS_IMPL_POSIX:
- *
- * This macro is defined if POSIX style threads are used.
- */
-
-/**
- * G_THREADS_IMPL_WIN32:
- *
- * This macro is defined if Windows style threads are used.
- */
-
 /* G_LOCK Documentation {{{1 ---------------------------------------------- */
 
 /**
@@ -224,75 +212,10 @@
  *
  * It is easy to see that this won't work in a multi-threaded
  * application. There current_number must be protected against shared
- * access. A first naive implementation would be:
+ * access. A #GMutex can be used as a solution to this problem:
  *
  * <example>
- *  <title>The wrong way to write a thread-safe function</title>
- *  <programlisting>
- *   int
- *   give_me_next_number (void)
- *   {
- *     static int current_number = 0;
- *     int ret_val;
- *     static GMutex * mutex = NULL;
- *
- *     if (!mutex) mutex = g_mutex_new (<!-- -->);
- *
- *     g_mutex_lock (mutex);
- *     ret_val = current_number = calc_next_number (current_number);
- *     g_mutex_unlock (mutex);
- *
- *     return ret_val;
- *   }
- *  </programlisting>
- * </example>
- *
- * This looks like it would work, but there is a race condition while
- * constructing the mutex and this code cannot work reliable. Please do
- * not use such constructs in your own programs! One working solution
- * is:
- *
- * <example>
- *  <title>A correct thread-safe function</title>
- *  <programlisting>
- *   static GMutex *give_me_next_number_mutex = NULL;
- *
- *   /<!-- -->* this function must be called before any call to
- *    * give_me_next_number(<!-- -->)
- *    *
- *    * it must be called exactly once.
- *    *<!-- -->/
- *   void
- *   init_give_me_next_number (void)
- *   {
- *     g_assert (give_me_next_number_mutex == NULL);
- *     give_me_next_number_mutex = g_mutex_new (<!-- -->);
- *   }
- *
- *   int
- *   give_me_next_number (void)
- *   {
- *     static int current_number = 0;
- *     int ret_val;
- *
- *     g_mutex_lock (give_me_next_number_mutex);
- *     ret_val = current_number = calc_next_number (current_number);
- *     g_mutex_unlock (give_me_next_number_mutex);
- *
- *     return ret_val;
- *   }
- *  </programlisting>
- * </example>
- *
- * If a #GMutex is allocated in static storage then it can be used
- * without initialisation.  Otherwise, you should call g_mutex_init() on
- * it and g_mutex_clear() when done.
- *
- * A statically initialized #GMutex provides an even simpler and safer
- * way of doing this:
- *
- * <example>
- *  <title>Using a statically allocated mutex</title>
+ *  <title>Using GMutex to protected a shared variable</title>
  *  <programlisting>
  *   int
  *   give_me_next_number (void)
@@ -310,6 +233,13 @@
  *  </programlisting>
  * </example>
  *
+ * Notice that the #GMutex is not initialised to any particular value.
+ * Its placement in static storage ensures that it will be initialised
+ * to all-zeros, which is appropriate.
+ *
+ * If a #GMutex is placed in other contexts (eg: embedded in a struct)
+ * then it must be explicitly initialised using g_mutex_init().
+ *
  * A #GMutex should only be accessed via <function>g_mutex_</function>
  * functions.
  */
@@ -485,6 +415,9 @@
  * is returned by g_thread_new() or g_thread_new_full(). You can
  * obtain the #GThread struct representing the current thead by
  * calling g_thread_self().
+ *
+ * The structure is opaque -- none of its fields may be directly
+ * accessed.
  */
 
 /**
@@ -789,15 +722,15 @@ g_thread_create_proxy (gpointer data)
  * @joinable: should this thread be joinable?
  * @error: return location for error
  *
- * This function creates a new thread. The new thread starts by
- * invoking @func with the argument data. The thread will run
- * until @func returns or until g_thread_exit() is called.
+ * This function creates a new thread. The new thread starts by invoking
+ * @func with the argument data. The thread will run until @func returns
+ * or until g_thread_exit() is called from the new thread.
  *
  * The @name can be useful for discriminating threads in
  * a debugger. Some systems restrict the length of @name to
  * 16 bytes.
  *
- * If @joinable is %TRUE, you can wait for this threads termination
+ * If @joinable is %TRUE, you can wait for this thread's termination
  * calling g_thread_join(). Resources for a joinable thread are not
  * fully released until g_thread_join() is called for that thread.
  * Otherwise the thread will just disappear when it terminates.
@@ -843,7 +776,7 @@ g_thread_new (const gchar  *name,
  * In most cases, using g_thread_new() (which doesn't take a
  * @stack_size) is better.
  *
- * If @joinable is %TRUE, you can wait for this threads termination
+ * If @joinable is %TRUE, you can wait for this thread's termination
  * calling g_thread_join(). Resources for a joinable thread are not
  * fully released until g_thread_join() is called for that thread.
  * Otherwise the thread will just disappear when it terminates.
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]