[glib: 1/2] gmain: Clarify thread safety of some common GSource functions

[Sebastian Dröge <sdroege src gnome org>]

commit ca4dace62bc7ee2d78ff0dc564217268aa4e0a80
Author: Philip Withnall <withnall endlessm com>
Date:   Fri Oct 25 12:07:23 2019 +0100

    gmain: Clarify thread safety of some common GSource functions
    
    See https://stackoverflow.com/q/58555626/2931197.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>

 glib/gmain.c | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)
---
diff --git a/glib/gmain.c b/glib/gmain.c
index d6c88818d..95093e727 100644
--- a/glib/gmain.c
+++ b/glib/gmain.c
@@ -115,8 +115,10 @@
  *
  * To allow multiple independent sets of sources to be handled in
  * different threads, each source is associated with a #GMainContext.
- * A GMainContext can only be running in a single thread, but
- * sources can be added to it and removed from it from other threads.
+ * A #GMainContext can only be running in a single thread, but
+ * sources can be added to it and removed from it from other threads. All
+ * functions which operate on a #GMainContext or a built-in #GSource are
+ * thread-safe.
  *
  * Each event source is assigned a priority. The default priority,
  * #G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities.
@@ -1171,6 +1173,9 @@ g_source_attach_unlocked (GSource      *source,
  * Adds a #GSource to a @context so that it will be executed within
  * that context. Remove it by calling g_source_destroy().
  *
+ * This function is safe to call from any thread, regardless of which thread
+ * the @context is running in.
+ *
  * Returns: the ID (greater than 0) for the source within the 
  *   #GMainContext. 
  **/
@@ -1267,6 +1272,9 @@ g_source_destroy_internal (GSource      *source,
  *
  * This does not unref the #GSource: if you still hold a reference, use
  * g_source_unref() to drop it.
+ *
+ * This function is safe to call from any thread, regardless of which thread
+ * the #GMainContext is running in.
  */
 void
 g_source_destroy (GSource *source)
@@ -4832,6 +4840,8 @@ g_timeout_add_full (gint           priority,
  * context. You can do these steps manually if you need greater control or to
  * use a custom main context.
  * 
+ * It is safe to call this function from any thread.
+ *
  * The interval given is in terms of monotonic time, not wall clock
  * time.  See g_get_monotonic_time().
  * 
@@ -4888,7 +4898,9 @@ g_timeout_add (guint32        interval,
  * g_timeout_source_new_seconds() and attaches it to the main loop context 
  * using g_source_attach(). You can do these steps manually if you need 
  * greater control.
- * 
+ *
+ * It is safe to call this function from any thread.
+ *
  * The interval given is in terms of monotonic time, not wall clock
  * time.  See g_get_monotonic_time().
  * 
@@ -4936,6 +4948,8 @@ g_timeout_add_seconds_full (gint           priority,
  * using g_source_attach(). You can do these steps manually if you need
  * greater control. Also see g_timeout_add_seconds_full().
  *
+ * It is safe to call this function from any thread.
+ *
  * Note that the first call of the timer may not be precise for timeouts
  * of one second. If you need finer precision and have such a timeout,
  * you may want to use g_timeout_add() instead.