From a734a92408494e4637ff6404bd515d15618f1f8d Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sun, 12 May 2019 17:06:51 +0100 Subject: [PATCH 1/2] Document the best practice for binding InitiallyUnowned Right now, the documentation is less than explicit on how language bindings should handle GInitiallyUnowned. --- gobject/gobject.c | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/gobject/gobject.c b/gobject/gobject.c index 190ae19ec..3127d527c 100644 --- a/gobject/gobject.c +++ b/gobject/gobject.c @@ -83,7 +83,23 @@ * Since floating references are useful almost exclusively for C convenience, * language bindings that provide automated reference and memory ownership * maintenance (such as smart pointers or garbage collection) should not - * expose floating references in their API. + * expose floating references in their API. The best practice for handling + * types that have initially floating references is to immediately sink those + * references after g_object_new() returns, by checking if the #GType + * inherits from #GInitiallyUnowned. For instance: + * + * |[ + * GObject *res = g_object_new_with_properties (gtype, + * n_props, + * prop_names, + * prop_values); + * + * // or: if (g_type_is_a (gtype, G_TYPE_INITIALLY_UNOWNED)) + * if (G_IS_INITIALLY_UNOWNED (res)) + * g_object_ref_sink (res); + * + * return res; + * ]| * * Some object implementations may need to save an objects floating state * across certain code portions (an example is #GtkMenu), to achieve this, From 8b2f6a5523000449de2a102f4bba276febea2def Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sun, 12 May 2019 17:08:51 +0100 Subject: [PATCH 2/2] Please don't use GInitiallyUnowned and floating refs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This place is not a place of honor… No highly esteemed API is implemented here… Nothing valued is here. --- gobject/gobject.c | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/gobject/gobject.c b/gobject/gobject.c index 3127d527c..c95311b3e 100644 --- a/gobject/gobject.c +++ b/gobject/gobject.c @@ -53,6 +53,13 @@ * * ## Floating references # {#floating-ref} * + * **Note**: Floating references are a C convenience API and should not be + * used in modern GObject code. Language bindings in particular find the + * concept highly problematic, as floating references are not identifiable + * through annotations, and neither are deviations from the floating reference + * behavior, like types that inherit from #GInitiallyUnowned and still return + * a full reference from g_object_new(). + * * GInitiallyUnowned is derived from GObject. The only difference between * the two is that the initial reference of a GInitiallyUnowned is flagged * as a "floating" reference. This means that it is not specifically