mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-10 03:16:17 +01:00
docs: Move the GVariant SECTION
Move it to the struct docs. Signed-off-by: Philip Withnall <pwithnall@gnome.org> Helps: #3037
This commit is contained in:
Philip Withnall
parent
229b76a388
commit
214853d6df
@ -49,14 +49,6 @@
|
||||
* Most GVariant API functions are in gvariant.c.
|
||||
*/
|
||||
|
||||
/**
|
||||
* GVariant:
|
||||
*
|
||||
* #GVariant is an opaque data structure and can only be accessed
|
||||
* using the following functions.
|
||||
*
|
||||
* Since: 2.24
|
||||
**/
|
||||
struct _GVariant
|
||||
/* see below for field member documentation */
|
||||
{
|
||||
|
||||
179
glib/gvariant.c
179
glib/gvariant.c
@ -36,115 +36,114 @@
|
||||
#include <string.h>
|
||||
|
||||
/**
|
||||
* SECTION:gvariant
|
||||
* @title: GVariant
|
||||
* @short_description: strongly typed value datatype
|
||||
* @see_also: GVariantType
|
||||
* GVariant:
|
||||
*
|
||||
* #GVariant is a variant datatype; it can contain one or more values
|
||||
* `GVariant` is a variant datatype; it can contain one or more values
|
||||
* along with information about the type of the values.
|
||||
*
|
||||
* A #GVariant may contain simple types, like an integer, or a boolean value;
|
||||
* A `GVariant` may contain simple types, like an integer, or a boolean value;
|
||||
* or complex types, like an array of two strings, or a dictionary of key
|
||||
* value pairs. A #GVariant is also immutable: once it's been created neither
|
||||
* value pairs. A `GVariant` is also immutable: once it’s been created neither
|
||||
* its type nor its content can be modified further.
|
||||
*
|
||||
* GVariant is useful whenever data needs to be serialized, for example when
|
||||
* sending method parameters in D-Bus, or when saving settings using GSettings.
|
||||
* `GVariant` is useful whenever data needs to be serialized, for example when
|
||||
* sending method parameters in D-Bus, or when saving settings using
|
||||
* [class@Gio.Settings].
|
||||
*
|
||||
* When creating a new #GVariant, you pass the data you want to store in it
|
||||
* When creating a new `GVariant`, you pass the data you want to store in it
|
||||
* along with a string representing the type of data you wish to pass to it.
|
||||
*
|
||||
* For instance, if you want to create a #GVariant holding an integer value you
|
||||
* For instance, if you want to create a `GVariant` holding an integer value you
|
||||
* can use:
|
||||
*
|
||||
* |[<!-- language="C" -->
|
||||
* GVariant *v = g_variant_new ("u", 40);
|
||||
* ]|
|
||||
* ```c
|
||||
* GVariant *v = g_variant_new ("u", 40);
|
||||
* ```
|
||||
*
|
||||
* The string "u" in the first argument tells #GVariant that the data passed to
|
||||
* the constructor (40) is going to be an unsigned integer.
|
||||
* The string `u` in the first argument tells `GVariant` that the data passed to
|
||||
* the constructor (`40`) is going to be an unsigned integer.
|
||||
*
|
||||
* More advanced examples of #GVariant in use can be found in documentation for
|
||||
* [GVariant format strings][gvariant-format-strings-pointers].
|
||||
* More advanced examples of `GVariant` in use can be found in documentation for
|
||||
* [`GVariant` format strings](gvariant-format-strings.html#pointers).
|
||||
*
|
||||
* The range of possible values is determined by the type.
|
||||
*
|
||||
* The type system used by #GVariant is #GVariantType.
|
||||
* The type system used by `GVariant` is [type@GLib.VariantType].
|
||||
*
|
||||
* #GVariant instances always have a type and a value (which are given
|
||||
* at construction time). The type and value of a #GVariant instance
|
||||
* can never change other than by the #GVariant itself being
|
||||
* destroyed. A #GVariant cannot contain a pointer.
|
||||
* `GVariant` instances always have a type and a value (which are given
|
||||
* at construction time). The type and value of a `GVariant` instance
|
||||
* can never change other than by the `GVariant` itself being
|
||||
* destroyed. A `GVariant` cannot contain a pointer.
|
||||
*
|
||||
* #GVariant is reference counted using g_variant_ref() and
|
||||
* g_variant_unref(). #GVariant also has floating reference counts --
|
||||
* see g_variant_ref_sink().
|
||||
* `GVariant` is reference counted using [method@GLib.Variant.ref] and
|
||||
* [method@GLib.Variant.unref]. `GVariant` also has floating reference counts —
|
||||
* see [method@GLib.Variant.ref_sink].
|
||||
*
|
||||
* #GVariant is completely threadsafe. A #GVariant instance can be
|
||||
* `GVariant` is completely threadsafe. A `GVariant` instance can be
|
||||
* concurrently accessed in any way from any number of threads without
|
||||
* problems.
|
||||
*
|
||||
* #GVariant is heavily optimised for dealing with data in serialized
|
||||
* `GVariant` is heavily optimised for dealing with data in serialized
|
||||
* form. It works particularly well with data located in memory-mapped
|
||||
* files. It can perform nearly all deserialization operations in a
|
||||
* small constant time, usually touching only a single memory page.
|
||||
* Serialized #GVariant data can also be sent over the network.
|
||||
* Serialized `GVariant` data can also be sent over the network.
|
||||
*
|
||||
* #GVariant is largely compatible with D-Bus. Almost all types of
|
||||
* #GVariant instances can be sent over D-Bus. See #GVariantType for
|
||||
* exceptions. (However, #GVariant's serialization format is not the same
|
||||
* as the serialization format of a D-Bus message body: use #GDBusMessage,
|
||||
* in the gio library, for those.)
|
||||
* `GVariant` is largely compatible with D-Bus. Almost all types of
|
||||
* `GVariant` instances can be sent over D-Bus. See [type@GLib.VariantType] for
|
||||
* exceptions. (However, `GVariant`’s serialization format is not the same
|
||||
* as the serialization format of a D-Bus message body: use
|
||||
* [class@Gio.DBusMessage], in the GIO library, for those.)
|
||||
*
|
||||
* For space-efficiency, the #GVariant serialization format does not
|
||||
* automatically include the variant's length, type or endianness,
|
||||
* For space-efficiency, the `GVariant` serialization format does not
|
||||
* automatically include the variant’s length, type or endianness,
|
||||
* which must either be implied from context (such as knowledge that a
|
||||
* particular file format always contains a little-endian
|
||||
* %G_VARIANT_TYPE_VARIANT which occupies the whole length of the file)
|
||||
* `G_VARIANT_TYPE_VARIANT` which occupies the whole length of the file)
|
||||
* or supplied out-of-band (for instance, a length, type and/or endianness
|
||||
* indicator could be placed at the beginning of a file, network message
|
||||
* or network stream).
|
||||
*
|
||||
* A #GVariant's size is limited mainly by any lower level operating
|
||||
* system constraints, such as the number of bits in #gsize. For
|
||||
* A `GVariant`’s size is limited mainly by any lower level operating
|
||||
* system constraints, such as the number of bits in `gsize`. For
|
||||
* example, it is reasonable to have a 2GB file mapped into memory
|
||||
* with #GMappedFile, and call g_variant_new_from_data() on it.
|
||||
* with [struct@GLib.MappedFile], and call [ctor@GLib.Variant.new_from_data] on
|
||||
* it.
|
||||
*
|
||||
* For convenience to C programmers, #GVariant features powerful
|
||||
* For convenience to C programmers, `GVariant` features powerful
|
||||
* varargs-based value construction and destruction. This feature is
|
||||
* designed to be embedded in other libraries.
|
||||
*
|
||||
* There is a Python-inspired text language for describing #GVariant
|
||||
* values. #GVariant includes a printer for this language and a parser
|
||||
* There is a Python-inspired text language for describing `GVariant`
|
||||
* values. `GVariant` includes a printer for this language and a parser
|
||||
* with type inferencing.
|
||||
*
|
||||
* ## Memory Use
|
||||
*
|
||||
* #GVariant tries to be quite efficient with respect to memory use.
|
||||
* `GVariant` tries to be quite efficient with respect to memory use.
|
||||
* This section gives a rough idea of how much memory is used by the
|
||||
* current implementation. The information here is subject to change
|
||||
* in the future.
|
||||
*
|
||||
* The memory allocated by #GVariant can be grouped into 4 broad
|
||||
* The memory allocated by `GVariant` can be grouped into 4 broad
|
||||
* purposes: memory for serialized data, memory for the type
|
||||
* information cache, buffer management memory and memory for the
|
||||
* #GVariant structure itself.
|
||||
* `GVariant` structure itself.
|
||||
*
|
||||
* ## Serialized Data Memory
|
||||
*
|
||||
* This is the memory that is used for storing GVariant data in
|
||||
* This is the memory that is used for storing `GVariant` data in
|
||||
* serialized form. This is what would be sent over the network or
|
||||
* what would end up on disk, not counting any indicator of the
|
||||
* endianness, or of the length or type of the top-level variant.
|
||||
*
|
||||
* The amount of memory required to store a boolean is 1 byte. 16,
|
||||
* 32 and 64 bit integers and double precision floating point numbers
|
||||
* use their "natural" size. Strings (including object path and
|
||||
* use their ‘natural’ size. Strings (including object path and
|
||||
* signature strings) are stored with a nul terminator, and as such
|
||||
* use the length of the string plus 1 byte.
|
||||
*
|
||||
* Maybe types use no space at all to represent the null value and
|
||||
* ‘Maybe’ types use no space at all to represent the null value and
|
||||
* use the same amount of space (sometimes plus one byte) as the
|
||||
* equivalent non-maybe-typed value to represent the non-null case.
|
||||
*
|
||||
@ -170,39 +169,39 @@
|
||||
* In the case that the dictionary is empty, 0 bytes are required for
|
||||
* the serialization.
|
||||
*
|
||||
* If we add an item "width" that maps to the int32 value of 500 then
|
||||
* we will use 4 byte to store the int32 (so 6 for the variant
|
||||
* If we add an item ‘width’ that maps to the int32 value of 500 then
|
||||
* we will use 4 bytes to store the int32 (so 6 for the variant
|
||||
* containing it) and 6 bytes for the string. The variant must be
|
||||
* aligned to 8 after the 6 bytes of the string, so that's 2 extra
|
||||
* aligned to 8 after the 6 bytes of the string, so that’s 2 extra
|
||||
* bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used
|
||||
* for the dictionary entry. An additional 1 byte is added to the
|
||||
* array as a framing offset making a total of 15 bytes.
|
||||
*
|
||||
* If we add another entry, "title" that maps to a nullable string
|
||||
* If we add another entry, ‘title’ that maps to a nullable string
|
||||
* that happens to have a value of null, then we use 0 bytes for the
|
||||
* null value (and 3 bytes for the variant to contain it along with
|
||||
* its type string) plus 6 bytes for the string. Again, we need 2
|
||||
* padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes.
|
||||
*
|
||||
* We now require extra padding between the two items in the array.
|
||||
* After the 14 bytes of the first item, that's 2 bytes required.
|
||||
* After the 14 bytes of the first item, that’s 2 bytes required.
|
||||
* We now require 2 framing offsets for an extra two
|
||||
* bytes. 14 + 2 + 11 + 2 = 29 bytes to encode the entire two-item
|
||||
* dictionary.
|
||||
*
|
||||
* ## Type Information Cache
|
||||
*
|
||||
* For each GVariant type that currently exists in the program a type
|
||||
* For each `GVariant` type that currently exists in the program a type
|
||||
* information structure is kept in the type information cache. The
|
||||
* type information structure is required for rapid deserialization.
|
||||
*
|
||||
* Continuing with the above example, if a #GVariant exists with the
|
||||
* type "a{sv}" then a type information struct will exist for
|
||||
* "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type
|
||||
* Continuing with the above example, if a `GVariant` exists with the
|
||||
* type `a{sv}` then a type information struct will exist for
|
||||
* `a{sv}`, `{sv}`, `s`, and `v`. Multiple uses of the same type
|
||||
* will share the same type information. Additionally, all
|
||||
* single-digit types are stored in read-only static memory and do
|
||||
* not contribute to the writable memory footprint of a program using
|
||||
* #GVariant.
|
||||
* `GVariant`.
|
||||
*
|
||||
* Aside from the type information structures stored in read-only
|
||||
* memory, there are two forms of type information. One is used for
|
||||
@ -210,23 +209,23 @@
|
||||
* maybe types. The other is used for container types where there
|
||||
* are multiple element types: tuples and dictionary entries.
|
||||
*
|
||||
* Array type info structures are 6 * sizeof (void *), plus the
|
||||
* Array type info structures are `6 * sizeof (void *)`, plus the
|
||||
* memory required to store the type string itself. This means that
|
||||
* on 32-bit systems, the cache entry for "a{sv}" would require 30
|
||||
* bytes of memory (plus malloc overhead).
|
||||
* on 32-bit systems, the cache entry for `a{sv}` would require 30
|
||||
* bytes of memory (plus allocation overhead).
|
||||
*
|
||||
* Tuple type info structures are 6 * sizeof (void *), plus 4 *
|
||||
* sizeof (void *) for each item in the tuple, plus the memory
|
||||
* Tuple type info structures are `6 * sizeof (void *)`, plus `4 *
|
||||
* sizeof (void *)` for each item in the tuple, plus the memory
|
||||
* required to store the type string itself. A 2-item tuple, for
|
||||
* example, would have a type information structure that consumed
|
||||
* writable memory in the size of 14 * sizeof (void *) (plus type
|
||||
* writable memory in the size of `14 * sizeof (void *)` (plus type
|
||||
* string) This means that on 32-bit systems, the cache entry for
|
||||
* "{sv}" would require 61 bytes of memory (plus malloc overhead).
|
||||
* `{sv}` would require 61 bytes of memory (plus allocation overhead).
|
||||
*
|
||||
* This means that in total, for our "a{sv}" example, 91 bytes of
|
||||
* This means that in total, for our `a{sv}` example, 91 bytes of
|
||||
* type information would be allocated.
|
||||
*
|
||||
* The type information cache, additionally, uses a #GHashTable to
|
||||
* The type information cache, additionally, uses a [struct@GLib.HashTable] to
|
||||
* store and look up the cached items and stores a pointer to this
|
||||
* hash table in static storage. The hash table is freed when there
|
||||
* are zero items in the type cache.
|
||||
@ -238,34 +237,34 @@
|
||||
*
|
||||
* ## Buffer Management Memory
|
||||
*
|
||||
* #GVariant uses an internal buffer management structure to deal
|
||||
* `GVariant` uses an internal buffer management structure to deal
|
||||
* with the various different possible sources of serialized data
|
||||
* that it uses. The buffer is responsible for ensuring that the
|
||||
* correct call is made when the data is no longer in use by
|
||||
* #GVariant. This may involve a g_free() or a g_slice_free() or
|
||||
* even g_mapped_file_unref().
|
||||
* `GVariant`. This may involve a [func@GLib.free] or
|
||||
* even [method@GLib.MappedFile.unref].
|
||||
*
|
||||
* One buffer management structure is used for each chunk of
|
||||
* serialized data. The size of the buffer management structure
|
||||
* is 4 * (void *). On 32-bit systems, that's 16 bytes.
|
||||
* is `4 * (void *)`. On 32-bit systems, that’s 16 bytes.
|
||||
*
|
||||
* ## GVariant structure
|
||||
*
|
||||
* The size of a #GVariant structure is 6 * (void *). On 32-bit
|
||||
* systems, that's 24 bytes.
|
||||
* The size of a `GVariant` structure is `6 * (void *)`. On 32-bit
|
||||
* systems, that’s 24 bytes.
|
||||
*
|
||||
* #GVariant structures only exist if they are explicitly created
|
||||
* with API calls. For example, if a #GVariant is constructed out of
|
||||
* `GVariant` structures only exist if they are explicitly created
|
||||
* with API calls. For example, if a `GVariant` is constructed out of
|
||||
* serialized data for the example given above (with the dictionary)
|
||||
* then although there are 9 individual values that comprise the
|
||||
* entire dictionary (two keys, two values, two variants containing
|
||||
* the values, two dictionary entries, plus the dictionary itself),
|
||||
* only 1 #GVariant instance exists -- the one referring to the
|
||||
* only 1 `GVariant` instance exists — the one referring to the
|
||||
* dictionary.
|
||||
*
|
||||
* If calls are made to start accessing the other values then
|
||||
* #GVariant instances will exist for those values only for as long
|
||||
* as they are in use (ie: until you call g_variant_unref()). The
|
||||
* `GVariant` instances will exist for those values only for as long
|
||||
* as they are in use (ie: until you call [method@GLib.Variant.unref]). The
|
||||
* type information is shared. The serialized data and the buffer
|
||||
* management structure for that serialized data is shared by the
|
||||
* child.
|
||||
@ -276,13 +275,15 @@
|
||||
* strings to variants (with two entries, as given above), we are
|
||||
* using 91 bytes of memory for type information, 29 bytes of memory
|
||||
* for the serialized data, 16 bytes for buffer management and 24
|
||||
* bytes for the #GVariant instance, or a total of 160 bytes, plus
|
||||
* malloc overhead. If we were to use g_variant_get_child_value() to
|
||||
* access the two dictionary entries, we would use an additional 48
|
||||
* bytes for the `GVariant` instance, or a total of 160 bytes, plus
|
||||
* allocation overhead. If we were to use [method@GLib.Variant.get_child_value]
|
||||
* to access the two dictionary entries, we would use an additional 48
|
||||
* bytes. If we were to have other dictionaries of the same type, we
|
||||
* would use more memory for the serialized data and buffer
|
||||
* management for those dictionaries, but the type information would
|
||||
* be shared.
|
||||
*
|
||||
* Since: 2.24
|
||||
*/
|
||||
|
||||
/* definition of GVariant structure is in gvariant-core.c */
|
||||
@ -964,7 +965,7 @@ g_variant_new_dict_entry (GVariant *key,
|
||||
* @format_string determines the C types that are used for unpacking
|
||||
* the values and also determines if the values are copied or borrowed,
|
||||
* see the section on
|
||||
* [GVariant format strings][gvariant-format-strings-pointers].
|
||||
* [`GVariant` format strings](gvariant-format-strings.html#pointers).
|
||||
*
|
||||
* This function is currently implemented with a linear scan. If you
|
||||
* plan to do many lookups then #GVariantDict may be more efficient.
|
||||
@ -4045,7 +4046,7 @@ g_variant_dict_init (GVariantDict *dict,
|
||||
*
|
||||
* @format_string determines the C types that are used for unpacking the
|
||||
* values and also determines if the values are copied or borrowed, see the
|
||||
* section on [GVariant format strings][gvariant-format-strings-pointers].
|
||||
* section on [`GVariant` format strings](gvariant-format-strings.html#pointers).
|
||||
*
|
||||
* Returns: %TRUE if a value was unpacked
|
||||
*
|
||||
@ -5505,7 +5506,7 @@ g_variant_new_va (const gchar *format_string,
|
||||
* @format_string determines the C types that are used for unpacking
|
||||
* the values and also determines if the values are copied or borrowed,
|
||||
* see the section on
|
||||
* [GVariant format strings][gvariant-format-strings-pointers].
|
||||
* [`GVariant` format strings](gvariant-format-strings.html#pointers).
|
||||
*
|
||||
* Since: 2.24
|
||||
**/
|
||||
@ -5559,7 +5560,7 @@ g_variant_get (GVariant *value,
|
||||
* @format_string determines the C types that are used for unpacking
|
||||
* the values and also determines if the values are copied or borrowed,
|
||||
* see the section on
|
||||
* [GVariant format strings][gvariant-format-strings-pointers].
|
||||
* [`GVariant` format strings](gvariant-format-strings.html#pointers).
|
||||
*
|
||||
* Since: 2.24
|
||||
**/
|
||||
@ -5654,7 +5655,7 @@ g_variant_builder_add (GVariantBuilder *builder,
|
||||
* @format_string determines the C types that are used for unpacking
|
||||
* the values and also determines if the values are copied or borrowed,
|
||||
* see the section on
|
||||
* [GVariant format strings][gvariant-format-strings-pointers].
|
||||
* [`GVariant` format strings](gvariant-format-strings.html#pointers).
|
||||
*
|
||||
* Since: 2.24
|
||||
**/
|
||||
@ -5727,7 +5728,7 @@ g_variant_get_child (GVariant *value,
|
||||
* the values and also determines if the values are copied or borrowed.
|
||||
*
|
||||
* See the section on
|
||||
* [GVariant format strings][gvariant-format-strings-pointers].
|
||||
* [`GVariant` format strings](gvariant-format-strings.html#pointers).
|
||||
*
|
||||
* Returns: %TRUE if a value was unpacked, or %FALSE if there as no value
|
||||
*
|
||||
@ -5826,7 +5827,7 @@ g_variant_iter_next (GVariantIter *iter,
|
||||
* the values and also determines if the values are copied or borrowed.
|
||||
*
|
||||
* See the section on
|
||||
* [GVariant format strings][gvariant-format-strings-pointers].
|
||||
* [`GVariant` format strings](gvariant-format-strings.html#pointers).
|
||||
*
|
||||
* Returns: %TRUE if a value was unpacked, or %FALSE if there was no
|
||||
* value
|
||||
|
||||
Loading…
Reference in New Issue
Block a user