[glib] GVariant: be more explicit about adopting and returning floating refs
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glib] GVariant: be more explicit about adopting and returning floating refs
- Date: Sat, 14 Aug 2010 02:44:11 +0000 (UTC)
commit c29d800d84d446d3762329815824a8be269c969b
Author: Simon McVittie <simon mcvittie collabora co uk>
Date: Fri Aug 13 22:42:24 2010 -0400
GVariant: be more explicit about adopting and returning floating refs
Bug: https://bugzilla.gnome.org/show_bug.cgi?id=622770
docs/reference/glib/gvariant-varargs.xml | 4 ++-
glib/gvariant.c | 53 +++++++++++++++++++-----------
2 files changed, 37 insertions(+), 20 deletions(-)
---
diff --git a/docs/reference/glib/gvariant-varargs.xml b/docs/reference/glib/gvariant-varargs.xml
index 2d92af0..c62f61c 100644
--- a/docs/reference/glib/gvariant-varargs.xml
+++ b/docs/reference/glib/gvariant-varargs.xml
@@ -220,7 +220,9 @@
<link linkend='GVariant'>GVariant</link> should be used in place of the normal C type or types. For
<link linkend='g-variant-new'><function>g_variant_new()</function></link> this means that you must pass a
non-<link linkend='NULL--CAPS'><literal>NULL</literal></link> <code>(<link linkend='GVariant'>GVariant</link>
- *)</code>. For <link linkend='g-variant-get'><function>g_variant_get()</function></link> this means that you
+ *)</code>; if it is a floating reference, ownership will be taken, as
+ if by using <link linkend="g-variant-ref-sink"><function>g_variant_ref_sink()</function></link>.
+ For <link linkend='g-variant-get'><function>g_variant_get()</function></link> this means that you
must pass a pointer to a <code>(<link linkend='GVariant'>GVariant</link> *)</code> for the value to be returned
by reference or <link linkend='NULL--CAPS'><literal>NULL</literal></link> to ignore the value. See
<link linkend='gvariant-format-strings-gvariant'><code>GVariant *</code></link> below.
diff --git a/glib/gvariant.c b/glib/gvariant.c
index ab42d2c..6822a2a 100644
--- a/glib/gvariant.c
+++ b/glib/gvariant.c
@@ -316,7 +316,7 @@ g_variant_new_from_trusted (const GVariantType *type,
/**
* g_variant_new_boolean:
* @boolean: a #gboolean value
- * @returns: a new boolean #GVariant instance
+ * @returns: a floating reference to a new boolean #GVariant instance
*
* Creates a new boolean #GVariant instance -- either %TRUE or %FALSE.
*
@@ -374,7 +374,7 @@ g_variant_get_boolean (GVariant *value)
/**
* g_variant_new_byte:
* @byte: a #guint8 value
- * @returns: a new byte #GVariant instance
+ * @returns: a floating reference to a new byte #GVariant instance
*
* Creates a new byte #GVariant instance.
*
@@ -397,7 +397,7 @@ NUMERIC_TYPE (BYTE, byte, guchar)
/**
* g_variant_new_int16:
* @int16: a #gint16 value
- * @returns: a new int16 #GVariant instance
+ * @returns: a floating reference to a new int16 #GVariant instance
*
* Creates a new int16 #GVariant instance.
*
@@ -420,7 +420,7 @@ NUMERIC_TYPE (INT16, int16, gint16)
/**
* g_variant_new_uint16:
* @uint16: a #guint16 value
- * @returns: a new uint16 #GVariant instance
+ * @returns: a floating reference to a new uint16 #GVariant instance
*
* Creates a new uint16 #GVariant instance.
*
@@ -443,7 +443,7 @@ NUMERIC_TYPE (UINT16, uint16, guint16)
/**
* g_variant_new_int32:
* @int32: a #gint32 value
- * @returns: a new int32 #GVariant instance
+ * @returns: a floating reference to a new int32 #GVariant instance
*
* Creates a new int32 #GVariant instance.
*
@@ -466,7 +466,7 @@ NUMERIC_TYPE (INT32, int32, gint32)
/**
* g_variant_new_uint32:
* @uint32: a #guint32 value
- * @returns: a new uint32 #GVariant instance
+ * @returns: a floating reference to a new uint32 #GVariant instance
*
* Creates a new uint32 #GVariant instance.
*
@@ -489,7 +489,7 @@ NUMERIC_TYPE (UINT32, uint32, guint32)
/**
* g_variant_new_int64:
* @int64: a #gint64 value
- * @returns: a new int64 #GVariant instance
+ * @returns: a floating reference to a new int64 #GVariant instance
*
* Creates a new int64 #GVariant instance.
*
@@ -512,7 +512,7 @@ NUMERIC_TYPE (INT64, int64, gint64)
/**
* g_variant_new_uint64:
* @uint64: a #guint64 value
- * @returns: a new uint64 #GVariant instance
+ * @returns: a floating reference to a new uint64 #GVariant instance
*
* Creates a new uint64 #GVariant instance.
*
@@ -535,7 +535,7 @@ NUMERIC_TYPE (UINT64, uint64, guint64)
/**
* g_variant_new_handle:
* @handle: a #gint32 value
- * @returns: a new handle #GVariant instance
+ * @returns: a floating reference to a new handle #GVariant instance
*
* Creates a new handle #GVariant instance.
*
@@ -566,7 +566,7 @@ NUMERIC_TYPE (HANDLE, handle, gint32)
/**
* g_variant_new_double:
* @floating: a #gdouble floating point value
- * @returns: a new double #GVariant instance
+ * @returns: a floating reference to a new double #GVariant instance
*
* Creates a new double #GVariant instance.
*
@@ -591,7 +591,7 @@ NUMERIC_TYPE (DOUBLE, double, gdouble)
* g_variant_new_maybe:
* @child_type: (allow-none): the #GVariantType of the child, or %NULL
* @child: (allow-none): the child value, or %NULL
- * @returns: a new #GVariant maybe instance
+ * @returns: a floating reference to a new #GVariant maybe instance
*
* Depending on if @child is %NULL, either wraps @child inside of a
* maybe container or creates a Nothing instance for the given @type.
@@ -601,6 +601,9 @@ NUMERIC_TYPE (DOUBLE, double, gdouble)
* If they are both non-%NULL then @child_type must be the type
* of @child.
*
+ * If @child is a floating reference (see g_variant_ref_sink()), the new
+ * instance takes ownership of @child.
+ *
* Since: 2.24
**/
GVariant *
@@ -665,11 +668,14 @@ g_variant_get_maybe (GVariant *value)
/**
* g_variant_new_variant:
* @value: a #GVariance instance
- * @returns: a new variant #GVariant instance
+ * @returns: a floating reference to a new variant #GVariant instance
*
* Boxes @value. The result is a #GVariant instance representing a
* variant containing the original value.
*
+ * If @child is a floating reference (see g_variant_ref_sink()), the new
+ * instance takes ownership of @child.
+ *
* Since: 2.24
**/
GVariant *
@@ -708,7 +714,7 @@ g_variant_get_variant (GVariant *value)
* @children: (allow-none) (array length=n_children): an array of
* #GVariant pointers, the children
* @n_children: the length of @children
- * @returns: a new #GVariant array
+ * @returns: a floating reference to a new #GVariant array
*
* Creates a new #GVariant array from @children.
*
@@ -723,6 +729,9 @@ g_variant_get_variant (GVariant *value)
* All items in the array must have the same type, which must be the
* same as @child_type, if given.
*
+ * If the @children are floating references (see g_variant_ref_sink()), the
+ * new instance takes ownership of them as if via g_variant_ref_sink().
+ *
* Since: 2.24
**/
GVariant *
@@ -792,7 +801,7 @@ g_variant_make_tuple_type (GVariant * const *children,
* g_variant_new_tuple:
* @children: (array length=n_children): the items to make the tuple out of
* @n_children: the length of @children
- * @returns: a new #GVariant tuple
+ * @returns: a floating reference to a new #GVariant tuple
*
* Creates a new tuple #GVariant out of the items in @children. The
* type is determined from the types of @children. No entry in the
@@ -800,6 +809,9 @@ g_variant_make_tuple_type (GVariant * const *children,
*
* If @n_children is 0 then the unit tuple is constructed.
*
+ * If the @children are floating references (see g_variant_ref_sink()), the
+ * new instance takes ownership of them as if via g_variant_ref_sink().
+ *
* Since: 2.24
**/
GVariant *
@@ -851,13 +863,16 @@ g_variant_make_dict_entry_type (GVariant *key,
* g_variant_new_dict_entry:
* @key: a basic #GVariant, the key
* @value: a #GVariant, the value
- * @returns: a new dictionary entry #GVariant
+ * @returns: a floating reference to a new dictionary entry #GVariant
*
* Creates a new dictionary entry #GVariant. @key and @value must be
* non-%NULL.
*
* @key must be a value of a basic type (ie: not a container).
*
+ * If the @key or @value are floating references (see g_variant_ref_sink()),
+ * the new instance takes ownership of them as if via g_variant_ref_sink().
+ *
* Since: 2.24
**/
GVariant *
@@ -959,7 +974,7 @@ g_variant_get_fixed_array (GVariant *value,
/**
* g_variant_new_string:
* @string: a normal utf8 nul-terminated string
- * @returns: a new string #GVariant instance
+ * @returns: a floating reference to a new string #GVariant instance
*
* Creates a string #GVariant with the contents of @string.
*
@@ -980,7 +995,7 @@ g_variant_new_string (const gchar *string)
/**
* g_variant_new_object_path:
* @object_path: a normal C nul-terminated string
- * @returns: a new object path #GVariant instance
+ * @returns: a floating reference to a new object path #GVariant instance
*
* Creates a DBus object path #GVariant with the contents of @string.
* @string must be a valid DBus object path. Use
@@ -1024,7 +1039,7 @@ g_variant_is_object_path (const gchar *string)
/**
* g_variant_new_signature:
* @signature: a normal C nul-terminated string
- * @returns: a new signature #GVariant instance
+ * @returns: a floating reference to a new signature #GVariant instance
*
* Creates a DBus type signature #GVariant with the contents of
* @string. @string must be a valid DBus type signature. Use
@@ -1298,7 +1313,7 @@ g_variant_dup_strv (GVariant *value,
/**
* g_variant_new_bytestring:
* @string: a normal nul-terminated string in no particular encoding
- * @returns: a new bytestring #GVariant instance
+ * @returns: a floating reference to a new bytestring #GVariant instance
*
* Creates an array-of-bytes #GVariant with the contents of @string.
* This function is just like g_variant_new_string() except that the
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]