[glib/floating-ref-warning: 1/2] Document the best practice for binding InitiallyUnowned
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glib/floating-ref-warning: 1/2] Document the best practice for binding InitiallyUnowned
- Date: Sun, 12 May 2019 16:10:05 +0000 (UTC)
commit 3956e54bab49017ef5f6619f9c1a3a470239cd76
Author: Emmanuele Bassi <ebassi gnome org>
Date: Sun May 12 17:06:51 2019 +0100
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..23201f192 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:
+ *
+ * |[<!-- 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,
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]