[glib: 1/2] gobject: Document it’s unsafe to call g_object_ref() from GWeakNotify

[Simon McVittie <smcv src gnome org>]

commit 0d57092a036a527ac381f07b919e431a2b51b14f
Author: Philip Withnall <pwithnall endlessos org>
Date:   Tue Sep 14 14:04:23 2021 +0100

    gobject: Document it’s unsafe to call g_object_ref() from GWeakNotify
    
    The documentation sort of already said this, but it’s better to make it
    explicit.
    
    This avoids the situation where some of the weak notify callbacks for an
    object have been called, and then a subsequent one resurrects the
    object. Without some way of undoing the weak notifications already sent,
    that would leave external state which is coupled to the object’s
    lifecycle out of sync.
    
    This arose from discussion on !2064.
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>

 gobject/gobject.h | 5 +++++
 1 file changed, 5 insertions(+)
---
diff --git a/gobject/gobject.h b/gobject/gobject.h
index f62f9c902..d74bebc7c 100644
--- a/gobject/gobject.h
+++ b/gobject/gobject.h
@@ -238,6 +238,11 @@ typedef void (*GObjectFinalizeFunc)     (GObject      *object);
  * Since the object is already being disposed when the #GWeakNotify is called,
  * there's not much you could do with the object, apart from e.g. using its
  * address as hash-index or the like.
+ *
+ * In particular, this means it’s invalid to call g_object_ref(),
+ * g_weak_ref_init(), g_weak_ref_set(), g_object_add_toggle_ref(),
+ * g_object_weak_ref(), g_object_add_weak_pointer() or any function which calls
+ * them on the object from this callback.
  */
 typedef void (*GWeakNotify)            (gpointer      data,
                                         GObject      *where_the_object_was);