[glib] gthread: Suggest using *_async() functions instead of threads

[Philip Withnall <pwithnall src gnome org>]

commit d624bf4e6673cc989f0d452c6bc2f26b526891c9
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Fri Dec 19 17:05:36 2014 +0000

    gthread: Suggest using *_async() functions instead of threads
    
    It’s unfortunately common to see worker threads being spawned all over
    the place to do operations which could be brought into the main thread
    with an async call, simplifying everything.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=741779

 glib/gthread.c |   18 ++++++++++++++++++
 1 files changed, 18 insertions(+), 0 deletions(-)
---
diff --git a/glib/gthread.c b/glib/gthread.c
index 6419006..7581829 100644
--- a/glib/gthread.c
+++ b/glib/gthread.c
@@ -140,6 +140,20 @@
  * and #GAsyncQueue, which are thread-safe and need no further
  * application-level locking to be accessed from multiple threads.
  * Most refcounting functions such as g_object_ref() are also thread-safe.
+ *
+ * A common use for #GThreads is to move a long-running blocking operation out
+ * of the main thread and into a worker thread. For GLib functions, such as
+ * single GIO operations, this is not necessary, and complicates the code.
+ * Instead, the `…_async()` version of the function should be used from the main
+ * thread, eliminating the need for locking and synchronisation between multiple
+ * threads. If an operation does need to be moved to a worker thread, consider
+ * using g_task_run_in_thread(), or a #GThreadPool. #GThreadPool is often a
+ * better choice than #GThread, as it handles thread reuse and task queueing;
+ * #GTask uses this internally.
+ *
+ * However, if multiple blocking operations need to be performed in sequence,
+ * and it is not possible to use #GTask for them, moving them to a worker thread
+ * can clarify the code.
  */
 
 /* G_LOCK Documentation {{{1 ---------------------------------------------- */
@@ -785,6 +799,10 @@ g_thread_proxy (gpointer data)
  * If the thread can not be created the program aborts. See
  * g_thread_try_new() if you want to attempt to deal with failures.
  *
+ * If you are using threads to offload (potentially many) short-lived tasks,
+ * #GThreadPool may be more appropriate than manually spawning and tracking
+ * multiple #GThreads.
+ *
  * To free the struct returned by this function, use g_thread_unref().
  * Note that g_thread_join() implicitly unrefs the #GThread as well.
  *