pub unsafe extern "C" fn GC_general_register_disappearing_link(
arg1: *mut *mut c_void,
arg2: *const c_void,
) -> c_intExpand description
A slight generalization of GC_register_disappearing_link.
*link is cleared when obj first becomes inaccessible. This can be
used to implement weak pointers easily and safely. Typically link
will point to a location (in a GC-allocated object or not) holding
a disguised pointer to obj. (A pointer inside an “atomic” object
is effectively disguised.) In this way, weak pointers are broken
before any object reachable from them gets finalized. Each link
may be registered only with one obj value, i.e. all objects but
the last one (link registered with) are ignored. link must be
non-NULL (and be properly aligned). obj must be a pointer to
the beginning of an object allocated by GC_malloc or friends.
A link disappears when it is unregistered manually, or when *link
is cleared, or when the object containing this link is garbage
collected. It is unsafe to explicitly deallocate the object
containing link. Explicit deallocation of obj may or may not
cause link to eventually be cleared. No-op in the find-leak mode.
This function can be used to implement certain types of weak pointers.
Note, however, this generally requires that the allocator lock is held,
at least in the reader mode (e.g. using GC_call_with_reader_lock()),
when the disguised pointer is accessed. Otherwise a strong pointer
could be recreated between the time the collector decides to reclaim
the object and the link is cleared. Returns GC_SUCCESS if
registration succeeded (a new link is registered), GC_DUPLICATE if
link was already registered (with some object), GC_NO_MEMORY if
registration failed for lack of memory (and GC_oom_fn did not handle
the problem), GC_UNIMPLEMENTED if GC_find_leak is true.