mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-25 15:06:14 +01:00
Improve docs for g_rc_box/g_atomic_rc_box
Especially the preconditions and the annotations for the returned values.
This commit is contained in:
Emmanuele Bassi
parent
3bc0499eb2
commit
68304ae583
@ -159,7 +159,7 @@
|
||||
|
||||
/**
|
||||
* 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
|
||||
* reference counting semantics to it.
|
||||
@ -167,7 +167,7 @@
|
||||
* The data will be freed when its reference count drops to
|
||||
* zero.
|
||||
*
|
||||
* Returns: a pointer to the allocated memory
|
||||
* Returns: (transfer full) (not nullable): a pointer to the allocated memory
|
||||
*
|
||||
* Since: 2.58
|
||||
*/
|
||||
@ -181,17 +181,17 @@ g_atomic_rc_box_alloc (gsize block_size)
|
||||
|
||||
/**
|
||||
* 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
|
||||
* 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
|
||||
* zero.
|
||||
*
|
||||
* Returns: a pointer to the allocated memory
|
||||
* Returns: (transfer full) (not nullable): a pointer to the allocated memory
|
||||
*
|
||||
* 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,
|
||||
* avoiding a type cast in the source code.
|
||||
*
|
||||
* This macro cannot return %NULL, as the minimum allocation
|
||||
* size from `sizeof (@type)` is 1 byte.
|
||||
*
|
||||
* Returns: (not nullable): a pointer to the allocated memory,
|
||||
* cast to a pointer for the given @type
|
||||
* Returns: (transfer full) (not nullable): a pointer to the allocated
|
||||
* memory, cast to a pointer for the given @type
|
||||
*
|
||||
* Since: 2.58
|
||||
*/
|
||||
@ -229,31 +226,29 @@ g_atomic_rc_box_alloc0 (gsize block_size)
|
||||
*
|
||||
* A convenience macro to allocate atomically reference counted
|
||||
* 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
|
||||
* casts the returned pointer to a pointer of the given @type,
|
||||
* avoiding a type cast in the source code.
|
||||
*
|
||||
* This macro cannot return %NULL, as the minimum allocation
|
||||
* size from `sizeof (@type)` is 1 byte.
|
||||
*
|
||||
* Returns: (not nullable): a pointer to the allocated memory,
|
||||
* cast to a pointer for the given @type
|
||||
* 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_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
|
||||
*
|
||||
* Allocates a new block of data with atomit reference counting
|
||||
* semantics, and copies @block_size bytes of @mem_block
|
||||
* 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
|
||||
*/
|
||||
@ -278,8 +273,8 @@ gpointer
|
||||
*
|
||||
* Atomically acquires a reference on the data pointed by @mem_block.
|
||||
*
|
||||
* Returns: (not nullabl): a pointer to the data, with its reference
|
||||
* count increased
|
||||
* Returns: (transfer none) (not nullable): a pointer to the data,
|
||||
* with its reference count increased
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* Returns: the size of the data
|
||||
* Returns: the size of the data, in bytes
|
||||
*
|
||||
* Since: 2.58
|
||||
*/
|
||||
|
||||
@ -230,7 +230,7 @@ g_rc_box_alloc_full (gsize block_size,
|
||||
|
||||
/**
|
||||
* 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
|
||||
* 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
|
||||
* zero.
|
||||
*
|
||||
* Returns: a pointer to the allocated memory
|
||||
* Returns: (transfer full) (not nullable): a pointer to the allocated memory
|
||||
*
|
||||
* Since: 2.58
|
||||
*/
|
||||
@ -252,17 +252,17 @@ g_rc_box_alloc (gsize block_size)
|
||||
|
||||
/**
|
||||
* 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
|
||||
* 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
|
||||
* zero.
|
||||
*
|
||||
* Returns: a pointer to the allocated memory
|
||||
* Returns: (transfer full) (not nullable): a pointer to the allocated memory
|
||||
*
|
||||
* 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,
|
||||
* avoiding a type cast in the source code.
|
||||
*
|
||||
* This macro cannot return %NULL, as the minimum allocation
|
||||
* size from `sizeof (@type)` is 1 byte.
|
||||
*
|
||||
* Returns: (not nullable): a pointer to the allocated memory,
|
||||
* cast to a pointer for the given @type
|
||||
* Returns: (transfer full) (not nullable): a pointer to the
|
||||
* allocated memory, cast to a pointer for the given @type
|
||||
*
|
||||
* Since: 2.58
|
||||
*/
|
||||
@ -299,31 +296,29 @@ g_rc_box_alloc0 (gsize block_size)
|
||||
* @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 0.
|
||||
* 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.
|
||||
*
|
||||
* This macro cannot return %NULL, as the minimum allocation
|
||||
* size from `sizeof (@type)` is 1 byte.
|
||||
*
|
||||
* Returns: (not nullable): a pointer to the allocated memory,
|
||||
* cast to a pointer for the given @type
|
||||
* 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_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
|
||||
*
|
||||
* Allocates a new block of data with reference counting
|
||||
* semantics, and copies @block_size bytes of @mem_block
|
||||
* 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
|
||||
*/
|
||||
@ -348,8 +343,8 @@ gpointer
|
||||
*
|
||||
* Acquires a reference on the data pointed by @mem_block.
|
||||
*
|
||||
* Returns: (not nullabl): a pointer to the data, with its reference
|
||||
* count increased
|
||||
* Returns: (transfer none) (not nullable): a pointer to the data,
|
||||
* with its reference count increased
|
||||
*
|
||||
* Since: 2.58
|
||||
*/
|
||||
@ -395,7 +390,7 @@ g_rc_box_release (gpointer mem_block)
|
||||
|
||||
/**
|
||||
* 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
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* Returns: the size of the data
|
||||
* Returns: the size of the data, in bytes
|
||||
*
|
||||
* Since: 2.58
|
||||
*/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user