Skip to main content

GC_general_register_disappearing_link

Function GC_general_register_disappearing_link 

Source
pub unsafe extern "C" fn GC_general_register_disappearing_link(
    arg1: *mut *mut c_void,
    arg2: *const c_void,
) -> c_int
Expand 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.