From 21cc809158bfe8fd4efc7292b7ab13288a385b73 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20=C3=85dahl?= Date: Fri, 9 Apr 2021 11:13:36 +0200 Subject: [PATCH] refcount: Clarify when the ref count ends up undefined Calling g_atomic_ref_count_dec() or g_ref_count_dec() and the reference count reaches zero results in different side effects depending on whether the reference count is atomic or not. The intended side effect when this happens is undefined, i.e. one should not rely on the reference count actually reaching zero, or staying 1, or becoming something else, and one should treat the grefcount / gatomicrefcount to be unusable until reinitialized. This wasn't documented, so add a paragraph about this. --- glib/grefcount.c | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/glib/grefcount.c b/glib/grefcount.c index 7cb12fc46..9dae60ad8 100644 --- a/glib/grefcount.c +++ b/glib/grefcount.c @@ -142,6 +142,10 @@ void * * Decreases the reference count. * + * If %TRUE is returned, the reference count reached 0. After this point, @rc + * is an undefined state and must be reinitialized with + * g_ref_count_init() to be used again. + * * Returns: %TRUE if the reference count reached 0, and %FALSE otherwise * * Since: 2.58 @@ -249,6 +253,10 @@ void * * Atomically decreases the reference count. * + * If %TRUE is returned, the reference count reached 0. After this point, @arc + * is an undefined state and must be reinitialized with + * g_atomic_ref_count_init() to be used again. + * * Returns: %TRUE if the reference count reached 0, and %FALSE otherwise * * Since: 2.58