We need stronger alignment guarantees for the memory allocations done
through g_rc_box_alloc_full(): while the passed block size may be
aligned, we're not aligning the private data size; this means the
overall allocation may become unaligned, and this could raise issues
when we use the private data size as an offset to access the reference
count.
Fixes: #1581
The accepted behaviour for reference counting functions can be described
as such:
- acquire: takes a pointer to a memory area and returns the same
pointer with its reference count increased; this means that the
returned value's ownership is fully transfered from the callee
to the caller
- release: takes a pointer to a memory area and drops the reference
count; this means that the caller transfers the ownership of the
argument to the callee
These annotations are mostly meant for documentation purposes: high
level language bindings are unlikely to use them, as they have their own
reference counting semantics on top of GLib's own, and they should not
expose this API to their own consumers.
Both g_rc_box_release_full() and g_atomic_rc_box_release_full() should
allow passing NULL as the clear function, to conform to the existing
coding practices in GLib.
Additionally, this allows us to reimplement release() in terms of
release_full(), and improve test coverage.
It's more useful to have a dup() function that copies any blob of memory
into a reference counted allocation, than to have a dup() that only
copies a reference counted allocation.
GArcBox is the atomic reference counting version of GRcBox. Unlike
GRcBox, the reference acquisition and release on GArcBox are guaranteed
to be atomic, and thus they can be performed from different threads.
This is similar to Rust's Arc<Box<T>> combination of traits.
It is useful to provide a "reference counted allocation" API that can
add reference counting semantics to any memory allocation. This allows
turning data structures that usually are placed on the stack into memory
that can be placed on the heap without:
- adding a public reference count field
- implementing copy/free semantics
This mechanism is similar to Rust's Rc<Box<T>> combination of traits,
and uses a Valgrind-friendly overallocation mechanism to store the
reference count into a private data segment, like we do with GObject's
private instance data.