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>

1 files changed, 5 insertions, 0 deletions

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);