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.
