luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-06-29 07:34:57 +02:00
Code Issues Packages Projects Releases Wiki Activity

Improve docs for g_rc_box/g_atomic_rc_box

Browse Source 
Especially the preconditions and the annotations for the returned
values.
This commit is contained in:
Emmanuele Bassi 2018-07-03 15:43:45 +01:00
parent 3bc0499eb2
commit 68304ae583
2 changed files with 33 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
glib/garcbox.c
View File

@ -159,7 +159,7 @@
/** /**
* g_atomic_rc_box_alloc: * g_atomic_rc_box_alloc:
* @block_size: the size of the allocation * @block_size: the size of the allocation, must be greater than 0
* *
* Allocates @block_size bytes of memory, and adds atomic * Allocates @block_size bytes of memory, and adds atomic
* reference counting semantics to it. * reference counting semantics to it.
@ -167,7 +167,7 @@
* The data will be freed when its reference count drops to * The data will be freed when its reference count drops to
* zero. * zero.
* *
* Returns: a pointer to the allocated memory * Returns: (transfer full) (not nullable): a pointer to the allocated memory
* *
* Since: 2.58 * Since: 2.58
*/ */
@ -181,17 +181,17 @@ g_atomic_rc_box_alloc (gsize block_size)
/** /**
* g_atomic_rc_box_alloc0: * g_atomic_rc_box_alloc0:
* @block_size: the size of the allocation * @block_size: the size of the allocation, must be greater than 0
* *
* Allocates @block_size bytes of memory, and adds atomic * Allocates @block_size bytes of memory, and adds atomic
* referenc counting semantics to it. * referenc counting semantics to it.
* *
* The contents of the returned data is set to 0's. * The contents of the returned data is set to zero.
* *
* The data will be freed when its reference count drops to * The data will be freed when its reference count drops to
* zero. * zero.
* *
* Returns: a pointer to the allocated memory * Returns: (transfer full) (not nullable): a pointer to the allocated memory
* *
* Since: 2.58 * Since: 2.58
*/ */
@ -214,11 +214,8 @@ g_atomic_rc_box_alloc0 (gsize block_size)
* casts the returned pointer to a pointer of the given @type, * casts the returned pointer to a pointer of the given @type,
* avoiding a type cast in the source code. * avoiding a type cast in the source code.
* *
* This macro cannot return %NULL, as the minimum allocation * Returns: (transfer full) (not nullable): a pointer to the allocated
* size from `sizeof (@type)` is 1 byte. * memory, cast to a pointer for the given @type
*
* Returns: (not nullable): a pointer to the allocated memory,
* cast to a pointer for the given @type
* *
* Since: 2.58 * Since: 2.58
*/ */
@ -229,31 +226,29 @@ g_atomic_rc_box_alloc0 (gsize block_size)
* *
* A convenience macro to allocate atomically reference counted * A convenience macro to allocate atomically reference counted
* data with the size of the given @type, and set its contents * data with the size of the given @type, and set its contents
* to 0. * to zero.
* *
* This macro calls g_atomic_rc_box_alloc0() with `sizeof (@type)` and * This macro calls g_atomic_rc_box_alloc0() with `sizeof (@type)` and
* casts the returned pointer to a pointer of the given @type, * casts the returned pointer to a pointer of the given @type,
* avoiding a type cast in the source code. * avoiding a type cast in the source code.
* *
* This macro cannot return %NULL, as the minimum allocation * Returns: (transfer full) (not nullable): a pointer to the allocated
* size from `sizeof (@type)` is 1 byte. * memory, cast to a pointer for the given @type
*
* Returns: (not nullable): a pointer to the allocated memory,
* cast to a pointer for the given @type
* *
* Since: 2.58 * Since: 2.58
*/ */
/** /**
* g_atomic_rc_box_dup: * g_atomic_rc_box_dup:
* @block_size: the number of bytes to copy * @block_size: the number of bytes to copy, must be greater than 0
* @mem_block: (not nullable): the memory to copy * @mem_block: (not nullable): the memory to copy
* *
* Allocates a new block of data with atomit reference counting * Allocates a new block of data with atomit reference counting
* semantics, and copies @block_size bytes of @mem_block * semantics, and copies @block_size bytes of @mem_block
* into it. * into it.
* *
* Returns: (not nullable): a pointer to the allocated memory * Returns: (transfer full) (not nullable): a pointer to the allocated
* memory
* *
* Since: 2.58 * Since: 2.58
*/ */
@ -278,8 +273,8 @@ gpointer
* *
* Atomically acquires a reference on the data pointed by @mem_block. * Atomically acquires a reference on the data pointed by @mem_block.
* *
* Returns: (not nullabl): a pointer to the data, with its reference * Returns: (transfer none) (not nullable): a pointer to the data,
* count increased * with its reference count increased
* *
* Since: 2.58 * Since: 2.58
*/ */
@ -361,7 +356,7 @@ g_atomic_rc_box_release_full (gpointer mem_block,
* *
* Retrieves the size of the reference counted data pointed by @mem_block. * Retrieves the size of the reference counted data pointed by @mem_block.
* *
* Returns: the size of the data * Returns: the size of the data, in bytes
* *
* Since: 2.58 * Since: 2.58
*/ */

39
glib/grcbox.c
View File

@ -230,7 +230,7 @@ g_rc_box_alloc_full (gsize block_size,
/** /**
* g_rc_box_alloc: * g_rc_box_alloc:
* @block_size: the size of the allocation * @block_size: the size of the allocation, must be greater than 0
* *
* Allocates @block_size bytes of memory, and adds reference * Allocates @block_size bytes of memory, and adds reference
* counting semantics to it. * counting semantics to it.
@ -238,7 +238,7 @@ g_rc_box_alloc_full (gsize block_size,
* The data will be freed when its reference count drops to * The data will be freed when its reference count drops to
* zero. * zero.
* *
* Returns: a pointer to the allocated memory * Returns: (transfer full) (not nullable): a pointer to the allocated memory
* *
* Since: 2.58 * Since: 2.58
*/ */
@ -252,17 +252,17 @@ g_rc_box_alloc (gsize block_size)
/** /**
* g_rc_box_alloc0: * g_rc_box_alloc0:
* @block_size: the size of the allocation * @block_size: the size of the allocation, must be greater than 0
* *
* Allocates @block_size bytes of memory, and adds reference * Allocates @block_size bytes of memory, and adds reference
* counting semantics to it. * counting semantics to it.
* *
* The contents of the returned data is set to 0's. * The contents of the returned data is set to zero.
* *
* The data will be freed when its reference count drops to * The data will be freed when its reference count drops to
* zero. * zero.
* *
* Returns: a pointer to the allocated memory * Returns: (transfer full) (not nullable): a pointer to the allocated memory
* *
* Since: 2.58 * Since: 2.58
*/ */
@ -285,11 +285,8 @@ g_rc_box_alloc0 (gsize block_size)
* casts the returned pointer to a pointer of the given @type, * casts the returned pointer to a pointer of the given @type,
* avoiding a type cast in the source code. * avoiding a type cast in the source code.
* *
* This macro cannot return %NULL, as the minimum allocation * Returns: (transfer full) (not nullable): a pointer to the
* size from `sizeof (@type)` is 1 byte. * allocated memory, cast to a pointer for the given @type
*
* Returns: (not nullable): a pointer to the allocated memory,
* cast to a pointer for the given @type
* *
* Since: 2.58 * Since: 2.58
*/ */
@ -299,31 +296,29 @@ g_rc_box_alloc0 (gsize block_size)
* @type: the type to allocate, typically a structure name * @type: the type to allocate, typically a structure name
* *
* A convenience macro to allocate reference counted data with * A convenience macro to allocate reference counted data with
* the size of the given @type, and set its contents to 0. * the size of the given @type, and set its contents to zero.
* *
* This macro calls g_rc_box_alloc0() with `sizeof (@type)` and * This macro calls g_rc_box_alloc0() with `sizeof (@type)` and
* casts the returned pointer to a pointer of the given @type, * casts the returned pointer to a pointer of the given @type,
* avoiding a type cast in the source code. * avoiding a type cast in the source code.
* *
* This macro cannot return %NULL, as the minimum allocation * Returns: (transfer full) (not nullable): a pointer to the
* size from `sizeof (@type)` is 1 byte. * allocated memory, cast to a pointer for the given @type
*
* Returns: (not nullable): a pointer to the allocated memory,
* cast to a pointer for the given @type
* *
* Since: 2.58 * Since: 2.58
*/ */
/** /**
* g_rc_box_dup: * g_rc_box_dup:
* @block_size: the number of bytes to copy * @block_size: the number of bytes to copy, must be greater than 0
* @mem_block: (not nullable): the memory to copy * @mem_block: (not nullable): the memory to copy
* *
* Allocates a new block of data with reference counting * Allocates a new block of data with reference counting
* semantics, and copies @block_size bytes of @mem_block * semantics, and copies @block_size bytes of @mem_block
* into it. * into it.
* *
* Returns: (not nullable): a pointer to the allocated memory * Returns: (transfer full) (not nullable): a pointer to the allocated
* memory
* *
* Since: 2.58 * Since: 2.58
*/ */
@ -348,8 +343,8 @@ gpointer
* *
* Acquires a reference on the data pointed by @mem_block. * Acquires a reference on the data pointed by @mem_block.
* *
* Returns: (not nullabl): a pointer to the data, with its reference * Returns: (transfer none) (not nullable): a pointer to the data,
* count increased * with its reference count increased
* *
* Since: 2.58 * Since: 2.58
*/ */
@ -395,7 +390,7 @@ g_rc_box_release (gpointer mem_block)
/** /**
* g_rc_box_release_full: * g_rc_box_release_full:
* @mem_block: (not nullabl): a pointer to reference counted data * @mem_block: (not nullable): a pointer to reference counted data
* @clear_func: (not nullable): a function to call when clearing the data * @clear_func: (not nullable): a function to call when clearing the data
* *
* Releases a reference on the data pointed by @mem_block. * Releases a reference on the data pointed by @mem_block.
@ -431,7 +426,7 @@ g_rc_box_release_full (gpointer mem_block,
* *
* Retrieves the size of the reference counted data pointed by @mem_block. * Retrieves the size of the reference counted data pointed by @mem_block.
* *
* Returns: the size of the data * Returns: the size of the data, in bytes
* *
* Since: 2.58 * Since: 2.58
*/ */