[glib: 1/2] Make clear in doc that signals are emitted synchroniously

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

commit 28d833a0752a5f875833e34540248c718f234d83
Author: Alexander Schwinn <al schwinn gsi de>
Date:   Tue Jan 18 08:53:20 2022 +0000

    Make clear in doc that signals are emitted synchroniously

 docs/reference/gobject/tut_gsignal.xml | 10 +++++-----
 gobject/gsignal.c                      | 12 ++++++++----
 gobject/gsignal.h                      |  4 ++--
 3 files changed, 15 insertions(+), 11 deletions(-)
---
diff --git a/docs/reference/gobject/tut_gsignal.xml b/docs/reference/gobject/tut_gsignal.xml
index 4ed4211fa..5559673cb 100644
--- a/docs/reference/gobject/tut_gsignal.xml
+++ b/docs/reference/gobject/tut_gsignal.xml
@@ -187,10 +187,10 @@ g_cclosure_marshal_VOID__INT (GClosure     *closure,
     <para>
       Each signal is registered in the type system together with the type on which
       it can be emitted: users of the type are said to <emphasis>connect</emphasis>
-      to the signal on a given type instance when they register a closure to be 
-      invoked upon the signal emission. Users can also emit the signal by themselves 
-      or stop the emission of the signal from within one of the closures connected 
-      to the signal.
+      to the signal on a given type instance when they register a closure to be  
+      invoked upon the signal emission. The closure will be called synchronously on emission.
+      Users can also emit the signal by themselves or stop the emission of the signal from
+      within one of the closures connected to the signal.
     </para>
 
     <para>
@@ -352,7 +352,7 @@ void g_signal_emitv (const GValue *instance_and_params,
                </para>
 
          <para>
-               Signal emission can be decomposed in 5 steps:
+               Signal emission is done synchronously and can be decomposed in 5 steps:
                <orderedlist>
                  <listitem><para>
                        <literal>RUN_FIRST</literal>: if the
diff --git a/gobject/gsignal.c b/gobject/gsignal.c
index 9cabacd15..df6c3e39f 100644
--- a/gobject/gsignal.c
+++ b/gobject/gsignal.c
@@ -3117,7 +3117,8 @@ g_signal_has_handler_pending (gpointer instance,
  * store the return value of the signal emission. This must be provided if the
  * specified signal returns a value, but may be ignored otherwise.
  *
- * Emits a signal.
+ * Emits a signal. Signal emission is done synchronously.
+ * The method will only return control after all handlers are called or signal emission was stopped.
  *
  * Note that g_signal_emitv() doesn't change @return_value if no handlers are
  * connected, in contrast to g_signal_emit() and g_signal_emit_valist().
@@ -3255,7 +3256,8 @@ accumulate (GSignalInvocationHint *ihint,
  *  location for the return value. If the return type of the signal
  *  is #G_TYPE_NONE, the return value location can be omitted.
  *
- * Emits a signal.
+ * Emits a signal. Signal emission is done synchronously.
+ * The method will only return control after all handlers are called or signal emission was stopped.
  *
  * Note that g_signal_emit_valist() resets the return value to the default
  * if no handlers are connected, in contrast to g_signal_emitv().
@@ -3534,7 +3536,8 @@ g_signal_emit_valist (gpointer instance,
  *  location for the return value. If the return type of the signal
  *  is #G_TYPE_NONE, the return value location can be omitted.
  *
- * Emits a signal.
+ * Emits a signal. Signal emission is done synchronously.
+ * The method will only return control after all handlers are called or signal emission was stopped.
  *
  * Note that g_signal_emit() resets the return value to the default
  * if no handlers are connected, in contrast to g_signal_emitv().
@@ -3561,7 +3564,8 @@ g_signal_emit (gpointer instance,
  *  is %G_TYPE_NONE, the return value location can be omitted. The
  *  number of parameters to pass to this function is defined when creating the signal.
  *
- * Emits a signal.
+ * Emits a signal. Signal emission is done synchronously.
+ * The method will only return control after all handlers are called or signal emission was stopped.
  *
  * Note that g_signal_emit_by_name() resets the return value to the default
  * if no handlers are connected, in contrast to g_signal_emitv().
diff --git a/gobject/gsignal.h b/gobject/gsignal.h
index 96e4eb38a..7e83924f6 100644
--- a/gobject/gsignal.h
+++ b/gobject/gsignal.h
@@ -497,7 +497,7 @@ void   g_signal_chain_from_overridden_handler (gpointer           instance,
  * 
  * Connects a #GCallback function to a signal for a particular object.
  * 
- * The handler will be called before the default handler of the signal.
+ * The handler will be called synchronously, before the default handler of the signal. g_signal_emit() will 
not return control until all handlers are called.
  *
  * See [memory management of signal handlers][signal-memory-management] for
  * details on how to handle the return value and memory management of @data.
@@ -515,7 +515,7 @@ void   g_signal_chain_from_overridden_handler (gpointer           instance,
  * 
  * Connects a #GCallback function to a signal for a particular object.
  * 
- * The handler will be called after the default handler of the signal.
+ * The handler will be called synchronously, after the default handler of the signal.
  * 
  * Returns: the handler ID, of type #gulong (always greater than 0 for successful connections)
  */