Previous: Destructuring Mismatch, Up: Argument Mismatch Detection
If call-next-method is called with arguments, the ordered set of applicable methods for the changed set of arguments for call-next-method must be the same as the ordered set of applicable methods for the original arguments to the generic function, or else an error should be signaled.
The comparison between the set of methods applicable to the new arguments and the set applicable to the original arguments is insensitive to order differences among methods with the same specializers.
If call-next-method is called with arguments that specify a different ordered set of applicable methods and there is no next method available, the test for different methods and the associated error signaling (when present) takes precedence over calling no-next-method.


{% extends "page.html" %} {% block main %}
Copy this token. You won't be able to see it again, but you can always come back here to get a new one.


Protocols
The following protocols are available globally.
-
The
ErrorTypeProtocol
protocol exposes the methods and properties of an underlyingGError
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeErrorType
. Alternatively, useErrorTypeRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
See moreGError
structure contains information about an error that has occurred.Declaration
Swift
public protocol ErrorTypeProtocol : Error
-
The
ArrayTypeProtocol
protocol exposes the methods and properties of an underlyingGArray
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeArrayType
. Alternatively, useArrayTypeRef
as a lighweight,unowned
reference if you already have an instance you just want to use.Contains the public fields of a GArray.
See moreDeclaration
Swift
public protocol ArrayTypeProtocol
-
The
AsyncQueueProtocol
protocol exposes the methods and properties of an underlyingGAsyncQueue
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeAsyncQueue
. Alternatively, useAsyncQueueRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The GAsyncQueue struct is an opaque data structure which represents an asynchronous queue. It should only be accessed through the g_async_queue_* functions.
See moreDeclaration
Swift
public protocol AsyncQueueProtocol
-
The
BookmarkFileProtocol
protocol exposes the methods and properties of an underlyingGBookmarkFile
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeBookmarkFile
. Alternatively, useBookmarkFileRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
See moreGBookmarkFile
structure contains only private data and should not be directly accessed.Declaration
Swift
public protocol BookmarkFileProtocol
-
The
ByteArrayProtocol
protocol exposes the methods and properties of an underlyingGByteArray
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeByteArray
. Alternatively, useByteArrayRef
as a lighweight,unowned
reference if you already have an instance you just want to use.Contains the public fields of a GByteArray.
See moreDeclaration
Swift
public protocol ByteArrayProtocol
-
The
BytesProtocol
protocol exposes the methods and properties of an underlyingGBytes
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeBytes
. Alternatively, useBytesRef
as a lighweight,unowned
reference if you already have an instance you just want to use.A simple refcounted data type representing an immutable sequence of zero or more bytes from an unspecified origin.
The purpose of a
GBytes
is to keep the memory region that it holds alive for as long as anyone holds a reference to the bytes. When the last reference count is dropped, the memory is released. Multiple unrelated callers can use byte data in theGBytes
without coordinating their activities, resting assured that the byte data will not change or move while they hold a reference.A
GBytes
can come from many different origins that may have different procedures for freeing the memory region. Examples are memory fromg_malloc()
, from memory slices, from aGMappedFile
or memory from other allocators.GBytes
work well as keys inGHashTable
. Useg_bytes_equal()
andg_bytes_hash()
as parameters tog_hash_table_new()
org_hash_table_new_full()
.GBytes
can also be used as keys in aGTree
by passing theg_bytes_compare()
function tog_tree_new()
.The data pointed to by this bytes must not be modified. For a mutable array of bytes see
See moreGByteArray
. Useg_bytes_unref_to_array()
to create a mutable array for aGBytes
sequence. To create an immutableGBytes
from a mutableGByteArray
, use theg_byte_array_free_to_bytes()
function.Declaration
Swift
public protocol BytesProtocol
-
The
ChecksumProtocol
protocol exposes the methods and properties of an underlyingGChecksum
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeChecksum
. Alternatively, useChecksumRef
as a lighweight,unowned
reference if you already have an instance you just want to use.An opaque structure representing a checksumming operation. To create a new GChecksum, use
See moreg_checksum_new()
. To free a GChecksum, useg_checksum_free()
.Declaration
Swift
public protocol ChecksumProtocol
-
The
CondProtocol
protocol exposes the methods and properties of an underlyingGCond
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeCond
. Alternatively, useCondRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
GCond
struct is an opaque data structure that represents a condition. Threads can block on aGCond
if they find a certain condition to be false. If other threads change the state of this condition they signal theGCond
, and that causes the waiting threads to be woken up.Consider the following example of a shared variable. One or more threads can wait for data to be published to the variable and when another thread publishes the data, it can signal one of the waiting threads to wake up to collect the data.
Here is an example for using GCond to block a thread until a condition is satisfied: (C Language Example):
gpointer current_data = NULL; GMutex data_mutex; GCond data_cond; void push_data (gpointer data) { g_mutex_lock (&data_mutex); current_data = data; g_cond_signal (&data_cond); g_mutex_unlock (&data_mutex); } gpointer pop_data (void) { gpointer data; g_mutex_lock (&data_mutex); while (!current_data) g_cond_wait (&data_cond, &data_mutex); data = current_data; current_data = NULL; g_mutex_unlock (&data_mutex); return data; }
Whenever a thread calls
pop_data()
now, it will wait until current_data is non-nil
, i.e. until some other thread has calledpush_data()
.The example shows that use of a condition variable must always be paired with a mutex. Without the use of a mutex, there would be a race between the check of
current_data
by the while loop inpop_data()
and waiting. Specifically, another thread could setcurrent_data
after the check, and signal the cond (with nobody waiting on it) before the first thread goes to sleep.GCond
is specifically useful for its ability to release the mutex and go to sleep atomically.It is also important to use the
g_cond_wait()
andg_cond_wait_until()
functions only inside a loop which checks for the condition to be true. Seeg_cond_wait()
for an explanation of why the condition may not be true even after it returns.If a
GCond
is allocated in static storage then it can be used without initialisation. Otherwise, you should callg_cond_init()
on it andg_cond_clear()
when done.A
See moreGCond
should only be accessed via the g_cond_ functions.Declaration
Swift
public protocol CondProtocol
-
The
DataProtocol
protocol exposes the methods and properties of an underlyingGData
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeData
. Alternatively, useDataRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
See moreGData
struct is an opaque data structure to represent a Keyed Data List. It should only be accessed via the following functions.Declaration
Swift
public protocol DataProtocol
-
The
DateProtocol
protocol exposes the methods and properties of an underlyingGDate
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeDate
. Alternatively, useDateRef
as a lighweight,unowned
reference if you already have an instance you just want to use.Represents a day between January 1, Year 1 and a few thousand years in the future. None of its members should be accessed directly.
If the
GDate
-struct is obtained fromg_date_new()
, it will be safe to mutate but invalid and thus not safe for calendrical computations.If it’s declared on the stack, it will contain garbage so must be initialized with
See moreg_date_clear()
.g_date_clear()
makes the date invalid but sane. An invalid date doesn’t represent a day, it’s “empty.” A date becomes valid after you set it to a Julian day or you set a day, month, and year.Declaration
Swift
public protocol DateProtocol
-
The
DateTimeProtocol
protocol exposes the methods and properties of an underlyingGDateTime
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeDateTime
. Alternatively, useDateTimeRef
as a lighweight,unowned
reference if you already have an instance you just want to use.
See moreGDateTime
is an opaque structure whose members cannot be accessed directly.Declaration
Swift
public protocol DateTimeProtocol
-
The
DebugKeyProtocol
protocol exposes the methods and properties of an underlyingGDebugKey
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeDebugKey
. Alternatively, useDebugKeyRef
as a lighweight,unowned
reference if you already have an instance you just want to use.Associates a string with a bit flag. Used in
See moreg_parse_debug_string()
.Declaration
Swift
public protocol DebugKeyProtocol
-
The
DirProtocol
protocol exposes the methods and properties of an underlyingGDir
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeDir
. Alternatively, useDirRef
as a lighweight,unowned
reference if you already have an instance you just want to use.An opaque structure representing an opened directory.
See moreDeclaration
Swift
public protocol DirProtocol
-
The
HashTableProtocol
protocol exposes the methods and properties of an underlyingGHashTable
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeHashTable
. Alternatively, useHashTableRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
See moreGHashTable
struct is an opaque data structure to represent a Hash Table. It should only be accessed via the following functions.Declaration
Swift
public protocol HashTableProtocol
-
The
HashTableIterProtocol
protocol exposes the methods and properties of an underlyingGHashTableIter
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeHashTableIter
. Alternatively, useHashTableIterRef
as a lighweight,unowned
reference if you already have an instance you just want to use.A GHashTableIter structure represents an iterator that can be used to iterate over the elements of a
GHashTable
. GHashTableIter structures are typically allocated on the stack and then initialized withg_hash_table_iter_init()
.The iteration order of a
See moreGHashTableIter
over the keys/values in a hash table is not defined.Declaration
Swift
public protocol HashTableIterProtocol
-
The
HmacProtocol
protocol exposes the methods and properties of an underlyingGHmac
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeHmac
. Alternatively, useHmacRef
as a lighweight,unowned
reference if you already have an instance you just want to use.An opaque structure representing a HMAC operation. To create a new GHmac, use
See moreg_hmac_new()
. To free a GHmac, useg_hmac_unref()
.Declaration
Swift
public protocol HmacProtocol
-
The
HookProtocol
protocol exposes the methods and properties of an underlyingGHook
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeHook
. Alternatively, useHookRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
See moreGHook
struct represents a single hook function in aGHookList
.Declaration
Swift
public protocol HookProtocol
-
The
HookListProtocol
protocol exposes the methods and properties of an underlyingGHookList
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeHookList
. Alternatively, useHookListRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
See moreGHookList
struct represents a list of hook functions.Declaration
Swift
public protocol HookListProtocol
-
The
IConvProtocol
protocol exposes the methods and properties of an underlyingGIConv
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeIConv
. Alternatively, useIConvRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The GIConv struct wraps an
See moreiconv()
conversion descriptor. It contains private data and should only be accessed using the following functions.Declaration
Swift
public protocol IConvProtocol
-
The
IOChannelProtocol
protocol exposes the methods and properties of an underlyingGIOChannel
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeIOChannel
. Alternatively, useIOChannelRef
as a lighweight,unowned
reference if you already have an instance you just want to use.A data structure representing an IO Channel. The fields should be considered private and should only be accessed with the following functions.
See moreDeclaration
Swift
public protocol IOChannelProtocol
-
The
IOFuncsProtocol
protocol exposes the methods and properties of an underlyingGIOFuncs
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeIOFuncs
. Alternatively, useIOFuncsRef
as a lighweight,unowned
reference if you already have an instance you just want to use.A table of functions used to handle different types of
See moreGIOChannel
in a generic way.Declaration
Swift
public protocol IOFuncsProtocol
-
The
KeyFileProtocol
protocol exposes the methods and properties of an underlyingGKeyFile
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeKeyFile
. Alternatively, useKeyFileRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The GKeyFile struct contains only private data and should not be accessed directly.
See moreDeclaration
Swift
public protocol KeyFileProtocol
-
The
ListProtocol
protocol exposes the methods and properties of an underlyingGList
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeList
. Alternatively, useListRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
See moreGList
struct is used for each element in a doubly-linked list.Declaration
Swift
public protocol ListProtocol
-
The
LogFieldProtocol
protocol exposes the methods and properties of an underlyingGLogField
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeLogField
. Alternatively, useLogFieldRef
as a lighweight,unowned
reference if you already have an instance you just want to use.Structure representing a single field in a structured log entry. See
g_log_structured()
for details.Log fields may contain arbitrary values, including binary with embedded nul bytes. If the field contains a string, the string must be UTF-8 encoded and have a trailing nul byte. Otherwise,
See morelength
must be set to a non-negative value.Declaration
Swift
public protocol LogFieldProtocol
-
The
MainContextProtocol
protocol exposes the methods and properties of an underlyingGMainContext
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeMainContext
. Alternatively, useMainContextRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
See moreGMainContext
struct is an opaque data type representing a set of sources to be handled in a main loop.Declaration
Swift
public protocol MainContextProtocol
-
The
MainLoopProtocol
protocol exposes the methods and properties of an underlyingGMainLoop
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeMainLoop
. Alternatively, useMainLoopRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
See moreGMainLoop
struct is an opaque data type representing the main event loop of a GLib or GTK+ application.Declaration
Swift
public protocol MainLoopProtocol
-
The
MappedFileProtocol
protocol exposes the methods and properties of an underlyingGMappedFile
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeMappedFile
. Alternatively, useMappedFileRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
See moreGMappedFile
represents a file mapping created withg_mapped_file_new()
. It has only private members and should not be accessed directly.Declaration
Swift
public protocol MappedFileProtocol
-
The
MarkupParseContextProtocol
protocol exposes the methods and properties of an underlyingGMarkupParseContext
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeMarkupParseContext
. Alternatively, useMarkupParseContextRef
as a lighweight,unowned
reference if you already have an instance you just want to use.A parse context is used to parse a stream of bytes that you expect to contain marked-up text.
See
See moreg_markup_parse_context_new()
,GMarkupParser
, and so on for more details.Declaration
Swift
public protocol MarkupParseContextProtocol
-
The
MarkupParserProtocol
protocol exposes the methods and properties of an underlyingGMarkupParser
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeMarkupParser
. Alternatively, useMarkupParserRef
as a lighweight,unowned
reference if you already have an instance you just want to use.Any of the fields in
See moreGMarkupParser
can benil
, in which case they will be ignored. Except for theerror
function, any of these callbacks can set an error; in particular theG_MARKUP_ERROR_UNKNOWN_ELEMENT
,G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE
, andG_MARKUP_ERROR_INVALID_CONTENT
errors are intended to be set from these callbacks. If you set an error from a callback,g_markup_parse_context_parse()
will report that error back to its caller.Declaration
Swift
public protocol MarkupParserProtocol
-
The
MatchInfoProtocol
protocol exposes the methods and properties of an underlyingGMatchInfo
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeMatchInfo
. Alternatively, useMatchInfoRef
as a lighweight,unowned
reference if you already have an instance you just want to use.A GMatchInfo is an opaque struct used to return information about matches.
See moreDeclaration
Swift
public protocol MatchInfoProtocol
-
The
MemVTableProtocol
protocol exposes the methods and properties of an underlyingGMemVTable
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeMemVTable
. Alternatively, useMemVTableRef
as a lighweight,unowned
reference if you already have an instance you just want to use.A set of functions used to perform memory allocation. The same
GMemVTable
must be used for all allocations in the same program; a call tog_mem_set_vtable()
, if it exists, should be prior to any use of GLib.This functions related to this has been deprecated in 2.46, and no longer work.
See moreDeclaration
Swift
public protocol MemVTableProtocol
-
The
NodeProtocol
protocol exposes the methods and properties of an underlyingGNode
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeNode
. Alternatively, useNodeRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
See moreGNode
struct represents one node in a n-ary tree.Declaration
Swift
public protocol NodeProtocol
-
The
OnceProtocol
protocol exposes the methods and properties of an underlyingGOnce
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeOnce
. Alternatively, useOnceRef
as a lighweight,unowned
reference if you already have an instance you just want to use.A
See moreGOnce
struct controls a one-time initialization function. Any one-time initialization function must have its own uniqueGOnce
struct.Declaration
Swift
public protocol OnceProtocol
-
The
OptionContextProtocol
protocol exposes the methods and properties of an underlyingGOptionContext
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeOptionContext
. Alternatively, useOptionContextRef
as a lighweight,unowned
reference if you already have an instance you just want to use.A
See moreGOptionContext
struct defines which options are accepted by the commandline option parser. The struct has only private fields and should not be directly accessed.Declaration
Swift
public protocol OptionContextProtocol
-
The
OptionEntryProtocol
protocol exposes the methods and properties of an underlyingGOptionEntry
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeOptionEntry
. Alternatively, useOptionEntryRef
as a lighweight,unowned
reference if you already have an instance you just want to use.A GOptionEntry struct defines a single option. To have an effect, they must be added to a
See moreGOptionGroup
withg_option_context_add_main_entries()
org_option_group_add_entries()
.Declaration
Swift
public protocol OptionEntryProtocol
-
The
OptionGroupProtocol
protocol exposes the methods and properties of an underlyingGOptionGroup
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeOptionGroup
. Alternatively, useOptionGroupRef
as a lighweight,unowned
reference if you already have an instance you just want to use.A
GOptionGroup
struct defines the options in a single group. The struct has only private fields and should not be directly accessed.All options in a group share the same translation function. Libraries which need to parse commandline options are expected to provide a function for getting a
See moreGOptionGroup
holding their options, which the application can then add to itsGOptionContext
.Declaration
Swift
public protocol OptionGroupProtocol
-
The
PatternSpecProtocol
protocol exposes the methods and properties of an underlyingGPatternSpec
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seePatternSpec
. Alternatively, usePatternSpecRef
as a lighweight,unowned
reference if you already have an instance you just want to use.A GPatternSpec struct is the ‘compiled’ form of a pattern. This structure is opaque and its fields cannot be accessed directly.
See moreDeclaration
Swift
public protocol PatternSpecProtocol
-
The
PollFDProtocol
protocol exposes the methods and properties of an underlyingGPollFD
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seePollFD
. Alternatively, usePollFDRef
as a lighweight,unowned
reference if you already have an instance you just want to use.Represents a file descriptor, which events to poll for, and which events occurred.
See moreDeclaration
Swift
public protocol PollFDProtocol
-
The
PrivateProtocol
protocol exposes the methods and properties of an underlyingGPrivate
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seePrivate
. Alternatively, usePrivateRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
GPrivate
struct is an opaque data structure to represent a thread-local data key. It is approximately equivalent to thepthread_setspecific()
/pthread_getspecific()
APIs on POSIX and toTlsSetValue()
/TlsGetValue()
on Windows.If you don’t already know why you might want this functionality, then you probably don’t need it.
GPrivate
is a very limited resource (as far as 128 per program, shared between all libraries). It is also not possible to destroy aGPrivate
after it has been used. As such, it is only ever acceptable to useGPrivate
in static scope, and even then sparingly so.See
G_PRIVATE_INIT()
for a couple of examples.The
See moreGPrivate
structure should be considered opaque. It should only be accessed via the g_private_ functions.Declaration
Swift
public protocol PrivateProtocol
-
The
PtrArrayProtocol
protocol exposes the methods and properties of an underlyingGPtrArray
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seePtrArray
. Alternatively, usePtrArrayRef
as a lighweight,unowned
reference if you already have an instance you just want to use.Contains the public fields of a pointer array.
See moreDeclaration
Swift
public protocol PtrArrayProtocol
-
The
QueueProtocol
protocol exposes the methods and properties of an underlyingGQueue
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeQueue
. Alternatively, useQueueRef
as a lighweight,unowned
reference if you already have an instance you just want to use.Contains the public fields of a Queue.
See moreDeclaration
Swift
public protocol QueueProtocol
-
The
RWLockProtocol
protocol exposes the methods and properties of an underlyingGRWLock
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeRWLock
. Alternatively, useRWLockRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The GRWLock struct is an opaque data structure to represent a reader-writer lock. It is similar to a
GMutex
in that it allows multiple threads to coordinate access to a shared resource.The difference to a mutex is that a reader-writer lock discriminates between read-only (‘reader’) and full (‘writer’) access. While only one thread at a time is allowed write access (by holding the ‘writer’ lock via
g_rw_lock_writer_lock()
), multiple threads can gain simultaneous read-only access (by holding the ‘reader’ lock viag_rw_lock_reader_lock()
).It is unspecified whether readers or writers have priority in acquiring the lock when a reader already holds the lock and a writer is queued to acquire it.
Here is an example for an array with access functions: (C Language Example):
GRWLock lock; GPtrArray *array; gpointer my_array_get (guint index) { gpointer retval = NULL; if (!array) return NULL; g_rw_lock_reader_lock (&lock); if (index < array->len) retval = g_ptr_array_index (array, index); g_rw_lock_reader_unlock (&lock); return retval; } void my_array_set (guint index, gpointer data) { g_rw_lock_writer_lock (&lock); if (!array) array = g_ptr_array_new (); if (index >= array->len) g_ptr_array_set_size (array, index+1); g_ptr_array_index (array, index) = data; g_rw_lock_writer_unlock (&lock); }
This example shows an array which can be accessed by many readers (the
my_array_get()
function) simultaneously, whereas the writers (themy_array_set()
function) will only be allowed one at a time and only if no readers currently access the array. This is because of the potentially dangerous resizing of the array. Using these functions is fully multi-thread safe now.If a
GRWLock
is allocated in static storage then it can be used without initialisation. Otherwise, you should callg_rw_lock_init()
on it andg_rw_lock_clear()
when done.A GRWLock should only be accessed with the g_rw_lock_ functions.
See moreDeclaration
Swift
public protocol RWLockProtocol
-
The
RandProtocol
protocol exposes the methods and properties of an underlyingGRand
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeRand
. Alternatively, useRandRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The GRand struct is an opaque data structure. It should only be accessed through the g_rand_* functions.
See moreDeclaration
Swift
public protocol RandProtocol
-
The
RecMutexProtocol
protocol exposes the methods and properties of an underlyingGRecMutex
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeRecMutex
. Alternatively, useRecMutexRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The GRecMutex struct is an opaque data structure to represent a recursive mutex. It is similar to a
GMutex
with the difference that it is possible to lock a GRecMutex multiple times in the same thread without deadlock. When doing so, care has to be taken to unlock the recursive mutex as often as it has been locked.If a
GRecMutex
is allocated in static storage then it can be used without initialisation. Otherwise, you should callg_rec_mutex_init()
on it andg_rec_mutex_clear()
when done.A GRecMutex should only be accessed with the g_rec_mutex_ functions.
See moreDeclaration
Swift
public protocol RecMutexProtocol
-
The
RegexProtocol
protocol exposes the methods and properties of an underlyingGRegex
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeRegex
. Alternatively, useRegexRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The g_regex_*() functions implement regular expression pattern matching using syntax and semantics similar to Perl regular expression.
Some functions accept a
start_position
argument, setting it differs from just passing over a shortened string and settingG_REGEX_MATCH_NOTBOL
in the case of a pattern that begins with any kind of lookbehind assertion. For example, consider the pattern “\Biss\B” which finds occurrences of “iss” in the middle of words. (“\B” matches only if the current position in the subject is not a word boundary.) When applied to the string “Mississipi” from the fourth byte, namely “issipi”, it does not match, because “\B” is always false at the start of the subject, which is deemed to be a word boundary. However, if the entire string is passed , but withstart_position
set to 4, it finds the second occurrence of “iss” because it is able to look behind the starting point to discover that it is preceded by a letter.Note that, unless you set the
G_REGEX_RAW
flag, all the strings passed to these functions must be encoded in UTF-8. The lengths and the positions inside the strings are in bytes and not in characters, so, for instance, “\xc3\xa0” (i.e. “à”) is two bytes long but it is treated as a single character. If you setG_REGEX_RAW
the strings can be non-valid UTF-8 strings and a byte is treated as a character, so “\xc3\xa0” is two bytes and two characters long.When matching a pattern, “\n” matches only against a “\n” character in the string, and “\r” matches only a “\r” character. To match any newline sequence use “\R”. This particular group matches either the two-character sequence CR + LF (“\r\n”), or one of the single characters LF (linefeed, U+000A, “\n”), VT vertical tab, U+000B, “\v”), FF (formfeed, U+000C, “\f”), CR (carriage return, U+000D, “\r”), NEL (next line, U+0085), LS (line separator, U+2028), or PS (paragraph separator, U+2029).
The behaviour of the dot, circumflex, and dollar metacharacters are affected by newline characters, the default is to recognize any newline character (the same characters recognized by “\R”). This can be changed with
G_REGEX_NEWLINE_CR
,G_REGEX_NEWLINE_LF
andG_REGEX_NEWLINE_CRLF
compile options, and withG_REGEX_MATCH_NEWLINE_ANY
,G_REGEX_MATCH_NEWLINE_CR
,G_REGEX_MATCH_NEWLINE_LF
andG_REGEX_MATCH_NEWLINE_CRLF
match options. These settings are also relevant when compiling a pattern ifG_REGEX_EXTENDED
is set, and an unescaped “#” outside a character class is encountered. This indicates a comment that lasts until after the next newline.When setting the
G_REGEX_JAVASCRIPT_COMPAT
flag, pattern syntax and pattern matching is changed to be compatible with the way that regular expressions work in JavaScript. More precisely, a lonely ‘]’ character in the pattern is a syntax error; the ‘\x’ escape only allows 0 to 2 hexadecimal digits, and you must use the ‘\u’ escape sequence with 4 hex digits to specify a unicode codepoint instead of ‘\x’ or ‘x{….}’. If ‘\x’ or ‘\u’ are not followed by the specified number of hex digits, they match ‘x’ and ‘u’ literally; also ‘\U’ always matches ‘U’ instead of being an error in the pattern. Finally, pattern matching is modified so that back references to an unset subpattern group produces a match with the empty string instead of an error. Seepcreapi(3)
for more information.Creating and manipulating the same
GRegex
structure from different threads is not a problem asGRegex
does not modify its internal state between creation and destruction, on the other handGMatchInfo
is not threadsafe.The regular expressions low-level functionalities are obtained through the excellent PCRE library written by Philip Hazel.
See moreDeclaration
Swift
public protocol RegexProtocol
-
The
SListProtocol
protocol exposes the methods and properties of an underlyingGSList
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeSList
. Alternatively, useSListRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
See moreGSList
struct is used for each element in the singly-linked list.Declaration
Swift
public protocol SListProtocol
-
The
ScannerProtocol
protocol exposes the methods and properties of an underlyingGScanner
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeScanner
. Alternatively, useScannerRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The data structure representing a lexical scanner.
You should set
input_name
after creating the scanner, since it is used by the default message handler when displaying warnings and errors. If you are scanning a file, the filename would be a good choice.The
user_data
andmax_parse_errors
fields are not used. If you need to associate extra data with the scanner you can place them here.If you want to use your own message handler you can set the
See moremsg_handler
field. The type of the message handler function is declared byGScannerMsgFunc
.Declaration
Swift
public protocol ScannerProtocol
-
The
ScannerConfigProtocol
protocol exposes the methods and properties of an underlyingGScannerConfig
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeScannerConfig
. Alternatively, useScannerConfigRef
as a lighweight,unowned
reference if you already have an instance you just want to use.Specifies the
See moreGScanner
parser configuration. Most settings can be changed during the parsing phase and will affect the lexical parsing of the next unpeeked token.Declaration
Swift
public protocol ScannerConfigProtocol
-
The
SequenceProtocol
protocol exposes the methods and properties of an underlyingGSequence
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeSequence
. Alternatively, useSequenceRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
See moreGSequence
struct is an opaque data type representing a sequence data type.Declaration
Swift
public protocol SequenceProtocol
-
The
SequenceIterProtocol
protocol exposes the methods and properties of an underlyingGSequenceIter
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeSequenceIter
. Alternatively, useSequenceIterRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
See moreGSequenceIter
struct is an opaque data type representing an iterator pointing into aGSequence
.Declaration
Swift
public protocol SequenceIterProtocol
-
The
SourceProtocol
protocol exposes the methods and properties of an underlyingGSource
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeSource
. Alternatively, useSourceRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
See moreGSource
struct is an opaque data type representing an event source.Declaration
Swift
public protocol SourceProtocol
-
The
SourceCallbackFuncsProtocol
protocol exposes the methods and properties of an underlyingGSourceCallbackFuncs
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeSourceCallbackFuncs
. Alternatively, useSourceCallbackFuncsRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
See moreGSourceCallbackFuncs
struct contains functions for managing callback objects.Declaration
Swift
public protocol SourceCallbackFuncsProtocol
-
The
SourceFuncsProtocol
protocol exposes the methods and properties of an underlyingGSourceFuncs
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeSourceFuncs
. Alternatively, useSourceFuncsRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
GSourceFuncs
struct contains a table of functions used to handle event sources in a generic manner.For idle sources, the prepare and check functions always return
true
to indicate that the source is always ready to be processed. The prepare function also returns a timeout value of 0 to ensure that thepoll()
call doesn’t block (since that would be time wasted which could have been spent running the idle function).For timeout sources, the prepare and check functions both return
true
if the timeout interval has expired. The prepare function also returns a timeout value to ensure that thepoll()
call doesn’t block too long and miss the next timeout.For file descriptor sources, the prepare function typically returns
See morefalse
, since it must wait untilpoll()
has been called before it knows whether any events need to be processed. It sets the returned timeout to -1 to indicate that it doesn’t mind how long thepoll()
call blocks. In the check function, it tests the results of thepoll()
call to see if the required condition has been met, and returnstrue
if so.Declaration
Swift
public protocol SourceFuncsProtocol
-
The
See moreSourcePrivateProtocol
protocol exposes the methods and properties of an underlyingGSourcePrivate
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeSourcePrivate
. Alternatively, useSourcePrivateRef
as a lighweight,unowned
reference if you already have an instance you just want to use.Declaration
Swift
public protocol SourcePrivateProtocol
-
The
StatBufProtocol
protocol exposes the methods and properties of an underlyingGStatBuf
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeStatBuf
. Alternatively, useStatBufRef
as a lighweight,unowned
reference if you already have an instance you just want to use.A type corresponding to the appropriate struct type for the
stat()
system call, depending on the platform and/or compiler being used.See
See moreg_stat()
for more information.Declaration
Swift
public protocol StatBufProtocol
-
The
StringChunkProtocol
protocol exposes the methods and properties of an underlyingGStringChunk
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeStringChunk
. Alternatively, useStringChunkRef
as a lighweight,unowned
reference if you already have an instance you just want to use.An opaque data structure representing String Chunks. It should only be accessed by using the following functions.
See moreDeclaration
Swift
public protocol StringChunkProtocol
-
The
StringTypeProtocol
protocol exposes the methods and properties of an underlyingGString
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeStringType
. Alternatively, useStringTypeRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The GString struct contains the public fields of a GString.
See moreDeclaration
Swift
public protocol StringTypeProtocol
-
The
TestCaseProtocol
protocol exposes the methods and properties of an underlyingGTestCase
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeTestCase
. Alternatively, useTestCaseRef
as a lighweight,unowned
reference if you already have an instance you just want to use.An opaque structure representing a test case.
See moreDeclaration
Swift
public protocol TestCaseProtocol
-
The
See moreTestConfigProtocol
protocol exposes the methods and properties of an underlyingGTestConfig
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeTestConfig
. Alternatively, useTestConfigRef
as a lighweight,unowned
reference if you already have an instance you just want to use.Declaration
Swift
public protocol TestConfigProtocol
-
The
See moreTestLogBufferProtocol
protocol exposes the methods and properties of an underlyingGTestLogBuffer
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeTestLogBuffer
. Alternatively, useTestLogBufferRef
as a lighweight,unowned
reference if you already have an instance you just want to use.Declaration
Swift
public protocol TestLogBufferProtocol
-
The
See moreTestLogMsgProtocol
protocol exposes the methods and properties of an underlyingGTestLogMsg
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeTestLogMsg
. Alternatively, useTestLogMsgRef
as a lighweight,unowned
reference if you already have an instance you just want to use.Declaration
Swift
public protocol TestLogMsgProtocol
-
The
TestSuiteProtocol
protocol exposes the methods and properties of an underlyingGTestSuite
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeTestSuite
. Alternatively, useTestSuiteRef
as a lighweight,unowned
reference if you already have an instance you just want to use.An opaque structure representing a test suite.
See moreDeclaration
Swift
public protocol TestSuiteProtocol
-
The
ThreadProtocol
protocol exposes the methods and properties of an underlyingGThread
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeThread
. Alternatively, useThreadRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
GThread
struct represents a running thread. This struct is returned byg_thread_new()
org_thread_try_new()
. You can obtain theGThread
struct representing the current thread by callingg_thread_self()
.GThread is refcounted, see
g_thread_ref()
andg_thread_unref()
. The thread represented by it holds a reference while it is running, andg_thread_join()
consumes the reference that it is given, so it is normally not necessary to manage GThread references explicitly.The structure is opaque – none of its fields may be directly accessed.
See moreDeclaration
Swift
public protocol ThreadProtocol
-
The
ThreadPoolProtocol
protocol exposes the methods and properties of an underlyingGThreadPool
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeThreadPool
. Alternatively, useThreadPoolRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The
See moreGThreadPool
struct represents a thread pool. It has three public read-only members, but the underlying struct is bigger, so you must not copy this struct.Declaration
Swift
public protocol ThreadPoolProtocol
-
The
TimeValProtocol
protocol exposes the methods and properties of an underlyingGTimeVal
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeTimeVal
. Alternatively, useTimeValRef
as a lighweight,unowned
reference if you already have an instance you just want to use.Represents a precise time, with seconds and microseconds. Similar to the struct timeval returned by the
gettimeofday()
UNIX system call.GLib is attempting to unify around the use of 64-bit integers to represent microsecond-precision time. As such, this type will be removed from a future version of GLib. A consequence of using
See moreglong
fortv_sec
is that on 32-bit systemsGTimeVal
is subject to the year 2038 problem.Declaration
Swift
public protocol TimeValProtocol
-
The
TimeZoneProtocol
protocol exposes the methods and properties of an underlyingGTimeZone
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeTimeZone
. Alternatively, useTimeZoneRef
as a lighweight,unowned
reference if you already have an instance you just want to use.
See moreGTimeZone
is an opaque structure whose members cannot be accessed directly.Declaration
Swift
public protocol TimeZoneProtocol
-
The
TimerProtocol
protocol exposes the methods and properties of an underlyingGTimer
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeTimer
. Alternatively, useTimerRef
as a lighweight,unowned
reference if you already have an instance you just want to use.Opaque datatype that records a start time.
See moreDeclaration
Swift
public protocol TimerProtocol
-
The
TrashStackProtocol
protocol exposes the methods and properties of an underlyingGTrashStack
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeTrashStack
. Alternatively, useTrashStackRef
as a lighweight,unowned
reference if you already have an instance you just want to use.Each piece of memory that is pushed onto the stack is cast to a GTrashStack*.
See moreDeclaration
Swift
public protocol TrashStackProtocol
-
The
TreeProtocol
protocol exposes the methods and properties of an underlyingGTree
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeTree
. Alternatively, useTreeRef
as a lighweight,unowned
reference if you already have an instance you just want to use.The GTree struct is an opaque data structure representing a balanced binary tree. It should be accessed only by using the following functions.
See moreDeclaration
Swift
public protocol TreeProtocol
-
The
VariantProtocol
protocol exposes the methods and properties of an underlyingGVariant
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeVariant
. Alternatively, useVariantRef
as a lighweight,unowned
reference if you already have an instance you just want to use.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; or complex types, like an array of two strings, or a dictionary of key value pairs. AGVariant
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 DBus, or when saving settings using GSettings.
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 can use:(C Language Example):
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.More advanced examples of
GVariant
in use can be found in documentation for GVariant format strings.The range of possible values is determined by the type.
The type system used by
GVariant
isGVariantType
.GVariant
instances always have a type and a value (which are given at construction time). The type and value of aGVariant
instance can never change other than by theGVariant
itself being destroyed. AGVariant
cannot contain a pointer.GVariant
is reference counted usingg_variant_ref()
andg_variant_unref()
.GVariant
also has floating reference counts – seeg_variant_ref_sink()
.GVariant
is completely threadsafe. AGVariant
instance can be concurrently accessed in any way from any number of threads without problems.GVariant
is heavily optimised for dealing with data in serialised form. It works particularly well with data located in memory-mapped files. It can perform nearly all deserialisation operations in a small constant time, usually touching only a single memory page. SerialisedGVariant
data can also be sent over the network.GVariant
is largely compatible with D-Bus. Almost all types ofGVariant
instances can be sent over D-Bus. SeeGVariantType
for exceptions. (However,GVariant
‘s serialisation format is not the same as the serialisation format of a D-Bus message body: useGDBusMessage
, in the gio library, for those.)For space-efficiency, the
GVariant
serialisation 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-endianG_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 ingsize
. For example, it is reasonable to have a 2GB file mapped into memory withGMappedFile
, and callg_variant_new_from_data()
on it.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 with type inferencing.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 purposes: memory for serialised data, memory for the type information cache, buffer management memory and memory for theGVariant
structure itself.Serialised Data Memory
This is the memory that is used for storing GVariant data in serialised 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 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 use the same amount of space (sometimes plus one byte) as the equivalent non-maybe-typed value to represent the non-null case.
Arrays use the amount of space required to store each of their members, concatenated. Additionally, if the items stored in an array are not of a fixed-size (ie: strings, other arrays, etc) then an additional framing offset is stored for each item. The size of this offset is either 1, 2 or 4 bytes depending on the overall size of the container. Additionally, extra padding bytes are added as required for alignment of child values.
Tuples (including dictionary entries) use the amount of space required to store each of their members, concatenated, plus one framing offset (as per arrays) for each non-fixed-sized item in the tuple, except for the last one. Additionally, extra padding bytes are added as required for alignment of child values.
Variants use the same amount of space as the item inside of the variant, plus 1 byte, plus the length of the type string for the item inside the variant.
As an example, consider a dictionary mapping strings to variants. In the case that the dictionary is empty, 0 bytes are required for the serialisation.
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 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 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 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. 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 information structure is kept in the type information cache. The type information structure is required for rapid deserialisation.
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 usingGVariant
.Aside from the type information structures stored in read-only memory, there are two forms of type information. One is used for container types where there is a single element type: arrays and 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 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).
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 string) This means that on 32-bit systems, the cache entry for “{sv}” would require 61 bytes of memory (plus malloc overhead).
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 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.Although these sizes may seem large it is important to remember that a program will probably only have a very small number of different types of values in it and that only one type information structure is required for many different values of the same type.
Buffer Management Memory
GVariant
uses an internal buffer management structure to deal with the various different possible sources of serialised data that it uses. The buffer is responsible for ensuring that the correct call is made when the data is no longer in use byGVariant
. This may involve ag_free()
or ag_slice_free()
or eveng_mapped_file_unref()
.One buffer management structure is used for each chunk of serialised data. The size of the buffer management structure 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.GVariant
structures only exist if they are explicitly created with API calls. For example, if aGVariant
is constructed out of serialised 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 1GVariant
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 callg_variant_unref()
). The type information is shared. The serialised data and the buffer management structure for that serialised data is shared by the child.Summary
To put the entire example together, for our dictionary mapping 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 serialised data, 16 bytes for buffer management and 24 bytes for the
See moreGVariant
instance, or a total of 160 bytes, plus malloc overhead. If we were to useg_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 serialised data and buffer management for those dictionaries, but the type information would be shared.Declaration
Swift
public protocol VariantProtocol
-
The
VariantBuilderProtocol
protocol exposes the methods and properties of an underlyingGVariantBuilder
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeVariantBuilder
. Alternatively, useVariantBuilderRef
as a lighweight,unowned
reference if you already have an instance you just want to use.A utility type for constructing container-type
GVariant
instances.This is an opaque structure and may only be accessed using the following functions.
See moreGVariantBuilder
is not threadsafe in any way. Do not attempt to access it from more than one thread.Declaration
Swift
public protocol VariantBuilderProtocol
-
The
VariantDictProtocol
protocol exposes the methods and properties of an underlyingGVariantDict
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeVariantDict
. Alternatively, useVariantDictRef
as a lighweight,unowned
reference if you already have an instance you just want to use.GVariantDict
is a mutable interface toGVariant
dictionaries.It can be used for doing a sequence of dictionary lookups in an efficient way on an existing
GVariant
dictionary or it can be used to construct new dictionaries with a hashtable-like interface. It can also be used for taking existing dictionaries and modifying them in order to create new ones.GVariantDict
can only be used withG_VARIANT_TYPE_VARDICT
dictionaries.It is possible to use
GVariantDict
allocated on the stack or on the heap. When using a stack-allocatedGVariantDict
, you begin with a call tog_variant_dict_init()
and free the resources with a call tog_variant_dict_clear()
.Heap-allocated
GVariantDict
follows normal refcounting rules: you allocate it withg_variant_dict_new()
and useg_variant_dict_ref()
andg_variant_dict_unref()
.g_variant_dict_end()
is used to convert theGVariantDict
back into a dictionary-typeGVariant
. When used with stack-allocated instances, this also implicitly frees all associated memory, but for heap-allocated instances, you must still callg_variant_dict_unref()
afterwards.You will typically want to use a heap-allocated
GVariantDict
when you expose it as part of an API. For most other uses, the stack-allocated form will be more convenient.Consider the following two examples that do the same thing in each style: take an existing dictionary and look up the “count” uint32 key, adding 1 to it if it is found, or returning an error if the key is not found. Each returns the new dictionary as a floating
GVariant
.Using a stack-allocated GVariantDict
(C Language Example):
GVariant * add_to_count (GVariant *orig, GError **error) { GVariantDict dict; guint32 count; g_variant_dict_init (&dict, orig); if (!g_variant_dict_lookup (&dict, "count", "u", &count)) { g_set_error (...); g_variant_dict_clear (&dict); return NULL; } g_variant_dict_insert (&dict, "count", "u", count + 1); return g_variant_dict_end (&dict); }
Using heap-allocated GVariantDict
(C Language Example):
See moreGVariant * add_to_count (GVariant *orig, GError **error) { GVariantDict *dict; GVariant *result; guint32 count; dict = g_variant_dict_new (orig); if (g_variant_dict_lookup (dict, "count", "u", &count)) { g_variant_dict_insert (dict, "count", "u", count + 1); result = g_variant_dict_end (dict); } else { g_set_error (...); result = NULL; } g_variant_dict_unref (dict); return result; }
Declaration
Swift
public protocol VariantDictProtocol
-
The
VariantIterProtocol
protocol exposes the methods and properties of an underlyingGVariantIter
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeVariantIter
. Alternatively, useVariantIterRef
as a lighweight,unowned
reference if you already have an instance you just want to use.
See moreGVariantIter
is an opaque data structure and can only be accessed using the following functions.Declaration
Swift
public protocol VariantIterProtocol
-
The
VariantTypeProtocol
protocol exposes the methods and properties of an underlyingGVariantType
instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, seeVariantType
. Alternatively, useVariantTypeRef
as a lighweight,unowned
reference if you already have an instance you just want to use.This section introduces the GVariant type system. It is based, in large part, on the D-Bus type system, with two major changes and some minor lifting of restrictions. The D-Bus specification, therefore, provides a significant amount of information that is useful when working with GVariant.
The first major change with respect to the D-Bus type system is the introduction of maybe (or “nullable”) types. Any type in GVariant can be converted to a maybe type, in which case, “nothing” (or “null”) becomes a valid value. Maybe types have been added by introducing the character “m” to type strings.
The second major change is that the GVariant type system supports the concept of “indefinite types” – types that are less specific than the normal types found in D-Bus. For example, it is possible to speak of “an array of any type” in GVariant, where the D-Bus type system would require you to speak of “an array of integers” or “an array of strings”. Indefinite types have been added by introducing the characters “*”, “?” and “r” to type strings.
Finally, all arbitrary restrictions relating to the complexity of types are lifted along with the restriction that dictionary entries may only appear nested inside of arrays.
Just as in D-Bus, GVariant types are described with strings (“type strings”). Subject to the differences mentioned above, these strings are of the same form as those found in DBus. Note, however: D-Bus always works in terms of messages and therefore individual type strings appear nowhere in its interface. Instead, “signatures” are a concatenation of the strings of the type of each argument in a message. GVariant deals with single values directly so GVariant type strings always describe the type of exactly one value. This means that a D-Bus signature string is generally not a valid GVariant type string – except in the case that it is the signature of a message containing exactly one argument.
An indefinite type is similar in spirit to what may be called an abstract type in other type systems. No value can exist that has an indefinite type as its type, but values can exist that have types that are subtypes of indefinite types. That is to say,
g_variant_get_type()
will never return an indefinite type, but callingg_variant_is_of_type()
with an indefinite type may returntrue
. For example, you cannot have a value that represents “an array of no particular type”, but you can have an “array of integers” which certainly matches the type of “an array of no particular type”, since “array of integers” is a subtype of “array of no particular type”.This is similar to how instances of abstract classes may not directly exist in other type systems, but instances of their non-abstract subtypes may. For example, in GTK, no object that has the type of
GtkBin
can exist (sinceGtkBin
is an abstract class), but aGtkWindow
can certainly be instantiated, and you would say that theGtkWindow
is aGtkBin
(sinceGtkWindow
is a subclass ofGtkBin
).GVariant Type Strings
A GVariant type string can be any of the following:
any basic type string (listed below)
“v”, “r” or “*”
one of the characters ‘a’ or ‘m’, followed by another type string
the character ‘(’, followed by a concatenation of zero or more other type strings, followed by the character ‘)’
the character ‘{’, followed by a basic type string (see below), followed by another type string, followed by the character ‘}’
A basic type string describes a basic type (as per
g_variant_type_is_basic()
) and is always a single character in length. The valid basic type strings are “b”, “y”, “n”, “q”, “i”, “u”, “x”, “t”, “h”, “d”, “s”, “o”, “g” and “?”.The above definition is recursive to arbitrary depth. “aaaaai” and “(
ui(nq((y)
))s)” are both valid type strings, as is"a(aa(ui)
(qna{ya(yd)
}))“. In order to not hit memory limits,GVariant
imposes a limit on recursion depth of 65 nested containers. This is the limit in the D-Bus specification (64) plus one to allow aGDBusMessage
to be nested in a top-level tuple.The meaning of each of the characters is as follows:
b
: the type string ofG_VARIANT_TYPE_BOOLEAN
; a boolean value.y
: the type string ofG_VARIANT_TYPE_BYTE
; a byte.n
: the type string ofG_VARIANT_TYPE_INT16
; a signed 16 bit integer.q
: the type string ofG_VARIANT_TYPE_UINT16
; an unsigned 16 bit integer.i
: the type string ofG_VARIANT_TYPE_INT32
; a signed 32 bit integer.u
: the type string ofG_VARIANT_TYPE_UINT32
; an unsigned 32 bit integer.x
: the type string ofG_VARIANT_TYPE_INT64
; a signed 64 bit integer.t
: the type string ofG_VARIANT_TYPE_UINT64
; an unsigned 64 bit integer.h
: the type string ofG_VARIANT_TYPE_HANDLE
; a signed 32 bit value that, by convention, is used as an index into an array of file descriptors that are sent alongside a D-Bus message.d
: the type string ofG_VARIANT_TYPE_DOUBLE
; a double precision floating point value.s
: the type string ofG_VARIANT_TYPE_STRING
; a string.o
: the type string ofG_VARIANT_TYPE_OBJECT_PATH
; a string in the form of a D-Bus object path.g
: the type string ofG_VARIANT_TYPE_SIGNATURE
; a string in the form of a D-Bus type signature.?
: the type string ofG_VARIANT_TYPE_BASIC
; an indefinite type that is a supertype of any of the basic types.v
: the type string ofG_VARIANT_TYPE_VARIANT
; a container type that contain any other type of value.a
: used as a prefix on another type string to mean an array of that type; the type string "ai”, for example, is the type of an array of signed 32-bit integers.m
: used as a prefix on another type string to mean a “maybe”, or “nullable”, version of that type; the type string “ms”, for example, is the type of a value that maybe contains a string, or maybe contains nothing.()
: used to enclose zero or more other concatenated type strings to create a tuple type; the type string “(is)”, for example, is the type of a pair of an integer and a string.r
: the type string ofG_VARIANT_TYPE_TUPLE
; an indefinite type that is a supertype of any tuple type, regardless of the number of items.{}
: used to enclose a basic type string concatenated with another type string to create a dictionary entry type, which usually appears inside of an array to form a dictionary; the type string “a{sd}”, for example, is the type of a dictionary that maps strings to double precision floating point values.
The first type (the basic type) is the key type and the second type is the value type. The reason that the first type is restricted to being a basic type is so that it can easily be hashed.
*
: the type string ofG_VARIANT_TYPE_ANY
; the indefinite type that is a supertype of all types. Note that, as with all type strings, this character represents exactly one type. It cannot be used inside of tuples to mean “any number of items”.
Any type string of a container that contains an indefinite type is, itself, an indefinite type. For example, the type string “a*” (corresponding to
G_VARIANT_TYPE_ARRAY
) is an indefinite type that is a supertype of every array type. “(*s)” is a supertype of all tuples that contain exactly two items where the second item is a string.“a{?}” is an indefinite type that is a supertype of all arrays containing dictionary entries where the key is any basic type and the value is any type at all. This is, by definition, a dictionary, so this type string corresponds to
See moreG_VARIANT_TYPE_DICTIONARY
. Note that, due to the restriction that the key of a dictionary entry must be a basic type, “{*}” is not a valid type string.Declaration
Swift
public protocol VariantTypeProtocol


all the movies
Whoops!
×
We couldn't find a movie with that title. Please double-check and try again.
Is this the movie that you're looking for?
×
Add this movie to your library.
×
Find a movie to review
Find movie
Show my movies
Hide my movies


What people in Hong Kong are saying after days of violence
HONG KONG, Nov 13 — Quotes from people in Hong Kong's central and financial districts and East Kowloon today after days of protests and violence that have caused widespread disruption in many parts of the territory.
They declined to give their full names owing to the sensitivity of talking about the protests.
Financial District, Central:
Wai-Chung, 57, construction worker
“The government is a big machine and needs time. We know that parts of the machine are not working, but you need to allow it time to fix itself. People already told the government the machine is not working.”
He had a meeting scheduled in the financial district, but it was cancelled owing to the disruption to the transport system.
“What they call the five demands are not achievable. There’s no room for bargaining,” he said, mentioning that he attended protests in June but no longer supports the protesters.
“For some people trying to make a change, they’ve stepped up their actions. It’s not acceptable to most people. They have freedoms to express their views but if they take the actions, they should take responsibility for the damages and consequences.”
Liu, 25, works in real estate
“I’m not saying all the violence is right, but the values they are striving for are always right,” said Liu, who wore a turquoise face mask, referring to the protesters.
“Because the roots have not yet been solved, the government has not replied to the demands, people have escalated the violence to get the government’s attention,” said Liu, who has attended lunch-time rallies over the past two days.
“The biggest problem is setting up the independent investigation to investigate police violence. As long as the government doesn’t reply to the demands, the violence will go on and keep escalating.”
He sees two ways forward:
“The government will use extreme situations to stop the violence, like not letting people go out at night. But I think that will be slim because it's too extreme and will be condemned by western countries. Hong Kong is still an international city.... Or the government will surrender”
Law, 63
“I have been crying watching the footage at the universities.”
“We are hopeless and helpless in Hong Kong now. The British did not give us democracy, but we did have our freedoms. We need help from the rest of the world.”
Panda
“Hong Kong belongs to China, these people don’t need to be scared. Did you see what happened at the university last night, I have a lot of friends who are leaving Hong Kong to move back to Shenzhen, the mainland, to get away from everything crazy that is happening here,” said Panda, who is from mainland Chinese and has lived in Hong Kong for seven years.
Michelle, 32, marketer
“It hurts, really hurts. It’s not just hurting Hong Kong’s economy, but also tearing every Hong Konger’s heart apart. This is going to leave us a lifelong scar and time won’t take that away.”
Kowloon:
Alexandra, 42, works in insurance
“It is very painful to watch my city turn into this.  There are many children inside the station, do you see anybody shouting at them? They are shouting at MTR (staff). Everyone is very tense, nobody is rational anymore. But when you see traffic police shooting at students how can you be reasonable? I want the world to know that Carrie Lam has destroyed this city and Hong Kong police are acting like Chinese police,” said Alexandra, dressed in a long, wavy black skirt and a white shirt and wearing a surgical mask.
“I grew up here. I’ve been working for almost 20 years for the same company. I never missed a day of work. This is the second time this week. I have two children, they can’t go to school. I always worry about (the children) being arrested. I don’t participate in the protests, I am too old for that. But you see on TV, police beating up children, Hong Kong’s children. Is that reasonable? What is wrong with what they are demanding? We all want to return to normal, but how can the government do that if they don’t listen to what Hong Kongers have been asking for. It’s been five months already and they still don’t care.”
Jannet, 29, receptionist
"My destination is Mong Kok. Even if I get there, it’s the tear gas capital of the world. Will I be able to get back? My husband is always working from home when this happens, but I’m a receptionist. I can’t be a receptionist from home, can I?”
“There’s three of us taking turns, but the other two live close by. I’m worried about my job. They know it’s not my fault but at the end of the day my colleagues can’t cover for me forever. Do I blame anyone? I blame the MTR. The government is trying to turn Hong Kongers against the students and all the protesters. But if they just listened to the protesters none of this would happen.” — Reuters