From a734a92408494e4637ff6404bd515d15618f1f8d Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sun, 12 May 2019 17:06:51 +0100 Subject: [PATCH] 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,