Crate bdwgc_alloc_sys 

bdwgc-alloc-sys

Rust bindings to the C API of bdwgc, the conservative garbage collector.

This crate builds bdwgc from its vendored source and links it statically. The bindings are generated from its headers at build time by bindgen, which requires libclang.

See the bdwgc-alloc crate for a GlobalAlloc implementation on top of these bindings.

Install

cargo add bdwgc-alloc-sys

By default bdwgc is built with autotools. To build with cmake, enable the cmake feature:

cargo add bdwgc-alloc-sys --no-default-features --features cmake

License

MIT

Structs

GC_prof_stats_s

Structure used to query the GC statistics (profiling information). More fields could be added in the future. To preserve compatibility new fields should be added only to the end, and no deprecated fields should be removed from.

GC_stack_base

Structure representing the bottom (cold end) of a thread stack. On most platforms this contains just a single address.

GC_timeval_s

A portable type definition of time with a nanosecond precision.

__sigset_t

Constants

GC_DUPLICATE

GC_EventType_GC_EVENT_END

GC_EventType_GC_EVENT_MARK_END

GC_EventType_GC_EVENT_MARK_START

GC_EventType_GC_EVENT_POST_START_WORLD

GC_EventType_GC_EVENT_POST_STOP_WORLD

GC_EventType_GC_EVENT_PRE_START_WORLD

GC_EventType_GC_EVENT_PRE_STOP_WORLD

GC_EventType_GC_EVENT_RECLAIM_END

GC_EventType_GC_EVENT_RECLAIM_START

GC_EventType_GC_EVENT_START

GC_EventType_GC_EVENT_THREAD_SUSPENDED

GC_EventType_GC_EVENT_THREAD_UNSUSPENDED

GC_NOT_FOUND

GC_NO_MEMORY

GC_NO_THREADS

GC_PROTECTS_NONE

GC_PROTECTS_POINTER_HEAP

GC_PROTECTS_PTRFREE_HEAP

GC_PROTECTS_STACK

GC_PROTECTS_STATIC_DATA

GC_SUCCESS

GC_TIME_UNLIMITED

GC_TMP_VERSION_MAJOR

GC_TMP_VERSION_MICRO

GC_TMP_VERSION_MINOR

GC_ToggleRefStatus_GC_TOGGLE_REF_DROP

GC_ToggleRefStatus_GC_TOGGLE_REF_STRONG

GC_ToggleRefStatus_GC_TOGGLE_REF_WEAK

GC_UNIMPLEMENTED

GC_VDB_DEFAULT

GC_VDB_GWW

GC_VDB_MANUAL

GC_VDB_MPROTECT

GC_VDB_NONE

GC_VDB_PROC

GC_VDB_SOFT

GC_VDB_UFFDWP

GC_VERSION_MAJOR

GC_VERSION_MICRO

GC_VERSION_MINOR

GC_heap_section_type_GC_HEAP_SECTION_TYPE_FORWARDING

GC_heap_section_type_GC_HEAP_SECTION_TYPE_FREE

GC_heap_section_type_GC_HEAP_SECTION_TYPE_PADDING

GC_heap_section_type_GC_HEAP_SECTION_TYPE_UNMAPPED

GC_heap_section_type_GC_HEAP_SECTION_TYPE_USED

GC_heap_section_type_GC_HEAP_SECTION_TYPE_WHOLE_SECT

Statics

GC_all_interior_pointers^⚠

GC_dont_expand^⚠

Do not expand the heap unless explicitly requested or forced to. The setter and the getter are unsynchronized.

GC_dont_gc^⚠

GC_dont_precollect^⚠

Do not collect as part of the collector initialization. Should be set only if the client wants a chance to manually initialize the root set before the first collection. Interferes with black-listing. Wizards only. The setter and the getter are unsynchronized (and no external locking is needed since the value is accessed at the collector initialization only).

GC_finalize_on_demand^⚠

If nonzero, finalizers will only be run in response to an explicit GC_invoke_finalizers() call. The default is determined by whether the FINALIZE_ON_DEMAND macro is defined when the collector is built. The setter and the getter are unsynchronized.

GC_finalizer_notifier^⚠

GC_find_leak^⚠

Turn on the find-leak mode (do not actually garbage collect, but simply report inaccessible memory that was not deallocated with GC_FREE() or friends). Initial value is determined by FIND_LEAK macro. The value should not typically be modified after the collector initialization (and, thus, it does not use or need synchronization). The mode is supported only if the library has been compiled without NO_FIND_LEAK macro defined.

GC_free_space_divisor^⚠

We try to make sure that we allocate at least N / GC_free_space_divisor bytes between collections, where N is twice the number of traced bytes, plus the number of untraced bytes (i.e. bytes in the “atomic” objects), plus a rough estimate of the root set size. N approximates GC tracing work per collection. The initial value is given by GC_FREE_SPACE_DIVISOR macro. Increasing its value will use less space but more collection time. Decreasing it will appreciably decrease total collection time at the expense of space. The setter and the getter are unsynchronized, so GC_call_with_alloc_lock() (GC_call_with_reader_lock() in case of the getter) is required to avoid data race (if the value is modified after the collector is put into the multi-threaded mode). In GC v7.1 and before, the setter returned the old value.

GC_full_freq^⚠

Number of partial collections between full collections. Matters only if GC_is_incremental_mode(). Full collections are also triggered if the collector detects a substantial increase in the number of the in-use heap blocks. Values in the tens are now perfectly reasonable. The setter and the getter are unsynchronized, so GC_call_with_alloc_lock() (GC_call_with_reader_lock() in case of the getter) is required to avoid data race (if the value is modified after the collector is put into the multi-threaded mode).

GC_gc_no^⚠

Counter incremented once per collection. Includes empty collections at startup. GC_get_gc_no() is unsynchronized, so it requires GC_call_with_reader_lock() to avoid data race on multiprocessors.

GC_is_valid_displacement_print_proc^⚠

GC_is_visible_print_proc^⚠

GC_java_finalization^⚠

Mark objects reachable from finalizable objects in a separate post-pass. This makes it a bit safer to use non-topologically-ordered finalization. Default value is determined by JAVA_FINALIZATION macro. Enables GC_register_finalizer_unreachable() to work correctly. The setter and the getter are unsynchronized.

GC_max_retries^⚠

The maximum number of collections attempted before reporting out of memory after heap expansion fails. Initially 0. The setter and getter are unsynchronized, so GC_call_with_alloc_lock() (GC_call_with_reader_lock() in case of the getter) is required to avoid data race (if the value is modified after the collector is put into the multi-threaded mode).

GC_no_dls^⚠

Do not register dynamic library data segments automatically. Also, if set by the collector itself (during a collection), this means that such a registration is not supported. Wizards only. Should be set only if the client explicitly registers all roots. (In some environments like Microsoft Windows and Apple’s Darwin, this may also prevent registration of the main data segment as a part of the root set.) The setter and the getter are unsynchronized.

GC_non_gc_bytes^⚠

Bytes not considered candidates for collection. Used only to control scheduling of collections. Updated by GC_malloc_uncollectable(), GC_free() and friends. Wizards only. The setter and the getter are unsynchronized, so GC_call_with_alloc_lock() (GC_call_with_reader_lock() in case of the getter) is required to avoid data race (if the value is modified after the collector is put into the multi-threaded mode).

GC_on_heap_resize^⚠

GC_oom_fn^⚠

GC_parallel^⚠

GC is parallelized for performance on multiprocessors. Set to a nonzero value when client calls GC_start_mark_threads() directly or starts the first non-main thread, provided the collector is built with PARALLEL_MARK macro defined, and either GC_MARKERS (or GC_NPROCS) environment variable is set to a value bigger than 1, or multiple cores (processors) are available, or the client calls GC_set_markers_count() before the collector initialization. After setting, GC_parallel value is equal to the number of marker threads minus one (i.e. the number of existing parallel marker threads excluding the initiating one).

GC_same_obj_print_proc^⚠

GC_stackbottom^⚠

The cold end (bottom) of user stack. May be set in the client prior to calling any GC_ routines. This avoids some overhead, and potentially some signals that can confuse debuggers. Otherwise the collector attempts to set it automatically. For multi-threaded code, this is the cold end of the stack for the primordial thread. For multi-threaded code, altering GC_stackbottom value directly after the collector initialization has no effect. Portable clients should use GC_set_stackbottom(), GC_get_stack_base(), GC_call_with_gc_active() and GC_register_my_thread() instead.

GC_time_limit^⚠

If incremental collection is enabled, we try to terminate collections after this many milliseconds (plus the amount of nanoseconds as given in the latest GC_set_time_limit_tv() call, if any). Not a hard time bound. Setting this variable to GC_TIME_UNLIMITED essentially disables incremental collection (i.e. disables the “pause time exceeded” tests) while leaving generational collection enabled. The setter and the getter are unsynchronized, so GC_call_with_alloc_lock() (GC_call_with_reader_lock() in case of the getter) is required to avoid data race (if the value is modified after the collector is put into the multi-threaded mode). The setter does not update the value of the nanosecond part of the time limit (it is zero unless ever set by GC_set_time_limit_tv() call).

GC_use_entire_heap^⚠

Causes the non-incremental collector to use the entire heap before collecting. This sometimes results in more large-block fragmentation, since very large blocks will tend to get broken up during each collection cycle. It is likely to result in a larger working set, but lower collection frequencies, and hence fewer instructions executed in the collector.

Functions

GC_abort_on_oom^⚠

A portable way to abort the application because of not enough memory.

GC_add_roots^⚠

Add a root segment. Wizards only. May merge adjacent or overlapping segments if appropriate. Both segment start (low_address) and end (high_address_plus_1) are not needed to be pointer-aligned. low_address must not be greater than high_address_plus_1.

GC_alloc_lock^⚠

GC_alloc_unlock^⚠

GC_allow_register_threads^⚠

Explicitly enable GC_register_my_thread() invocation. Done implicitly if a GC thread-creation function is called (or implicit thread registration is activated, or the collector is compiled with GC_ALWAYS_MULTITHREADED macro defined). Otherwise, it must be called from the main (or any previously registered) thread between the collector initialization and the first explicit registering of a thread (it should be called as late as possible). Includes a GC_start_mark_threads() call.

GC_atfork_child^⚠

GC_atfork_parent^⚠

GC_atfork_prepare^⚠

Routines to handle POSIX fork() manually (no-op if handled automatically). GC_atfork_prepare() should be called immediately before fork(); GC_atfork_parent() should be invoked just after fork in the branch that corresponds to parent process (i.e., fork result is nonzero); GC_atfork_child() is to be called immediately in the child branch (i.e., fork result is 0). Note that GC_atfork_child() call should, of course, precede GC_start_mark_threads() call, if any. Note that fork() could be called from an unregistered thread.

GC_base^⚠

Return a pointer to the base (lowest address) of an object given a pointer to a location within the object. I.e., map an interior pointer to the corresponding base pointer. Note that with debugging allocation, this returns a pointer to the actual base of the object, i.e. the debug information, not to the base of the user object. Return NULL if displaced_pointer does not point to within a valid object. Note that a deallocated object in the garbage collected heap may be considered valid, even if it has been deallocated with GC_free() or friends.

GC_call_with_alloc_lock^⚠

Execute given function with the allocator lock held (in the exclusive mode).

GC_call_with_gc_active^⚠

Call a function switching to the “active” state of the collector for the current thread (i.e. the user function is temporarily back allowed to call any GC function and/or manipulate pointers to the garbage-collected heap). GC_call_with_gc_active() has the functionality opposite to GC_do_blocking() one. It is assumed that the collector is already initialized and the current thread is registered. fn may toggle the collector thread’s state temporarily to “inactive” one by using GC_do_blocking(). GC_call_with_gc_active() often can be used to provide a sufficiently accurate stack bottom. Acquires the allocator lock in the reader mode (but fn is called not holding it).

GC_call_with_reader_lock^⚠

GC_call_with_stack_base^⚠

Call a function with a stack base structure corresponding to somewhere in the GC_call_with_stack_base frame. This often can be used to provide a sufficiently accurate stack bottom. And we implement it everywhere.

GC_change_stubborn^⚠

GC_clear_exclusion_table^⚠

Clear the number of entries in the exclusion table. Wizards only. Should be called typically with the allocator lock held, but no assertion about it by design.

GC_clear_roots^⚠

Clear the set of root segments. Wizards only.

GC_collect_a_little^⚠

Perform some garbage collection work, if appropriate. Return 0 if there is no more work to be done (including the case when garbage collection is not appropriate). Typically performs an amount of work corresponding roughly to marking from one page. May do more work if further progress requires it, e.g. if incremental collection is disabled. It is reasonable to call this in a wait loop until it returns 0. If the garbage collection is disabled but the incremental collection is already ongoing, then perform marking anyway but not stopping the world (and without the reclaim phase).

GC_debug_change_stubborn^⚠

GC_debug_end_stubborn_change^⚠

GC_debug_free^⚠

GC_debug_freezero^⚠

GC_debug_malloc^⚠

Debugging (annotated) allocation. GC_gcollect() will check objects allocated in this way for overwrites, etc.

GC_debug_malloc_atomic^⚠

GC_debug_malloc_atomic_ignore_off_page^⚠

GC_debug_malloc_atomic_uncollectable^⚠

GC_debug_malloc_ignore_off_page^⚠

GC_debug_malloc_replacement^⚠

The functions that allocate objects with debug information (like the above), but just fill in dummy file and line number information. Thus they can serve as drop-in malloc/realloc/reallocf replacements. This can be useful for two reasons:

GC_debug_malloc_stubborn^⚠

GC_debug_malloc_uncollectable^⚠

GC_debug_malloc_uncollectable_replacement^⚠

GC_debug_ptr_store_and_dirty^⚠

GC_debug_realloc^⚠

GC_debug_realloc_replacement^⚠

GC_debug_reallocf^⚠

GC_debug_reallocf_replacement^⚠

GC_debug_register_displacement^⚠

GC_debug_register_finalizer^⚠

GC_debug_register_finalizer_ignore_self^⚠

GC_debug_register_finalizer_no_order^⚠

GC_debug_register_finalizer_unreachable^⚠

GC_debug_strdup^⚠

GC_debug_strndup^⚠

GC_debug_toggleref_add^⚠

GC_deinit^⚠

Perform the collector shutdown. (E.g. dispose critical sections on Windows target.) A duplicate invocation is a no-op. In case of Windows, typically, the client should also call GC_win32_free_heap() before this function call. TODO: The collector reinitialization after shutdown might work in certain configurations, but not tested.

GC_disable^⚠

Disable garbage collection. Even GC_gcollect() calls will be ineffective.

GC_dlopen^⚠

GC_do_blocking^⚠

Wrapper for functions that are likely to block (or, at least, do not allocate garbage-collected memory and/or manipulate pointers to the garbage-collected heap) for an appreciable length of time. While fn is running, the collector is said to be in the “inactive” state for the current thread (this means that the thread is not suspended and the thread’s stack frames “belonging” to the functions in the “inactive” state are not scanned during garbage collections). It is assumed that the collector is already initialized and the current thread is registered. It is allowed for fn to call GC_call_with_gc_active() (even recursively), thus temporarily toggling the collector’s state back to “active”. The latter technique might be used to make stack scanning more precise (i.e. scan only stack frames of functions that allocate garbage-collected memory and/or manipulate pointers to the garbage-collected heap). Acquires the allocator lock in the reader mode (but fn is called not holding it).

GC_dump^⚠

Explicitly dump the collector state. This is most often called from the debugger, or by setting the GC_DUMP_REGULARLY environment variable, but it may be useful to call it from client code during debugging. The current collection number is printed in the header of the dump. Acquires the allocator lock in the reader mode to avoid data race. Defined only if the library has been compiled without NO_DEBUGGING macro defined.

GC_dump_finalization^⚠

Dump information about every registered disappearing link and finalizable object. Defined only if the library has been compiled without NO_DEBUGGING macro defined.

GC_dump_named^⚠

The same as GC_dump but allows to specify the name of dump and does not acquire the allocator lock. If name is non-NULL, it is printed to help identifying individual dumps. Otherwise the current collection number is used as the name. Defined only if the library has been compiled without NO_DEBUGGING macro defined.

GC_dump_regions^⚠

Dump information about each block of every GC memory section. Defined only if the library has been compiled without NO_DEBUGGING macro defined.

GC_enable^⚠

Try to re-enable garbage collection. GC_disable() and GC_enable() calls could be nested. Garbage collection is enabled if the number of calls to both functions is equal.

GC_enable_incremental^⚠

Enable incremental/generational collection. Not advisable unless dirty bits are available or most heap objects are pointer-free (atomic) or immutable. Do not use in the find-leak mode. Ignored if GC_dont_gc is nonzero. Only the generational piece of this is functional if GC_time_limit is set to GC_TIME_UNLIMITED. Causes thread-local variant of GC_gcj_malloc() to revert to locked allocation. Must be called before any such GC_gcj_malloc() calls. For best performance, should be called as early as possible. On some platforms, calling it later may have adverse effects. Safe to call before the collector initialization; it performs the latter if not done yet.

GC_end_stubborn_change^⚠

Inform the collector that the object has been changed. Only non-NULL pointer stores into the object are considered to be changes. Matters only if the incremental collection is enabled in the manual VDB (virtual dirty bits) mode; otherwise the function does nothing. Should be followed typically by GC_reachable_here() called for each of the stored pointers.

GC_exclude_static_roots^⚠

Inform the collector that a certain section of statically allocated memory contains no pointers to garbage-collected memory. Thus it does not need to be scanned. This is sometimes important if the application maps large read/write files into the address space, which could be mistaken for dynamic library data segments on some systems. Both section start (low_address) and end (high_address_plus_1) are not needed to be pointer-aligned.

GC_expand_hp^⚠

Increase the heap size explicitly. The performed increase is at least number_of_bytes. Does the collector initialization as well (if not yet). Returns 0 on failure, 1 on success.

GC_finish_and_disable^⚠

Similar to GC_disable() but finishes any ongoing collection first.

GC_foreach_heap_section_inner^⚠

Apply fn to each heap section and each heap block inside. Similar to GC_apply_to_all_blocks(). Assumes the allocator lock is held at least in the reader mode, but no assertion about it by design. Defined only if the library has been compiled without NO_DEBUGGING macro defined.

GC_free^⚠

Explicitly deallocate an object. Dangerous if used incorrectly. Requires a pointer to the base of an object. An object should not be enabled for finalization (and it should not contain registered disappearing links of any kind) when it is explicitly deallocated. GC_free(0) is a no-op, as required by ANSI C for free().

GC_free_profiler_hook^⚠

A symbol to be intercepted by heap profilers so that they can accurately track allocations. Programs such as Valgrind massif and KDE heaptrack do tracking of allocated objects by overriding common allocator methods (e.g. malloc and free). However, because the collector does not work by calling standard allocation methods on objects that were reclaimed, we need a way to tell the profiler that an object has been freed. This function is not intended to be called by the client, it should be used for the interception purpose only. The collector calls this function internally whenever an object is freed. Defined only if the library has been compiled with VALGRIND_TRACKING macro defined.

GC_freezero^⚠

Similar to GC_free but also clears the object before deallocation. Guaranteed to clear the specified amount of bytes from the beginning of the deallocated object. It is safe to pass a value larger than the size of the object, e.g. ~0 could be passed to clear the entire object.

GC_gcollect^⚠

Explicitly trigger a full, world-stop collection.

GC_gcollect_and_unmap^⚠

Same as above but ignores the default stop_func setting and tries to unmap as much memory as possible (regardless of the corresponding switch setting). The recommended usage: on receiving a system low-memory event; before retrying a system call failed because of the system is running out of resources.

GC_general_register_disappearing_link^⚠

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.

GC_get_abort_func^⚠

GC_get_actual_vdb^⚠

An extended variant of GC_is_incremental_mode() to return one of GC_VDB_ constants designating which VDB (virtual dirty bits) technique is used exactly. Does not acquire the allocator lock.

GC_get_all_interior_pointers^⚠

GC_get_allocd_bytes_per_finalizer^⚠

GC_get_avg_stopped_mark_time_ns^⚠

Get the average time spent in all mark phases with the world stopped. The average value is computed since the start of the performance measurements (or right since the collector initialization if the collector logging is enabled). The result is in nanoseconds. The function acquires the allocator lock (in the reader mode) to avoid data race. Defined only if the library has been compiled without NO_CLOCK macro defined.

GC_get_await_finalize_proc^⚠

GC_get_bytes_since_gc^⚠

Return the number of bytes allocated since the last collection. This is an unsynchronized getter (see GC_get_heap_size comment regarding thread-safety).

GC_get_disable_automatic_collection^⚠

GC_get_dont_expand^⚠

GC_get_dont_precollect^⚠

GC_get_expl_freed_bytes_since_gc^⚠

Return the number of explicitly deallocated bytes of memory since the recent collection. This is an unsynchronized getter.

GC_get_finalize_on_demand^⚠

GC_get_finalizer_notifier^⚠

GC_get_find_leak^⚠

GC_get_force_unmap_on_gcollect^⚠

GC_get_free_bytes^⚠

Return a lower bound on the number of free bytes in the heap (excluding the unmapped memory space). This is an unsynchronized getter (see GC_get_heap_size comment regarding thread-safety).

GC_get_free_space_divisor^⚠

GC_get_full_freq^⚠

GC_get_full_gc_total_ns_frac^⚠

Get the fractional nanosecond part of the total time value returned by GC_get_full_gc_total_time(). The result is always less than 1000000. In the multi-threaded mode, the client should use GC_call_with_reader_lock() to get a consistent total time value. Defined only if the library has been compiled without NO_CLOCK macro defined.

GC_get_full_gc_total_time^⚠

Get the total time of all full collections since the start of the performance measurements. Includes time spent in the supplementary actions like blacklists promotion, marks clearing, free lists reconstruction and objects finalization. The measurement unit is a millisecond. Note that the returned value wraps around on overflow. The function does not use any synchronization. Defined only if the library has been compiled without NO_CLOCK macro defined.

GC_get_gc_no^⚠

GC_get_heap_size^⚠

Return the number of bytes in the heap. Excludes collector private data structures; excludes the unmapped memory (returned to the OS). Includes empty blocks and fragmentation loss. Includes some pages that were allocated but never written. This is an unsynchronized getter, so it should be called typically with the allocator lock held, at least in the reader mode, to avoid data race on multiprocessors (the alternative way is to use GC_get_prof_stats or GC_get_heap_usage_safe API calls instead). This getter remains lock-free (unsynchronized) for compatibility reason since some existing clients call it from a GC callback holding the allocator lock. (This API function and the following four ones below were made thread-safe in GC v7.2alpha1 and reverted back in v7.2alpha7 for the reason described.)

GC_get_heap_usage_safe^⚠

Return the heap usage information. This is a thread-safe (atomic) alternative for the five above getters. (This function acquires the allocator lock in the reader mode, thus preventing data race and returning the consistent result.) Passing NULL pointer is allowed for any argument. Returned (filled in) values are of GC_word type.

GC_get_interrupt_finalizers^⚠

GC_get_is_valid_displacement_print_proc^⚠

GC_get_is_visible_print_proc^⚠

GC_get_java_finalization^⚠

GC_get_manual_vdb_allowed^⚠

GC_get_max_prior_attempts^⚠

GC_get_max_retries^⚠

GC_get_memory_use^⚠

Return the total memory use (in bytes) by all allocated blocks. The result is equal to GC_get_heap_size() - GC_get_free_bytes(). Acquires the allocator lock in the reader mode.

GC_get_min_bytes_allocd^⚠

GC_get_mprotect_vdb_allowed^⚠

GC_get_my_stackbottom^⚠

Fill in the GC_stack_base structure with the cold end (bottom) of the stack of the current thread (or coroutine). Unlike GC_get_stack_base, it retrieves the value stored in the collector (which is initially set by the collector upon the thread is started or registered manually but it could be later updated by client using GC_set_stackbottom). Returns the GC-internal non-NULL handle of the thread which could be passed to GC_set_stackbottom() later. It is assumed that the collector is already initialized and the thread is registered. Acquires the allocator lock in the reader mode.

GC_get_no_dls^⚠

GC_get_non_gc_bytes^⚠

GC_get_obtained_from_os_bytes^⚠

Return the total number of bytes obtained from OS. Includes the unmapped memory. Never decreases. It is an unsynchronized getter.

GC_get_on_collection_event^⚠

GC_get_on_heap_resize^⚠

GC_get_on_os_get_mem^⚠

GC_get_on_thread_event^⚠

GC_get_oom_fn^⚠

GC_get_pages_executable^⚠

Returns nonzero value if the garbage collector is set to the allocate-executable-memory mode. The mode could be changed by GC_set_pages_executable (before GC_INIT() call) unless the former has no effect on the platform. Does not use or need synchronization.

GC_get_parallel^⚠

Return value of GC_parallel. Does not acquire the allocator lock.

GC_get_prof_stats^⚠

Atomically get the collector statistics (various global counters). Clients should pass the size of the buffer (of GC_prof_stats_s type) to fill in the values - this is for interoperability between different collector versions: an old client could have fewer fields, and vice versa, client could use newer gc.h file (with more entries declared in the structure) than that of the linked collector library; in the latter case, unsupported (unknown) fields are filled in with -1 (~0). Return the size (in bytes) of the filled in part of the structure (excluding all unknown fields, if any).

GC_get_prof_stats_unsafe^⚠

Same as GC_get_prof_stats but unsynchronized (i.e., not holding the allocator lock). Clients should call it using GC_call_with_reader_lock() to avoid data race on multiprocessors.

GC_get_rate^⚠

GC_get_same_obj_print_proc^⚠

GC_get_size_map_at^⚠

Get the element value (converted to bytes) at a given index of GC_size_map table which provides requested-to-actual allocation size mapping. Assumes the collector is initialized. Returns -1 (~0) if the index is out of GC_size_map table bounds. Does not use synchronization, thus clients should call it using GC_call_with_reader_lock() typically to avoid data race on multiprocessors.

GC_get_sp_corrector^⚠

GC_get_stack_base^⚠

Attempt to fill in the GC_stack_base structure with the stack bottom for this thread. This appears to be required to implement anything like the JNI (Java Native Interface) AttachCurrentThread in an environment in which new threads are not automatically registered with the collector. It is also unfortunately hard to implement well on many platforms. Returns GC_SUCCESS or GC_UNIMPLEMENTED. Acquires the allocator lock on some platforms.

GC_get_stop_func^⚠

GC_get_stopped_mark_total_time^⚠

Same as GC_get_full_gc_total_time but takes into account all mark phases with the world stopped and nothing else.

GC_get_supported_vdbs^⚠

Get the list of available VDB (virtual dirty bits) techniques. The returned value is a constant one, either GC_VDB_NONE, or one or more of the above GC_VDB_ constants, or’ed together. The result is not affected by GC_set_mprotect_vdb_allowed(). May be called before the collector is initialized.

GC_get_suspend_signal^⚠

Return the signal number (which is a constant after the collector initialization) used by the collector to suspend threads on POSIX systems. Return -1 otherwise.

GC_get_thr_restart_signal^⚠

Return the signal number (which is a constant after the collector initialization) used by the collector to restart (resume) threads on POSIX systems. Return -1 otherwise.

GC_get_time_limit^⚠

GC_get_time_limit_tv^⚠

GC_get_toggleref_func^⚠

GC_get_total_bytes^⚠

Return the total number of bytes allocated in this process. Never decreases, except due to wrapping. This is an unsynchronized getter (see GC_get_heap_size comment regarding thread-safety).

GC_get_unmapped_bytes^⚠

Return the size (in bytes) of the unmapped memory (which is returned to the OS but could be remapped back by the collector later unless the OS runs out of system/virtual memory). This is an unsynchronized getter (see GC_get_heap_size comment regarding thread-safety).

GC_get_version^⚠

Get the collector library version. The returned value is a constant in the form: ((version_major << 16) | (version_minor << 8) | version_micro).

GC_get_warn_proc^⚠

GC_ignore_warn_proc^⚠

GC_ignore_warn_proc may be used as an argument for GC_set_warn_proc() to suppress all warnings (unless statistics printing is turned on). This is recommended for production code (release).

GC_incremental_protection_needs^⚠

Does incremental mode write-protect pages in a client-visible way? Returns zero or more of the above GC_PROTECTS_ constants, or’ed together. The collector is assumed to be initialized before this call. The result is not affected by GC_set_manual_vdb_allowed(). Call of GC_enable_incremental() may change the result to GC_PROTECTS_NONE if some VDB implementation chosen at runtime is not needing to write-protect the pages (thus GC_set_mprotect_vdb_allowed(0) might affect the result).

GC_init^⚠

Initialize the collector. Portable clients should call GC_INIT() from the program’s main() instead.

GC_invoke_finalizers^⚠

Run finalizers for all objects that are ready to be finalized. Return the number of finalizers that were run. Normally this is also called implicitly during some allocations. If GC_finalize_on_demand is nonzero, it must be called explicitly.

GC_is_disabled^⚠

Return 1 (true) if the garbage collection is disabled (i.e., the value of GC_dont_gc is nonzero), 0 otherwise. Does not acquire the allocator lock.

GC_is_heap_ptr^⚠

Return 1 (true) if the argument points to somewhere in the garbage collected heap, 0 otherwise. Primary use is as a fast alternative to GC_base_C() to check whether the given object is allocated by the collector or not. It is assumed that the collector is already initialized.

GC_is_incremental_mode^⚠

Return 1 (true) if the incremental mode is on, 0 otherwise. Does not acquire the allocator lock.

GC_is_init_called^⚠

Return 1 (true) if the collector is initialized (or, at least, the initialization is in progress), 0 otherwise.

GC_is_valid_displacement^⚠

Check that if p is a pointer to a heap page, then it points to a valid displacement within a heap object. If it is not, invoke GC_is_valid_displacement_print_proc (fail by default). Always returns the argument (p). Uninteresting in the all-interior-pointers mode. Note that we do not acquire the allocator lock, since nothing relevant about the header should change while we have a valid object pointer to the block.

GC_is_visible^⚠

Check that p is visible to the collector as a possibly pointer containing location. If it is not, call GC_is_visible_print_proc (fail by default). Always returns the argument (p). May erroneously succeed in hard cases. The function is intended for debugging use with untyped allocations. (The idea is that it should be possible, though slow, to add such a call to all indirect pointer stores.) Currently almost useless for the multi-threaded worlds.

GC_malloc^⚠

General-purpose allocation functions, with roughly malloc calling conventions. The atomic variants promise that no relevant pointers are contained in the object. The non-atomic variants guarantee that the new object is cleared. GC_malloc_uncollectable() allocates an object that is scanned for pointers to collectible objects, but is not itself collectible. The object is scanned even if it does not appear to be reachable. GC_malloc_uncollectable(), GC_free() (and GC_freezero()) called on the resulting object implicitly update GC_non_gc_bytes appropriately. All these functions (GC_malloc, GC_malloc_atomic, GC_strdup, GC_strndup, GC_malloc_uncollectable) are guaranteed never to return NULL unless GC_oom_fn() returns NULL.

GC_malloc_atomic^⚠

GC_malloc_atomic_ignore_off_page^⚠

GC_malloc_atomic_uncollectable^⚠

Allocate lb bytes of pointer-free, untraced, uncollectible data. This is normally roughly equivalent to the system malloc. But it may be useful if malloc is redefined. The function (including its debug variant) is guaranteed never to return NULL unless GC_oom_fn() returns NULL. Defined only if the library has been compiled with GC_ATOMIC_UNCOLLECTABLE macro defined.

GC_malloc_ignore_off_page^⚠

Allocate an object of size lb bytes. The client guarantees that as long as the object is live, it will be referenced by a pointer that points to somewhere within the first GC heap block (hblk) of the object. (This should normally be declared volatile to prevent the compiler from invalidating this assertion.) This function is only useful if a large array is being allocated. It reduces the chance of accidentally retaining such an array as a result of scanning an integer that happens to be an address inside the array. (Actually, it reduces the chance of the allocator not finding space for such an array, since it will try hard to avoid introducing such a false reference.) On a SunOS 4.x or Windows system this is recommended for arrays likely to be larger than 100 KB or so. For other systems, or if the collector is not configured to recognize all interior pointers, the threshold is normally much higher. These functions are guaranteed never to return NULL unless GC_oom_fn() returns NULL.

GC_malloc_many^⚠

This returns a list of objects with the link pointer located at the beginning of each object. The use of such list can greatly reduce lock contention problems, since the allocator lock can be acquired and released many fewer times. Note that there is no “atomic” variant of this function, as otherwise the links would not be seen by the collector. If the argument (lb) is zero, then it is treated as 1. The function is guaranteed never to return NULL unless GC_oom_fn() returns NULL.

GC_malloc_stubborn^⚠

GC_malloc_uncollectable^⚠

GC_memalign^⚠

The allocation function which guarantees the requested alignment of the allocated memory object. The align argument should be nonzero and a power of two. It is guaranteed never to return NULL unless GC_oom_fn() returns NULL.

GC_move_disappearing_link^⚠

Moves a link previously registered via GC_general_register_disappearing_link (or GC_register_disappearing_link). Does not change the target object of the weak reference. Does not change contents of *new_link. May be called with new_link equal to link (to check whether link has been registered). Returns GC_SUCCESS on success, GC_DUPLICATE if there is already another disappearing link at the new location (never returned if new_link is equal to link), GC_NOT_FOUND if no link is registered at the original location.

GC_move_long_link^⚠

Similar to GC_move_disappearing_link but for a link previously registered via GC_register_long_link.

GC_noop1^⚠

Make the argument of GC_word type appear live to compiler. This could be used to prevent certain compiler false positive (FP) warnings and misoptimizations. Should be robust against the whole program analysis.

GC_noop1_ptr^⚠

Same as GC_noop1() but for a pointer.

GC_posix_memalign^⚠

A function similar to GC_memalign but existing largely for redirection in the find-leak mode. The align argument should be nonzero and a power of two, but additionally the argument is required to be not less than size of a pointer. Note that the function does not change value of *memptr in case of failure (i.e. when the result is nonzero). It is guaranteed never to return NULL unless GC_oom_fn() returns NULL.

GC_post_incr^⚠

GC_pre_incr^⚠

Checked pointer pre- and post-increment operations. Note that the second argument (how_much) is in units of bytes, not multiples of the object size. This should either be invoked from a macro, or the call should be automatically generated.

GC_pthread_cancel^⚠

GC_pthread_create^⚠

GC_pthread_detach^⚠

GC_pthread_exit^⚠

GC_pthread_join^⚠

GC_pthread_sigmask^⚠

GC_ptr_store_and_dirty^⚠

GC_pvalloc^⚠

GC_realloc^⚠

For compatibility with C library. This is occasionally faster than a malloc followed by a bcopy. But if you rely on that, either here or with the standard C library, your code is broken. Probably, it should not have been invented, but now we are stuck. The resulting object has the same kind as the original one. It is an error to have changes enabled for the original object. It does not change the contents of the object from its beginning to the minimum of old size and new_size_in_bytes; the contents above in case of object size growth is initialized to zero (not guaranteed for atomic object type). The function follows ANSI conventions for NULL old_object (i.e., equivalent to GC_malloc regardless of new_size_in_bytes). If new_size_in_bytes is zero (and old_object is non-NULL), then the call is equivalent to GC_free (and NULL is returned). If old_object is non-NULL, it must have been returned by an earlier call to GC_realloc, GC_malloc or friends. In case of the allocation failure, GC_realloc (and its debug variant) does not touch and does not free memory pointed by old_object. The logic of GC_reallocf and its debug variant is different - they free memory pointed by old_object if the allocation has failed. If the returned pointer is not the same as old_object and both of them are non-NULL, then old_object is freed. Returns either NULL (in case of the allocation failure or zero new_size_in_bytes) or pointer to the allocated memory. For a nonzero new_size_in_bytes, the functions are guaranteed never to return NULL unless GC_oom_fn() returns NULL.

GC_reallocf^⚠

GC_register_altstack^⚠

Notify the collector about the stack and the alt-stack of the current thread. normstack and normstack_size are used to determine the “normal” stack boundaries when a thread is suspended while it is on an alt-stack. Acquires the allocator lock in the reader mode.

GC_register_disappearing_link^⚠

This routine may be used to break cycles between finalizable objects, thus causing cyclic finalizable objects to be finalized in the correct order. The standard use involves calling GC_register_disappearing_link(&p), where p is a pointer that is not followed by finalization code, and should not be considered in determining finalization order. link should point to a field of a heap-allocated object. *link will be cleared when the object is found to be inaccessible. This happens before any finalization code is invoked, and before any decisions about finalization order are made. This is useful in telling the finalizer that some pointers are not essential for proper finalization. This may avoid finalization cycles. Note that the object may be resurrected by another finalizer, and thus the clearing of *link may be visible to non-finalization code. There is an argument that an arbitrary action should be allowed here, instead of just clearing a pointer. But this causes problems if that action alters, or examines connectivity. Returns GC_DUPLICATE if given link was already registered, GC_SUCCESS if registration succeeded, GC_NO_MEMORY if it failed for lack of memory (and GC_oom_fn did not handle the problem). Only exists for backward compatibility, use GC_general_register_disappearing_link() instead.

GC_register_displacement^⚠

Add a displacement to the set of those considered valid by the collector. GC_register_displacement(offset) means that if p was returned by GC_malloc(), then (char *)p + offset will be considered to be a valid pointer to p. offset must be less than the size of a heap block. (All pointers to the interior of objects from the stack are considered valid in any case. This applies to heap objects and static data.) Preferably, this should be called before any other GC procedures. Calling it later adds to the probability of excess memory retention. This is a no-op if the collector has recognition of arbitrary interior pointers enabled, which is the default (assuming the collector is built with ALL_INTERIOR_POINTERS macro defined). The debugging variant should be used if any debugging allocation is being done.

GC_register_finalizer^⚠

When obj is no longer accessible, invoke (*fn)(obj, cd). If a and b are inaccessible, and a points to b (after disappearing links have been made to disappear), then only a will be finalized. (If this does not create any new pointers to b, then b will be finalized after the next collection.) Any finalizable object that is reachable from itself by following one or more pointers will not be finalized (or collected). Thus cycles involving finalizable objects should be avoided, or broken by disappearing links. All but the last finalizer registered for an object is ignored. No-op in the find-leak mode. Finalization may be removed by passing 0 as fn. Finalizers are implicitly unregistered when they are enqueued for finalization (i.e. become ready to be finalized). The old finalizer and client data are stored in *ofn and *ocd, respectively. (ofn and/or ocd may be NULL. The allocator lock is held while *ofn and *ocd are updated. In case of error (no memory to register new finalizer), *ofn and *ocd remain unchanged.) fn is never invoked on an accessible object, provided hidden pointers are converted to real pointers only if the allocator lock is held, at least in the reader mode, and such conversions are not performed by finalization routines. If GC_register_finalizer() is aborted as a result of a signal, then the object may be left with no finalization, even if neither the old nor new finalizer were NULL. obj should be the starting address of an object allocated by GC_malloc or friends. obj may also be NULL or point to something outside the collector heap (in this case, fn is ignored, *ofn and *ocd are set to NULL). Note that any garbage collectible object referenced by cd will be considered accessible until the finalizer is invoked.

GC_register_finalizer_ignore_self^⚠

Another variant of GC_register_finalizer but ignoring self-cycles, i.e. pointers from a finalizable object to itself. There is a stylistic argument that this is wrong, but it is unavoidable for C++, since the compiler may silently introduce these. It is also benign in that specific case. And it helps if finalizable objects are split to avoid cycles. Note that cd will still be viewed as accessible, even if it refers to the object itself.

GC_register_finalizer_no_order^⚠

Another variant of GC_register_finalizer which ignores all cycles. It should probably only be used by Java implementations. Note that cd will still be viewed as accessible, even if it refers to the object itself.

GC_register_finalizer_unreachable^⚠

This is a special finalizer that is useful when an object’s finalizer must be run when the object is known to be no longer reachable, not even from other finalizable objects. It behaves like “normal” finalization, except that the finalizer is not run while the object is reachable from other objects specifying unordered finalization. Effectively it allows an object referenced, possibly indirectly, from an unordered finalizable object to override the unordered finalization request. This can be used in combination with GC_register_finalizer_no_order so as to release resources that must not be released while an object can still be brought back to life by other finalizers. Only works if GC_java_finalization is set. Probably only of interest when implementing a language that requires unordered finalization (e.g. Java, C#).

GC_register_has_static_roots_callback^⚠

Register a new callback (a user-supplied filter) to control the scanning of dynamic libraries. Replaces any previously registered callback. May be 0 (means no filtering). May be unused on some platforms (if the filtering is unimplemented or inappropriate).

GC_register_long_link^⚠

Similar to GC_general_register_disappearing_link but *link only gets cleared when obj becomes truly inaccessible. An object becomes truly inaccessible when it can no longer be resurrected from its finalizer (e.g. by assigning itself to a pointer traceable from root). This can be used to implement “long” weak pointers easily and safely.

GC_register_my_thread^⚠

Register the current thread, with the indicated stack bottom, as a new thread whose stack(s) should be traced by the collector. If it is not implicitly called by the collector, this must be called before a thread can allocate garbage-collected memory, or assign pointers to the garbage-collected heap. Once registered, a thread will be stopped during garbage collections. This call must be previously enabled (see GC_allow_register_threads). This should never be called from the main thread, where it is always done implicitly. This is normally done implicitly if GC_ functions are called to create the thread, e.g. by include gc.h file (which redefines some system functions) before calling the system thread creation function. Nonetheless, thread cleanup routines (e.g., pthreads key destructor) typically require manual thread registering (and unregistering) if pointers to GC-allocated objects are manipulated inside. It is also always done implicitly on Win32 platform if GC_use_threads_discovery() is called at start-up. Except for the latter case, the explicit call is normally required for threads created by third-party libraries. A manually registered thread requires manual unregistering. Returns GC_SUCCESS on success, GC_DUPLICATE if already registered.

GC_remove_roots^⚠

Remove root segments located fully in the region. Wizards only.

GC_same_obj^⚠

Check that p and q point to the same object. GC_same_obj_print_proc is called (fail by default) if they do not. Succeeds, as well, if neither p nor q points to the heap. (May succeed also if both p and q point to between heap objects.) Returns the first argument (p). (The returned value may be hard to use due to typing issues. But if we had a suitable preprocessor…) We assume this is somewhat performance critical (it should not be called by production code, of course, but it can easily make even debugging intolerably slow).

GC_set_abort_func^⚠

GC_set_all_interior_pointers^⚠

GC_set_allocd_bytes_per_finalizer^⚠

Set/get the minimum value of the ratio of allocated bytes since garbage collection to the amount of finalizers created since that collection (so value is greater than GC_bytes_allocd / (GC_fo_entries - last_fo_entries)) which triggers the collection instead heap expansion. The value has no effect in the collector incremental mode. The default value is 10000 unless GC_ALLOCD_BYTES_PER_FINALIZER macro with a custom value is defined to build the collector. The default value might be not the right choice for clients where e.g. most objects have a finalizer. Zero value effectively disables taking amount of finalizers in the decision whether to collect or not. The functions do not use any synchronization.

GC_set_await_finalize_proc^⚠

GC_set_disable_automatic_collection^⚠

Control whether to disable algorithm deciding if a collection should be started when we allocated enough to amortize the collection. Both the setter and the getter acquire the allocator lock (in the reader mode in case of the getter) to avoid data race.

GC_set_dont_expand^⚠

GC_set_dont_precollect^⚠

GC_set_finalize_on_demand^⚠

GC_set_finalizer_notifier^⚠

GC_set_find_leak^⚠

GC_set_force_unmap_on_gcollect^⚠

The setter and the getter for switching “unmap as much as possible” mode on(1) and off(0). Has no effect unless unmapping is turned on. Initial value is controlled by GC_FORCE_UNMAP_ON_GCOLLECT macro. The setter and the getter are unsynchronized.

GC_set_free_space_divisor^⚠

GC_set_full_freq^⚠

GC_set_handle_fork^⚠

Overrides the default handle-fork mode. A nonzero value means GC should install proper pthread_atfork handlers. Has effect only if called before the collector initialization. Clients should call GC_set_handle_fork() with nonzero argument if going to use fork with the GC functions called in the child process. (Note that such client and at-fork handler activities are not fully POSIX-compliant.) GC_set_handle_fork() instructs GC_init to setup GC fork handlers using pthread_atfork(), the latter might fail (or, even, absent on some targets) causing abort at the collector initialization. Issues with missing (or failed) pthread_atfork() could be avoided by invocation of GC_set_handle_fork(-1) at application start-up and surrounding each fork() with the relevant GC_atfork_prepare/GC_atfork_parent/GC_atfork_child calls.

GC_set_interrupt_finalizers^⚠

Set maximum amount of finalizers to run during a single invocation of GC_invoke_finalizers(). Zero means no limit. Both the setter and the getter acquire the allocator lock (in the reader mode in case of the getter). Note that invocation of GC_finalize_all() resets the maximum amount value.

GC_set_is_valid_displacement_print_proc^⚠

GC_set_is_visible_print_proc^⚠

GC_set_java_finalization^⚠

GC_set_log_fd^⚠

Change file descriptor of the collector log. Unavailable on some targets.

GC_set_manual_vdb_allowed^⚠

Select whether to use the manual VDB (virtual dirty bits) mode for the incremental collection. Has no effect if called after enabling the incremental collection. The default value is off unless the collector is compiled with MANUAL_VDB macro defined. The manual VDB mode should be used only if the client has the appropriate GC_END_STUBBORN_CHANGE() and GC_reachable_here() (or, alternatively, GC_PTR_STORE_AND_DIRTY()) calls (to ensure proper write barriers). The setter and the getter are not synchronized.

GC_set_markers_count^⚠

Set the number of marker threads (including the initiating one) to the desired value at start-up. Zero value means the collector is to decide. If the correct nonzero value is passed, then GC_parallel will be set to the value minus one later. Has no effect if called after the collector initialization. Does not itself cause creation of the marker threads. Does not use any synchronization.

GC_set_max_heap_size^⚠

Limit the heap size to n bytes. Useful when you are debugging, especially on systems that do not handle running out of memory well. A zero n means the heap is unbounded; this is the default. This setter function is unsynchronized (so it might require GC_call_with_alloc_lock to avoid data race).

GC_set_max_prior_attempts^⚠

Set/get the maximum number of prior attempts at the world-stop marking. Not synchronized.

GC_set_max_retries^⚠

GC_set_min_bytes_allocd^⚠

The setter and the getter of the minimum value returned by the internal min_bytes_allocd(). The value should not be zero; the default value is one. Not synchronized.

GC_set_mprotect_vdb_allowed^⚠

Select whether to allow usage of the mprotect-based VDB (virtual dirty bits) mode for the incremental collection. The default value is on regardless of the availability of this VDB mode. Disallowing the mprotect-based VDB might be useful for applications that use mprotect() and/or SIGSEGV/SIGBUS for own needs or cannot deal with the related unintended system call failures. Has no effect if called after enabling the incremental collection (either explicitly or implicitly during the collector initialization). The setter and the getter are not synchronized.

GC_set_no_dls^⚠

GC_set_non_gc_bytes^⚠

GC_set_on_collection_event^⚠

GC_set_on_heap_resize^⚠

GC_set_on_os_get_mem^⚠

GC_set_on_thread_event^⚠

GC_set_oom_fn^⚠

GC_set_pages_executable^⚠

Set whether the garbage collector will allocate executable memory pages or not. A nonzero argument instructs the collector to allocate memory with the executable flag on. Must be called before the collector is initialized. May have no effect on some platforms. The default value is controlled by NO_EXECUTE_PERMISSION macro (if present then the flag is off). Portable clients should have GC_set_pages_executable(1) call (before GC_INIT() one) provided they are going to execute code on any of the GC-allocated memory objects.

GC_set_rate^⚠

Set/get the size in pages of units operated by GC_collect_a_little(). The value should not be zero. Not synchronized.

GC_set_same_obj_print_proc^⚠

GC_set_sp_corrector^⚠

GC_set_stackbottom^⚠

Set the cool end of the user (coroutine) stack of the specified thread. The GC thread handle (gc_thread_handle) is either the one returned by GC_get_my_stackbottom() or NULL (the latter designates the current thread). The caller should hold the allocator lock (e.g. using GC_call_with_reader_lock() with release argument set to 1), the reader mode should be enough typically, at least for the collector itself (the client is responsible to avoid data race between this and GC_get_my_stackbottom functions if the client acquires the allocator lock in the reader mode). Also, the function could be used for setting GC_stackbottom value (the bottom of the primordial thread) before the collector is initialized (the allocator lock is not needed to be acquired at all in this case).

GC_set_stop_func^⚠

Set/get the default stop_func. The latter is used by GC_gcollect() and by implicitly triggered collections (except for the case when handling out of memory). Must not be 0. Both the setter and the getter acquire the allocator lock (in the reader mode in case of the getter) to avoid data race.

GC_set_suspend_signal^⚠

Suggest the collector to use the specific signal to suspend threads. Has no effect after the collector initialization and on non-POSIX systems.

GC_set_thr_restart_signal^⚠

Suggest the collector to use the specific signal to resume threads. Has no effect after the collector initialization and on non-POSIX systems. The same signal might be used for threads suspension and restart.

GC_set_time_limit^⚠

GC_set_time_limit_tv^⚠

Set/get the time limit of the incremental collections. This is similar to GC_set_time_limit and GC_get_time_limit but the time is provided with the nanosecond precision. The value of tv_nsec part should be less than a million. If the value of tv_ms part is GC_TIME_UNLIMITED, then tv_nsec part is ignored. Initially, the value of tv_nsec part of the time limit is zero. The functions do not use any synchronization. Defined only if the library has been compiled without NO_CLOCK macro defined.

GC_set_toggleref_func^⚠

Set (register) a callback that decides the state of a given object (by, probably, inspecting its native state). The argument may be 0 (means no callback). Both the setter and the getter acquire the allocator lock (in the reader mode in case of the getter).

GC_set_warn_proc^⚠

GC_should_invoke_finalizers^⚠

Returns a nonzero value (true) if GC_invoke_finalizers() has something to do. (Useful if finalizers can only be called from some kind of “safe state” and getting into that safe state is expensive.) Does not use any synchronization.

GC_size^⚠

Given a pointer to the base of an object, return its size in bytes. (For small objects this also happens to work from interior pointers, but that should not be relied upon.) The returned size may be slightly larger than the actual size of the object (the returned value may include the size of the object debug header, an extra byte past end of the object, etc.). The argument may be NULL (causing 0 to be returned).

GC_start_incremental_collection^⚠

Force start of incremental collection. Acquires the allocator lock. No-op unless the incremental mode is on.

GC_start_mark_threads^⚠

Start the parallel marker threads, if available. Useful, e.g., after POSIX fork in a child process (provided not followed by exec()) or in single-threaded clients (provided it is OK for the client to perform marking in parallel). Acquires the allocator lock to avoid a race.

GC_start_performance_measurement^⚠

Tell the collector to start various performance measurements. Only the total time taken by full collections and the average time spent in the world-stopped collections are calculated, as of now. And, currently, there is no way to stop the measurements. The function does not use any synchronization. Defined only if the library has been compiled without NO_CLOCK macro defined.

GC_start_world_external^⚠

GC_stop_world_external^⚠

Stop/start the world explicitly. Not recommended for general use.

GC_strdup^⚠

GC_strndup^⚠

GC_thread_is_registered^⚠

Return 1 (true) if the calling (current) thread is registered with the garbage collector, 0 otherwise. Acquires the allocator lock in the reader mode. If the thread is finished (e.g. running in a destructor and not registered manually again), then it is considered as not registered.

GC_toggleref_add^⚠

Register a given object for “toggle-refs” processing. It will be stored internally and the “toggle-refs” callback will be invoked on the object until the callback returns GC_TOGGLE_REF_DROP or the object is collected. If is_strong, then the object is registered with a strong ref, a weak one otherwise. obj should be the starting address of an object allocated by GC_malloc (GC_debug_malloc) or friends. Returns GC_SUCCESS if registration succeeded (or no callback is registered yet), GC_NO_MEMORY if it failed for a lack of memory reason.

GC_try_to_collect^⚠

GC_unregister_disappearing_link^⚠

Undoes a registration by either GC_register_disappearing_link() or GC_general_register_disappearing_link(). Returns 0 if link was not actually registered (otherwise returns 1).

GC_unregister_long_link^⚠

Similar to GC_unregister_disappearing_link but for link registration done by GC_register_long_link().

GC_unregister_my_thread^⚠

Unregister the current thread. Only an explicitly registered thread (i.e. for which GC_register_my_thread() returns GC_SUCCESS) is allowed (and required) to call this function. (As a special exception, it is also allowed to once unregister the main thread.) The thread may no longer allocate garbage-collected memory or manipulate pointers to the garbage-collected heap after making this call. Specifically, if it wants to return or otherwise communicate a pointer to the garbage-collected heap to another thread, it must do this before calling GC_unregister_my_thread, most probably by saving it in a global data structure. Must not be called inside a GC callback function (except for GC_call_with_stack_base() one). Always returns GC_SUCCESS.

GC_valloc^⚠

The allocation functions that guarantee the memory page alignment of the returned object. Exist largely for redirection in the find-leak mode. All these functions (GC_pvalloc, GC_valloc) are guaranteed never to return NULL unless GC_oom_fn() returns NULL.

GC_win32_free_heap^⚠

win32s may not free all resources on process exit. This explicitly deallocates the heap. Defined only for Windows.

Type Aliases

GC_EventType

GC_PTR

GC_ToggleRefStatus

GC_abort_func

This is invoked on the collector fatal aborts (just before OS-dependent abort() or exit(1) is called). Must be non-NULL. The default one outputs msg to the platform stderr provided msg is non-NULL. msg is NULL if invoked before exit(1) otherwise msg is non-NULL (i.e., if invoked before abort). Both the setter and the getter acquire the allocator lock (in the reader mode in case of the getter). The setter does not change GC_abort_func if the library has been compiled with SMALL_CONFIG macro defined.

GC_await_finalize_proc

Finalizer callback support. Invoked by the collector (with the allocator lock held) for each unreachable object enqueued for finalization. Zero means no callback. The setter and the getter acquire the allocator lock too (in the reader mode in case of the getter).

GC_finalization_proc

GC_finalizer_notifier_proc

Invoked by the collector when there are objects to be finalized. Invoked at most once per collection cycle. Never invoked unless GC_finalize_on_demand is set. Typically this will notify a finalization thread, which will call GC_invoke_finalizers() in response. May be 0 (means no notifier). Both the setter and the getter acquire the allocator lock (in the reader mode in case of the getter).

GC_fn_type

GC_has_static_roots_func

A filter function to control the scanning of dynamic libraries. If implemented, called by the collector before registering a dynamic library (discovered by the collector) section as a static data root (called only as a last reason not to register). The filename (dlpi_name) of the library, the address and the length of the memory region (section) are passed. This routine should return a nonzero value if that region should be scanned. Always called with the allocator lock held. Depending on the platform, might be called with the world stopped.

GC_heap_section_proc

GC_heap_section_type

GC_hidden_pointer

GC_on_collection_event_proc

Invoked to indicate progress through the collection process. Not used for thread suspend/resume notifications. Called with the allocator lock held (or, even, the world stopped). May be 0 (means no notifier). Both the setter and the getter acquire the allocator lock (in the reader mode in case of the getter).

GC_on_heap_resize_proc

Invoked when the heap grows or shrinks. Called with the world stopped (and the allocator lock held). May be 0. Both the setter and the getter acquire the allocator lock (in the reader mode in case of the getter).

GC_on_os_get_mem_proc

Invoked when new memory space is obtained from the OS. Called with the allocator lock held. If space argument is NULL, this means a failure to the get the memory. The argument of GC_set_on_os_get_mem() may be 0 (means no notifier). Both the setter and the getter acquire the allocator lock (in the reader mode in case of the getter).

GC_on_thread_event_proc

Invoked when a thread is suspended or resumed during collection. Called with the allocator lock held (and the world stopped partially). May be 0 (means no notifier). Both the setter and the getter acquire the allocator lock (in the reader mode in case of the getter).

GC_oom_func

When there is insufficient memory to satisfy an allocation request, we return (*GC_oom_fn)(size). If it returns, it must return either NULL or a valid pointer to a previously allocated heap object. By default, this just returns NULL. If it points to a function which never returns NULL, probably by aborting the program instead, then invocations of GC_MALLOC() and friends (that are additionally marked as “never returning NULL unless GC_oom_fn returns NULL”) do not need to be followed by code that checks for the NULL result. GC_oom_fn must not be 0. Both the setter and the getter acquire the allocator lock (in the reader mode in case of the getter) to avoid data race.

GC_return_addr_t

GC_same_obj_print_proc_t

GC_signed_word

GC_sp_corrector_proc

Provide a verifier/modifier of the stack pointer when pushing the thread stacks. This might be useful for a crude integration with certain coroutine implementations. *sp_ptr is the captured stack pointer of the suspended thread with pthread_id (the latter is actually of pthread_t type). The functionality is unsupported on some targets (the getter always returns 0 in such a case). Both the setter and the getter acquire the allocator lock (in the reader mode in case of the getter). The client function (if provided) is called with the allocator lock held and, might be, with the world stopped.

GC_stack_base_func

GC_stop_func

Trigger a full world-stopped collection. Abort the collection if and when stop_func() returns a nonzero value. stop_func() will be called frequently, and should be reasonably fast. (stop_func() is called with the allocator lock held and the world might be stopped; it is not allowed for stop_func() to manipulate pointers to the garbage-collected heap or call most of GC functions.) This works even if no virtual dirty bits, and hence incremental collection is not available for the architecture. Collections can be aborted faster than normal pause times for incremental collection; however, aborted collections do no useful work; the next collection needs to start from the beginning. stop_func must not be 0. GC_try_to_collect() returns 0 if the collection was aborted (or the collections are disabled), 1 if it succeeded.

GC_toggleref_func

The callback is to decide (return) the new state of a given object. Invoked by the collector for all objects registered for “toggle-refs” processing. Invoked with the allocator lock held but the world is running.

GC_uintptr_t

GC_valid_ptr_print_proc_t

The functions called to report pointer checking errors. Called without the allocator lock held. The default behavior is to fail with the appropriate message which includes the pointers. The functions (variables) must not be 0. Both the setters and the getters are unsynchronized.

GC_warn_proc

GC_set_warn_proc can be used to redirect or filter warning messages. p may not be a NULL pointer. msg is a printf format string (arg must match the format). Both the setter and the getter acquire the allocator lock (in the reader mode in case of the getter) to avoid data race. In GC v7.1 and before: the setter returned the value of old warn_proc. In GC v8.2.x and before: msg pointer type had no const qualifier.

GC_word

Define public word and signed_word to be unsigned and signed types of the size same as of size_t, ptrdiff_t, and of the address part of data pointers (like char * and void *).

pthread_t

sigset_t

Unions

pthread_attr_t