Description
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:
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():
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:
If you wish to transfer the ownership of a reference counted data
type without increasing the reference count, you can use g_steal_pointer():
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.
Functions
g_atomic_rc_box_alloc ()
gpointer
g_atomic_rc_box_alloc (gsize block_size);
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.
The allocated data is guaranteed to be suitably aligned for any
built-in type.
Returns
a pointer to the allocated memory.
[transfer full][not nullable]
Since: 2.58
g_atomic_rc_box_alloc0 ()
gpointer
g_atomic_rc_box_alloc0 (gsize block_size);
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.
The allocated data is guaranteed to be suitably aligned for any
built-in type.
Returns
a pointer to the allocated memory.
[transfer full][not nullable]
Since: 2.58
g_atomic_rc_box_new()
#define g_atomic_rc_box_new(type)
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
a pointer to the allocated
memory, cast to a pointer for the given type
.
[transfer full][not nullable]
Since: 2.58
g_atomic_rc_box_new0()
#define g_atomic_rc_box_new0(type)
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
a pointer to the allocated
memory, cast to a pointer for the given type
.
[transfer full][not nullable]
Since: 2.58
g_atomic_rc_box_dup ()
gpointer
g_atomic_rc_box_dup (gsize block_size,
gconstpointer mem_block);
Allocates a new block of data with atomic reference counting
semantics, and copies block_size
bytes of mem_block
into it.
Returns
a pointer to the allocated
memory.
[transfer full][not nullable]
Since: 2.58
g_atomic_rc_box_acquire ()
gpointer
g_atomic_rc_box_acquire (gpointer mem_block);
Atomically acquires a reference on the data pointed by mem_block
.
Returns
a pointer to the data,
with its reference count increased.
[transfer full][not nullable]
Since: 2.58
g_atomic_rc_box_release ()
void
g_atomic_rc_box_release (gpointer mem_block);
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 ()
void
g_atomic_rc_box_release_full (gpointer mem_block,
GDestroyNotify clear_func);
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_rc_box_get_size ()
gsize
g_atomic_rc_box_get_size (gpointer mem_block);
Retrieves the size of the reference counted data pointed by mem_block
.
Returns
the size of the data, in bytes
Since: 2.58