Document the best practice for binding InitiallyUnowned

Right now, the documentation is less than explicit on how language
bindings should handle GInitiallyUnowned.
This commit is contained in:
Emmanuele Bassi 2019-05-12 17:06:51 +01:00
parent 95144006e3
commit a734a92408

View File

@ -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:
*
* |[<!-- language="C" -->
* 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,