From c29d800d84d446d3762329815824a8be269c969b Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Fri, 13 Aug 2010 22:42:24 -0400 Subject: [PATCH] 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 2d92af0e0..c62f61c70 100644 --- a/docs/reference/glib/gvariant-varargs.xml +++ b/docs/reference/glib/gvariant-varargs.xml @@ -220,7 +220,9 @@ GVariant should be used in place of the normal C type or types. For g_variant_new() this means that you must pass a non-NULL (GVariant - *). For g_variant_get() this means that you + *); if it is a floating reference, ownership will be taken, as + if by using g_variant_ref_sink(). + For g_variant_get() this means that you must pass a pointer to a (GVariant *) for the value to be returned by reference or NULL to ignore the value. See GVariant * below. diff --git a/glib/gvariant.c b/glib/gvariant.c index ab42d2ce8..6822a2aba 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