docs: update g_action_group_activate_action() remote activation semantics

Refer https://gitlab.gnome.org/GNOME/glib/-/issues/2284

1 files changed, 27 insertions, 0 deletions

diff --git a/gio/gactiongroup.c b/gio/gactiongroup.c
index 24da353b0..ecd3af1c3 100644
--- a/gio/gactiongroup.c
+++ b/gio/gactiongroup.c
@@ -589,6 +589,33 @@ g_action_group_change_action_state (GActionGroup *action_group,
  * parameters then @parameter must be %NULL.  See
  * g_action_group_get_action_parameter_type().
  *
+ * If the #GActionGroup implementation supports asynchronous remote
+ * activation over D-Bus, this call may return before the relevant
+ * D-Bus traffic has been sent, or any replies have been received. In
+ * order to block on such asynchronous activation calls,
+ * g_dbus_connection_flush() should be called prior to the code, which
+ * depends on the result of the action activation. Without flushing
+ * the D-Bus connection, there is no guarantee that the action would
+ * have been activated.
+ *
+ * The following code which runs in a remote app instance, shows an
+ * example of a "quit" action being activated on the primary app
+ * instance over D-Bus. Here g_dbus_connection_flush() is called
+ * before `exit()`. Without g_dbus_connection_flush(), the "quit" action
+ * may fail to be activated on the primary instance.
+ *
+ * |[<!-- language="C" -->
+ * // call "quit" action on primary instance
+ * g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL);
+ *
+ * // make sure the action is activated now
+ * g_dbus_connection_flush (...);
+ *
+ * g_debug ("application has been terminated. exiting.");
+ *
+ * exit (0);
+ * ]|
+ *
  * Since: 2.28
  **/
 void