[glib] gmain: Document more use cases of g_main_context_wakeup()

[Benjamin Otte <otte src gnome org>]

commit 9d9532bdd358a38c1b878be91702af5a8b82a5aa
Author: Colin Walters <walters verbum org>
Date:   Mon Jun 10 13:17:08 2013 -0400

    gmain: Document more use cases of g_main_context_wakeup()
    
    https://bugzilla.gnome.org/show_bug.cgi?id=701878

 glib/gmain.c |   30 ++++++++++++++++++++++++++++--
 1 files changed, 28 insertions(+), 2 deletions(-)
---
diff --git a/glib/gmain.c b/glib/gmain.c
index d6037ba..cf219fe 100644
--- a/glib/gmain.c
+++ b/glib/gmain.c
@@ -4307,8 +4307,34 @@ g_main_context_get_poll_func (GMainContext *context)
  * g_main_context_wakeup:
  * @context: a #GMainContext
  * 
- * If @context is currently waiting in a poll(), interrupt
- * the poll(), and continue the iteration process.
+ * If @context is currently blocking in g_main_context_iteration()
+ * waiting for a source to become ready, cause it to stop blocking
+ * and return.  Otherwise, cause the next invocation of
+ * g_main_context_iteration() to return without blocking.
+ *
+ * This API is useful for low-level control over #GMainContext; for
+ * example, integrating it with main loop implementations such as
+ * #GMainLoop.
+ *
+ * Another related use for this function is when implementing a main
+ * loop with a termination condition, computed from multiple threads:
+ *
+ * |[
+ *   #define NUM_TASKS 10
+ *   static volatile gint tasks_remaining = NUM_TASKS;
+ *   ...
+ *  
+ *   while (g_atomic_int_get (&tasks_remaining) != 0)
+ *     g_main_context_iteration (NULL, TRUE);
+ * ]|
+ *  
+ * Then in a thread:
+ * |[
+ *   perform_work();
+ *
+ *   if (g_atomic_int_dec_and_test (&tasks_remaining))
+ *     g_main_context_wakeup (NULL);
+ * ]|
  **/
 void
 g_main_context_wakeup (GMainContext *context)