Merge branch 'doc_sync_signals' into 'main'

Make clear in doc that signals are emitted synchroniously

See merge request GNOME/glib!2423

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 
+      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 
+      invoked upon the signal emission. The closure will be called synchronously on emission.
-      or stop the emission of the signal from within one of the closures connected 
+      Users can also emit the signal by themselves or stop the emission of the signal from
-      to the signal.
+      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

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().

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)
  */