[glib/th/gdbus-doc-unsubscribe-idle: 89/90] gdbus: document completion after idle action for g_dbus_connection_signal_unsubscribe()

[Thomas Haller <thaller src gnome org>]

commit b0157af9a6d29eb0221d5cc746f25cd5da7a4497
Author: Thomas Haller <thaller redhat com>
Date:   Sun Apr 18 08:54:33 2021 +0200

    gdbus: document completion after idle action for g_dbus_connection_signal_unsubscribe()
    
    Since commit ab285899a6fb ('gdbusconnection: Document main context
    iteration for unsubscript'), we document when the user is guaranteed
    that all resources are gone after g_dbus_connection_signal_unsubscribe().
    This is not merely an implementation detail, it's something that the
    user needs to be able to rely on. It is good that this is documented.
    
    However, libnm does something different ([1]). It registers to several D-Bus
    signals without providing a GDestroyNotify. After unsubscription, it schedules
    another idle action with lower priority and uses that to know when
    cleanup is complete. I think this is a useful alternative and should
    also be guaranteed and documented to work.
    
    Also note that this isn't just some implementation detail that currently
    happens to work. GDBusConnection tightly integrates with GMainContext and it
    works by scheduling idle sources with G_PRIORITY_DEFAULT priority. It needs to
    schedule all events with this same priority, otherwise the ordering is not
    preserved. At this point, with GDBusConnection working this way, this is no longer
    something that can reasonably be any different. It's how GDBusConnection fundamentally
    works, and a user must be able to rely on that. As such, this new promise isn't
    something that we would want to break in the future.
    
    Thus document it.
    
    [1] 
https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/blob/a55c10c6cb0cd047ff2aa835535d2abe09507ad6/src/libnm-client-impl/nm-client.c#L7918

 gio/gdbusconnection.c | 3 +++
 1 file changed, 3 insertions(+)
---
diff --git a/gio/gdbusconnection.c b/gio/gdbusconnection.c
index 28c6795bc..7c20462eb 100644
--- a/gio/gdbusconnection.c
+++ b/gio/gdbusconnection.c
@@ -3715,6 +3715,9 @@ unsubscribe_id_internal (GDBusConnection *connection,
  * 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.
+ * Alternatively, any idle source with a priority lower than %G_PRIORITY_DEFAULT
+ * that was scheduled after unsubscription, also indicates that all resources
+ * of this subscription are released.
  *
  * Since: 2.26
  */