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

[Thomas Haller <thaller src gnome org>]

commit 66b3afb2470cc1b8b6aa29d9a2b8f1e4c949ade9
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 events with G_PRIORITY_DEFAULT. It needs to schedule
    all events with this same priority, otherwise the ordering is not
    preserved. At this point, GDBusConnection working this way, is no longer something
    that can reasonably be any different. It's how it fundamentally works, and
    a user must be able to rely on that. As such, this new promise isn't
    something that we wouldn't want to keep 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
  */