[glib: 15/17] gdbusconnection: Document main context iteration for unsubscriptions

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

commit ab285899a6fb611f43c7dec4022e869b10124bae
Author: Philip Withnall <withnall endlessm com>
Date:   Fri Feb 21 15:12:08 2020 +0000

    gdbusconnection: Document main context iteration for unsubscriptions
    
    Add a note to the documentation of
    `g_dbus_connection_signal_unsubscribe()`, `g_bus_unwatch_name()` and
    `g_bus_unown_name()` warning about the need to continue iterating the
    caller’s thread-default `GMainContext` until the
    unsubscribe/unwatch/unown operation is complete.
    
    See the previous few commits and #1515 for an idea of the insidious bugs
    that can be caused by not iterating the `GMainContext` until
    everything’s synchronised.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>

 gio/gdbusconnection.c   | 8 ++++++++
 gio/gdbusnameowning.c   | 7 +++++++
 gio/gdbusnamewatching.c | 7 +++++++
 3 files changed, 22 insertions(+)
---
diff --git a/gio/gdbusconnection.c b/gio/gdbusconnection.c
index b58b1b4a3..1a4dae3bd 100644
--- a/gio/gdbusconnection.c
+++ b/gio/gdbusconnection.c
@@ -3694,6 +3694,14 @@ unsubscribe_id_internal (GDBusConnection *connection,
  *
  * Unsubscribes from signals.
  *
+ * Note that there may still be D-Bus traffic to process (relating to this
+ * signal subscription) in the current thread-default #GMainContext after this
+ * function has returned. You should continue to iterate the #GMainContext
+ * until the #GDestroyNotify function passed to
+ * g_dbus_connection_signal_subscribe() is called, in order to avoid memory
+ * leaks through callbacks queued on the #GMainContext after it’s stopped being
+ * iterated.
+ *
  * Since: 2.26
  */
 void
diff --git a/gio/gdbusnameowning.c b/gio/gdbusnameowning.c
index ee7d8445f..d20e6ffed 100644
--- a/gio/gdbusnameowning.c
+++ b/gio/gdbusnameowning.c
@@ -889,6 +889,13 @@ g_bus_own_name_on_connection_with_closures (GDBusConnection    *connection,
  *
  * Stops owning a name.
  *
+ * Note that there may still be D-Bus traffic to process (relating to owning
+ * and unowning the name) in the current thread-default #GMainContext after
+ * this function has returned. You should continue to iterate the #GMainContext
+ * until the #GDestroyNotify function passed to g_bus_own_name() is called, in
+ * order to avoid memory leaks through callbacks queued on the #GMainContext
+ * after it’s stopped being iterated.
+ *
  * Since: 2.26
  */
 void
diff --git a/gio/gdbusnamewatching.c b/gio/gdbusnamewatching.c
index c103bb484..bc2a9119e 100644
--- a/gio/gdbusnamewatching.c
+++ b/gio/gdbusnamewatching.c
@@ -858,6 +858,13 @@ guint g_bus_watch_name_on_connection_with_closures (
  *
  * Stops watching a name.
  *
+ * Note that there may still be D-Bus traffic to process (relating to watching
+ * and unwatching the name) in the current thread-default #GMainContext after
+ * this function has returned. You should continue to iterate the #GMainContext
+ * until the #GDestroyNotify function passed to g_bus_watch_name() is called, in
+ * order to avoid memory leaks through callbacks queued on the #GMainContext
+ * after it’s stopped being iterated.
+ *
  * Since: 2.26
  */
 void