[glib] gmain: Explicitly document the threading behaviour of g_timeout_add()

[Philip Withnall <pwithnall src gnome org>]

commit 8df6e5fa3ffeb74739d5d914669c7e245a84e46d
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Fri Dec 19 15:33:59 2014 +0000

    gmain: Explicitly document the threading behaviour of g_timeout_add()
    
    i.e. That calling g_timeout_add() from a thread other than the main one
    probably doesn’t do what you want. Same for g_idle_add() and the
    *_full() variants.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=741779

 glib/gmain.c |   24 ++++++++++++++++--------
 1 files changed, 16 insertions(+), 8 deletions(-)
---
diff --git a/glib/gmain.c b/glib/gmain.c
index e20128a..d5661bb 100644
--- a/glib/gmain.c
+++ b/glib/gmain.c
@@ -4636,8 +4636,10 @@ g_timeout_source_new_seconds (guint interval)
  * (it does not try to 'catch up' time lost in delays).
  *
  * This internally creates a main loop source using g_timeout_source_new()
- * and attaches it to the main loop context using g_source_attach(). You can
- * do these steps manually if you need greater control.
+ * and attaches it to the global #GMainContext using g_source_attach(), so
+ * the callback will be invoked in whichever thread is running that main
+ * context. You can do these steps manually if you need greater control or to
+ * use a custom main context.
  *
  * The interval given in terms of monotonic time, not wall clock time.
  * See g_get_monotonic_time().
@@ -4694,8 +4696,10 @@ g_timeout_add_full (gint           priority,
  * optimizations and more efficient system power usage.
  *
  * This internally creates a main loop source using g_timeout_source_new()
- * and attaches it to the main loop context using g_source_attach(). You can
- * do these steps manually if you need greater control.
+ * and attaches it to the global #GMainContext using g_source_attach(), so
+ * the callback will be invoked in whichever thread is running that main
+ * context. You can do these steps manually if you need greater control or to
+ * use a custom main context.
  * 
  * The interval given is in terms of monotonic time, not wall clock
  * time.  See g_get_monotonic_time().
@@ -5429,8 +5433,10 @@ g_idle_source_new (void)
  * removed from the list of event sources and will not be called again.
  * 
  * This internally creates a main loop source using g_idle_source_new()
- * and attaches it to the main loop context using g_source_attach(). 
- * You can do these steps manually if you need greater control.
+ * and attaches it to the global #GMainContext using g_source_attach(), so
+ * the callback will be invoked in whichever thread is running that main
+ * context. You can do these steps manually if you need greater control or to
+ * use a custom main context.
  * 
  * Returns: the ID (greater than 0) of the event source.
  * Rename to: g_idle_add
@@ -5470,8 +5476,10 @@ g_idle_add_full (gint           priority,
  * sources and will not be called again.
  * 
  * This internally creates a main loop source using g_idle_source_new()
- * and attaches it to the main loop context using g_source_attach(). 
- * You can do these steps manually if you need greater control.
+ * and attaches it to the global #GMainContext using g_source_attach(), so
+ * the callback will be invoked in whichever thread is running that main
+ * context. You can do these steps manually if you need greater control or to
+ * use a custom main context.
  * 
  * Returns: the ID (greater than 0) of the event source.
  **/