diff options
Diffstat (limited to 'gir')
| -rw-r--r-- | gir/gio-2.0.c | 2 | ||||
| -rw-r--r-- | gir/glib-2.0.c | 674 |
2 files changed, 674 insertions, 2 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index db030057..20842024 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -23806,7 +23806,7 @@ * * Gets the attribute type, value and status for an attribute key. * - * Returns: %TRUE if @info has an attribute named @attribute, + * Returns: (transfer none): %TRUE if @info has an attribute named @attribute, * %FALSE otherwise. */ diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index ce173474..09eb0da0 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -5090,6 +5090,132 @@ /** + * SECTION:arcbox + * @Title: Atomically reference counted data + * @Short_description: Allocated memory with atomic reference counting semantics + * + * An "atomically reference counted box", or "ArcBox", is an opaque wrapper + * data type that is guaranteed to be as big as the size of a given data type, + * and which augments the given data type with thread safe reference counting + * semantics for its memory management. + * + * ArcBox is useful if you have a plain old data type, like a structure + * typically placed on the stack, and you wish to provide additional API + * to use it on the heap; or if you want to implement a new type to be + * passed around by reference without necessarily implementing copy/free + * semantics or your own reference counting. + * + * The typical use is: + * + * |[<!-- language="C" --> + * typedef struct { + * char *name; + * char *address; + * char *city; + * char *state; + * int age; + * } Person; + * + * Person * + * person_new (void) + * { + * return g_atomic_rc_box_new0 (Person); + * } + * ]| + * + * Every time you wish to acquire a reference on the memory, you should + * call g_atomic_rc_box_acquire(); similarly, when you wish to release a reference + * you should call g_atomic_rc_box_release(): + * + * |[<!-- language="C" --> + * // Add a Person to the Database; the Database acquires ownership + * // of the Person instance + * void + * add_person_to_database (Database *db, Person *p) + * { + * db->persons = g_list_prepend (db->persons, g_atomic_rc_box_acquire (p)); + * } + * + * // Removes a Person from the Database; the reference acquired by + * // add_person_to_database() is released here + * void + * remove_person_from_database (Database *db, Person *p) + * { + * db->persons = g_list_remove (db->persons, p); + * g_atomic_rc_box_release (p); + * } + * ]| + * + * If you have additional memory allocated inside the structure, you can + * use g_atomic_rc_box_release_full(), which takes a function pointer, which + * will be called if the reference released was the last: + * + * |[<!-- language="C" --> + * void + * person_clear (Person *p) + * { + * g_free (p->name); + * g_free (p->address); + * g_free (p->city); + * g_free (p->state); + * } + * + * void + * remove_person_from_database (Database *db, Person *p) + * { + * db->persons = g_list_remove (db->persons, p); + * g_atomic_rc_box_release_full (p, (GDestroyNotify) person_clear); + * } + * ]| + * + * If you wish to transfer the ownership of a reference counted data + * type without increasing the reference count, you can use g_steal_pointer(): + * + * |[<!-- language="C" --> + * Person *p = g_atomic_rc_box_new (Person); + * + * fill_person_details (p); + * + * add_person_to_database (db, g_steal_pointer (&p)); + * ]| + * + * ## Thread safety + * + * The reference counting operations on data allocated using g_atomic_rc_box_alloc(), + * g_atomic_rc_box_new(), and g_atomic_rc_box_dup() are guaranteed to be atomic, and thus + * can be safely be performed by different threads. It is important to note that + * only the reference acquisition and release are atomic; changes to the content + * of the data are your responsibility. + * + * ## Automatic pointer clean up + * + * If you want to add g_autoptr() support to your plain old data type through + * reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and + * g_atomic_rc_box_release(): + * + * |[<!-- language="C" --> + * G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_atomic_rc_box_release) + * ]| + * + * If you need to clear the contents of the data, you will need to use an + * ancillary function that calls g_rc_box_release_full(): + * + * |[<!-- laguage="C" --> + * static void + * my_data_struct_release (MyDataStruct *data) + * { + * // my_data_struct_clear() is defined elsewhere + * g_atomic_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear); + * } + * + * G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_clear) + * ]| + * + * Since: 2.58. + */ + + +/** * SECTION:arrays * @title: Arrays * @short_description: arrays of arbitrary elements which grow @@ -7837,6 +7963,137 @@ /** + * SECTION:rcbox + * @Title: Reference counted data + * @Short_description: Allocated memory with reference counting semantics + * + * A "reference counted box", or "RcBox", is an opaque wrapper data type + * that is guaranteed to be as big as the size of a given data type, and + * which augments the given data type with reference counting semantics + * for its memory management. + * + * RcBox is useful if you have a plain old data type, like a structure + * typically placed on the stack, and you wish to provide additional API + * to use it on the heap; or if you want to implement a new type to be + * passed around by reference without necessarily implementing copy/free + * semantics or your own reference counting. + * + * The typical use is: + * + * |[<!-- language="C" --> + * typedef struct { + * char *name; + * char *address; + * char *city; + * char *state; + * int age; + * } Person; + * + * Person * + * person_new (void) + * { + * return g_rc_box_new0 (Person); + * } + * ]| + * + * Every time you wish to acquire a reference on the memory, you should + * call g_rc_box_acquire(); similarly, when you wish to release a reference + * you should call g_rc_box_release(): + * + * |[<!-- language="C" --> + * // Add a Person to the Database; the Database acquires ownership + * // of the Person instance + * void + * add_person_to_database (Database *db, Person *p) + * { + * db->persons = g_list_prepend (db->persons, g_rc_box_acquire (p)); + * } + * + * // Removes a Person from the Database; the reference acquired by + * // add_person_to_database() is released here + * void + * remove_person_from_database (Database *db, Person *p) + * { + * db->persons = g_list_remove (db->persons, p); + * g_rc_box_release (p); + * } + * ]| + * + * If you have additional memory allocated inside the structure, you can + * use g_rc_box_release_full(), which takes a function pointer, which + * will be called if the reference released was the last: + * + * |[<!-- language="C" --> + * void + * person_clear (Person *p) + * { + * g_free (p->name); + * g_free (p->address); + * g_free (p->city); + * g_free (p->state); + * } + * + * void + * remove_person_from_database (Database *db, Person *p) + * { + * db->persons = g_list_remove (db->persons, p); + * g_rc_box_release_full (p, (GDestroyNotify) person_clear); + * } + * ]| + * + * If you wish to transfer the ownership of a reference counted data + * type without increasing the reference count, you can use g_steal_pointer(): + * + * |[<!-- language="C" --> + * Person *p = g_rc_box_new (Person); + * + * // fill_person_details() is defined elsewhere + * fill_person_details (p); + * + * // add_person_to_database_no_ref() is defined elsewhere; it adds + * // a Person to the Database without taking a reference + * add_person_to_database_no_ref (db, g_steal_pointer (&p)); + * ]| + * + * ## Thread safety + * + * The reference counting operations on data allocated using g_rc_box_alloc(), + * g_rc_box_new(), and g_rc_box_dup() are not thread safe; it is your code's + * responsibility to ensure that references are acquired are released on the + * same thread. + * + * If you need thread safe reference counting, see the [atomic reference counted + * data][arcbox] API. + * + * ## Automatic pointer clean up + * + * If you want to add g_autoptr() support to your plain old data type through + * reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and + * g_rc_box_release(): + * + * |[<!-- language="C" --> + * G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_rc_box_release) + * ]| + * + * If you need to clear the contents of the data, you will need to use an + * ancillary function that calls g_rc_box_release_full(): + * + * |[<!-- laguage="C" --> + * static void + * my_data_struct_release (MyDataStruct *data) + * { + * // my_data_struct_clear() is defined elsewhere + * g_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear); + * } + * + * G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_clear) + * ]| + * + * Since: 2.58. + */ + + +/** * SECTION:refcount * @Title: Reference counting * @Short_description: Reference counting types and functions @@ -7861,6 +8118,75 @@ /** + * SECTION:refstring + * @Title: Reference counted strings + * @Short_description: Strings with reference counted memory management + * + * Reference counted strings are normal C strings that have been augmented + * with a reference counter to manage their resources. You allocate a new + * reference counted string and acquire and release references as needed, + * instead of copying the string among callers; when the last reference on + * the string is released, the resources allocated for it are freed. + * + * Typically, reference counted strings can be used when parsing data from + * files and storing them into data structures that are passed to various + * callers: + * + * |[<!-- language="C" --> + * PersonDetails * + * person_details_from_data (const char *data) + * { + * // Use g_autoptr() to simplify error cases + * g_autoptr(GRefString) full_name = NULL; + * g_autoptr(GRefString) address = NULL; + * g_autoptr(GRefString) city = NULL; + * g_autoptr(GRefString) state = NULL; + * g_autoptr(GRefString) zip_code = NULL; + * + * // parse_person_details() is defined elsewhere; returns refcounted strings + * if (!parse_person_details (data, &full_name, &address, &city, &state, &zip_code)) + * return NULL; + * + * if (!validate_zip_code (zip_code)) + * return NULL; + * + * // add_address_to_cache() and add_full_name_to_cache() are defined + * // elsewhere; they add strings to various caches, using refcounted + * // strings to avoid copying data over and over again + * add_address_to_cache (address, city, state, zip_code); + * add_full_name_to_cache (full_name); + * + * // person_details_new() is defined elsewhere; it takes a reference + * // on each string + * PersonDetails *res = person_details_new (full_name, + * address, + * city, + * state, + * zip_code); + * + * return res; + * } + * ]| + * + * In the example above, we have multiple functions taking the same strings + * for different uses; with typical C strings, we'd have to copy the strings + * every time the life time rules of the data differ from the life time of + * the string parsed from the original buffer. With reference counted strings, + * each caller can take a reference on the data, and keep it as long as it + * needs to own the string. + * + * Reference counted strings can also be "interned" inside a global table + * owned by GLib; while an interned string has at least a reference, creating + * a new interned reference counted string with the same contents will return + * a reference to the existing string instead of creating a new reference + * counted string instance. Once the string loses its last reference, it will + * be automatically removed from the global interned strings table. + * + * Since: 2.58 + */ + + +/** * SECTION:scanner * @title: Lexical Scanner * @short_description: a general purpose lexical scanner @@ -10650,6 +10976,139 @@ /** + * g_atomic_rc_box_acquire: + * @mem_block: (not nullable): a pointer to reference counted data + * + * Atomically acquires a reference on the data pointed by @mem_block. + * + * Returns: (transfer full) (not nullable): a pointer to the data, + * with its reference count increased + * Since: 2.58 + */ + + +/** + * g_atomic_rc_box_alloc: + * @block_size: the size of the allocation, must be greater than 0 + * + * Allocates @block_size bytes of memory, and adds atomic + * reference counting semantics to it. + * + * The data will be freed when its reference count drops to + * zero. + * + * Returns: (transfer full) (not nullable): a pointer to the allocated memory + * Since: 2.58 + */ + + +/** + * g_atomic_rc_box_alloc0: + * @block_size: the size of the allocation, must be greater than 0 + * + * Allocates @block_size bytes of memory, and adds atomic + * referenc counting semantics to it. + * + * The contents of the returned data is set to zero. + * + * The data will be freed when its reference count drops to + * zero. + * + * Returns: (transfer full) (not nullable): a pointer to the allocated memory + * Since: 2.58 + */ + + +/** + * g_atomic_rc_box_dup: + * @block_size: the number of bytes to copy, must be greater than 0 + * @mem_block: (not nullable): the memory to copy + * + * Allocates a new block of data with atomit reference counting + * semantics, and copies @block_size bytes of @mem_block + * into it. + * + * Returns: (transfer full) (not nullable): a pointer to the allocated + * memory + * Since: 2.58 + */ + + +/** + * g_atomic_rc_box_get_size: + * @mem_block: (not nullable): a pointer to reference counted data + * + * Retrieves the size of the reference counted data pointed by @mem_block. + * + * Returns: the size of the data, in bytes + * Since: 2.58 + */ + + +/** + * g_atomic_rc_box_new: + * @type: the type to allocate, typically a structure name + * + * A convenience macro to allocate atomically reference counted + * data with the size of the given @type. + * + * This macro calls g_atomic_rc_box_alloc() with `sizeof (@type)` and + * casts the returned pointer to a pointer of the given @type, + * avoiding a type cast in the source code. + * + * Returns: (transfer full) (not nullable): a pointer to the allocated + * memory, cast to a pointer for the given @type + * Since: 2.58 + */ + + +/** + * g_atomic_rc_box_new0: + * @type: the type to allocate, typically a structure name + * + * A convenience macro to allocate atomically reference counted + * data with the size of the given @type, and set its contents + * to zero. + * + * This macro calls g_atomic_rc_box_alloc0() with `sizeof (@type)` and + * casts the returned pointer to a pointer of the given @type, + * avoiding a type cast in the source code. + * + * Returns: (transfer full) (not nullable): a pointer to the allocated + * memory, cast to a pointer for the given @type + * Since: 2.58 + */ + + +/** + * g_atomic_rc_box_release: + * @mem_block: (transfer full) (not nullable): a pointer to reference counted data + * + * Atomically releases a reference on the data pointed by @mem_block. + * + * If the reference was the last one, it will free the + * resources allocated for @mem_block. + * + * Since: 2.58 + */ + + +/** + * g_atomic_rc_box_release_full: + * @mem_block: (transfer full) (not nullable): a pointer to reference counted data + * @clear_func: (not nullable): a function to call when clearing the data + * + * Atomically releases a reference on the data pointed by @mem_block. + * + * If the reference was the last one, it will call @clear_func + * to clear the contents of @mem_block, and then will free the + * resources allocated for @mem_block. + * + * Since: 2.58 + */ + + +/** * g_atomic_ref_count_compare: * @arc: the address of an atomic reference count variable * @val: the value to compare @@ -14063,7 +14522,10 @@ * * To set the value of a date to the current day, you could write: * |[<!-- language="C" --> - * g_date_set_time_t (date, time (NULL)); + * time_t now = time (NULL); + * if (now == (time_t) -1) + * // handle the error + * g_date_set_time_t (date, now); * ]| * * Since: 2.10 @@ -25287,6 +25749,138 @@ /** + * g_rc_box_acquire: + * @mem_block: (not nullable): a pointer to reference counted data + * + * Acquires a reference on the data pointed by @mem_block. + * + * Returns: (transfer full) (not nullable): a pointer to the data, + * with its reference count increased + * Since: 2.58 + */ + + +/** + * g_rc_box_alloc: + * @block_size: the size of the allocation, must be greater than 0 + * + * Allocates @block_size bytes of memory, and adds reference + * counting semantics to it. + * + * The data will be freed when its reference count drops to + * zero. + * + * Returns: (transfer full) (not nullable): a pointer to the allocated memory + * Since: 2.58 + */ + + +/** + * g_rc_box_alloc0: + * @block_size: the size of the allocation, must be greater than 0 + * + * Allocates @block_size bytes of memory, and adds reference + * counting semantics to it. + * + * The contents of the returned data is set to zero. + * + * The data will be freed when its reference count drops to + * zero. + * + * Returns: (transfer full) (not nullable): a pointer to the allocated memory + * Since: 2.58 + */ + + +/** + * g_rc_box_dup: + * @block_size: the number of bytes to copy, must be greater than 0 + * @mem_block: (not nullable): the memory to copy + * + * Allocates a new block of data with reference counting + * semantics, and copies @block_size bytes of @mem_block + * into it. + * + * Returns: (transfer full) (not nullable): a pointer to the allocated + * memory + * Since: 2.58 + */ + + +/** + * g_rc_box_get_size: + * @mem_block: (not nullable): a pointer to reference counted data + * + * Retrieves the size of the reference counted data pointed by @mem_block. + * + * Returns: the size of the data, in bytes + * Since: 2.58 + */ + + +/** + * g_rc_box_new: + * @type: the type to allocate, typically a structure name + * + * A convenience macro to allocate reference counted data with + * the size of the given @type. + * + * This macro calls g_rc_box_alloc() with `sizeof (@type)` and + * casts the returned pointer to a pointer of the given @type, + * avoiding a type cast in the source code. + * + * Returns: (transfer full) (not nullable): a pointer to the + * allocated memory, cast to a pointer for the given @type + * Since: 2.58 + */ + + +/** + * g_rc_box_new0: + * @type: the type to allocate, typically a structure name + * + * A convenience macro to allocate reference counted data with + * the size of the given @type, and set its contents to zero. + * + * This macro calls g_rc_box_alloc0() with `sizeof (@type)` and + * casts the returned pointer to a pointer of the given @type, + * avoiding a type cast in the source code. + * + * Returns: (transfer full) (not nullable): a pointer to the + * allocated memory, cast to a pointer for the given @type + * Since: 2.58 + */ + + +/** + * g_rc_box_release: + * @mem_block: (transfer full) (not nullable): a pointer to reference counted data + * + * Releases a reference on the data pointed by @mem_block. + * + * If the reference was the last one, it will free the + * resources allocated for @mem_block. + * + * Since: 2.58 + */ + + +/** + * g_rc_box_release_full: + * @mem_block: (transfer full) (not nullable): a pointer to reference counted data + * @clear_func: (not nullable): a function to call when clearing the data + * + * Releases a reference on the data pointed by @mem_block. + * + * If the reference was the last one, it will call @clear_func + * to clear the contents of @mem_block, and then will free the + * resources allocated for @mem_block. + * + * Since: 2.58 + */ + + +/** * g_realloc: * @mem: (nullable): the memory to reallocate * @n_bytes: new size of the memory in bytes @@ -25455,6 +26049,84 @@ /** + * g_ref_string_acquire: + * @str: a reference counted string + * + * Acquires a reference on a string. + * + * Returns: the given string, with its reference count increased + * Since: 2.58 + */ + + +/** + * g_ref_string_length: + * @str: a reference counted string + * + * Retrieves the length of @str. + * + * Returns: the length of the given string, in bytes + * Since: 2.58 + */ + + +/** + * g_ref_string_new: + * @str: (not nullable): a NUL-terminated string + * + * Creates a new reference counted string and copies the contents of @str + * into it. + * + * Returns: (transfer full) (not nullable): the newly created reference counted string + * Since: 2.58 + */ + + +/** + * g_ref_string_new_intern: + * @str: (not nullable): a NUL-terminated string + * + * Creates a new reference counted string and copies the content of @str + * into it. + * + * If you call this function multiple times with the same @str, or with + * the same contents of @str, it will return a new reference, instead of + * creating a new string. + * + * Returns: (transfer full) (not nullable): the newly created reference + * counted string, or a new reference to an existing string + * Since: 2.58 + */ + + +/** + * g_ref_string_new_len: + * @str: (not nullable): a string + * @len: length of @str to use, or -1 if @str is nul-terminated + * + * Creates a new reference counted string and copies the contents of @str + * into it, up to @len bytes. + * + * Since this function does not stop at nul bytes, it is the caller's + * responsibility to ensure that @str has at least @len addressable bytes. + * + * Returns: (transfer full) (not nullable): the newly created reference counted string + * Since: 2.58 + */ + + +/** + * g_ref_string_release: + * @str: a reference counted string + * + * Releases a reference on a string; if it was the last reference, the + * resources allocated by the string are freed as well. + * + * Since: 2.58 + */ + + +/** * g_regex_check_replacement: * @replacement: the replacement string * @has_references: (out) (optional): location to store information about |