The collector uses a large amount of conditional compilation in order to deal with platform dependencies. This violates a number of known coding standards. On the other hand, it seems to be the only practical way to support this many platforms without excessive code duplication.
A few guidelines have mostly been followed in order to keep this manageable:
1. #if and #ifdef directives are properly indented whenever easily
possible. All known C compilers allow whitespace between the "#" and the
if to make this possible. ANSI C also allows white space before the
"#", though we avoid that. It has the known disadvantages that it
differs from the normal GNU conventions, and that it makes patches larger
than otherwise necessary. It is still well worth it, for the same reason
that we indent ordinary if statements.
2. Whenever possible, tests are performed on the macros defined in
gcconfig.h file instead of directly testing platform-specific
predefined macros. This makes it relatively easy to adapt to new
compilers with a different set of predefined macros. Currently these
macros generally identify platforms instead of features. In many cases,
this is a mistake.
Many of the tested configuration macros are at least somewhat defined in
either include/config.h.in or in Makefile.direct. Below is an attempt at
documenting these macros.
The following macros are tested by the public headers (gc.h file and
others). Some of them are also affecting the collector build.
GC_DEBUG - Tested by gc.h file (and by gc_cpp.cc file). Causes
all-upper-case macros to expand to calls to the debug variant of collector
routines.
GC_NAMESPACE - Tested by gc_cpp.h file. Causes gc_cpp symbols to be
defined in boehmgc namespace.
GC_NAMESPACE_ALLOCATOR - Tested by gc_allocator.h file. Causes
gc_allocator<T> and similar symbols to be defined in boehmgc namespace.
GC_DEBUG_REPLACEMENT - Tested by gc.h file. Causes
GC_MALLOC/GC_REALLOC to be defined as
GC_debug_malloc_replacement/GC_debug_realloc_replacement.
GC_NO_THREAD_REDIRECTS - Tested by gc.h file. Prevents redirection of
thread creation routines and friends to the GC_ variants. Requires the
client to explicitly handle thread registration.
GC_NO_THREAD_DECLS - Tested by gc.h file. Does not declare thread
creation (and related) routines and do not include platform windows.h file
from gc.h file.
GC_DONT_INCLUDE_WINDOWS_H - Tested by gc.h file. Windows only. Does not
include platform windows.h file from gc.h file (but Windows-specific
thread creation routines are declared).
GC_UNDERSCORE_STDCALL - Tested by gc.h file. Explicitly prefixes
exported/imported WINAPI (__stdcall) symbols with "_" (underscore). Could
be used with MinGW compiler targeting x86 (in conjunction with GC_DLL) to
follow MS conventions for __stdcall symbols naming.
_ENABLE_ARRAYNEW - Tested by gc_cpp.h. Predefined by the Digital Mars C++
compiler when operator new[] and delete[] are separately overloadable.
GC_NO_OPERATOR_NEW_ARRAY - Tested by gc_cpp.h file. Declares that the C++
compiler does not support the new syntax operator new[] for allocating and
deleting arrays. This is defined implicitly in a few environments.
GC_NO_INLINE_STD_NEW - Tested by gc_cpp.h file (and by gc_cpp.cc file).
Windows only. Defines the system-wide new and delete operators in
gccpp.dll file instead of providing an inline variant of the operators.
_DLL - Tested by gc.h. Defined by Visual C++ if runtime dynamic libraries
are in use. Used (only if none of GC_DLL, GC_NOT_DLL and __GNUC__ are
defined) to test whether __declspec(dllimport) needs to be added to
declarations to support the case in which the collector is in a DLL.
GC_DLL - Tested by cord.h, gc.h files. Defined by client if dynamic
libraries are being built or used. Also the macro is set in gc.h file if
_DLL is defined (except for MinGW) when GC_NOT_DLL and __GNUC__ are both
undefined. This is the macro that is tested internally to determine whether
the collector is in its own dynamic library. May need to be set by clients
before include gc.h file. Note that inside the collector implementation it
indicates primarily that the collector should export its symbols. But in
clients, it indicates that the collector resides in a different dynamic
(shared) library, its entry points should be referenced accordingly, and
precautions may need to be taken to properly deal with statically allocated
variables of the main program. Used for Windows, and also by GCC v4+ (only
when the dynamic shared library is being built) to hide internally used
symbols.
GC_NOT_DLL - Tested by gc.h and gc_cpp.h files. A client-settable macro
that overrides _DLL macro, e.g. if runtime dynamic libraries are used, but
the collector is in a static library.
GC_NO_VALLOC - Tested by gc.h and leak_detector.h files. Does not
provide GC_valloc and GC_pvalloc functions, and do not redirect the
corresponding glibc functions in leak_detector.h file.
GC_REQUIRE_WCSDUP - Tested by gc.h and leak_detector.h files (and by
dbg_mlc.c and mallocx.c files). Forces the collector to export
GC_wcsdup (the Unicode variant of GC_strdup); could be useful in the
find-leak mode. Clients should define it before including gc.h file if the
function is needed.
GC_THREADS - Tested by gc.h file. Enables support for native threads.
Must normally be defined by the client (before including gc.h file), thus
redefining thread primitives to invoke the GC_ wrappers instead.
GC_MARKERS=<n> - Tested by gc.h file. Sets the desired number of marker
threads. If not defined or defined to zero, then the collector decides based
on the number of total CPU cores. Has no effect unless the collector is built
with PARALLEL_MARK macro defined.
The following macros (-D arguments passed to the compiler) are tested only
in .c, .cpp files and private headers. Some of them provide the default
configuration values, others become hard-coded values for the library.
NO_FIND_LEAK - Excludes the support of the find-leak mode (for smaller code
size).
FIND_LEAK - Causes the collector to assume that all inaccessible objects
should have been explicitly deallocated, and reports exceptions.
Finalization and some of the test programs are not usable in this mode.
Actually, GC_set_find_leak(1) could be called, before the collector
initialization, to enter this mode. Should not be defined if NO_FIND_LEAK
is defined.
GC_FINDLEAK_DELAY_FREE - Turns on deferred freeing of objects in the
find-leak mode letting the collector to detect alter-object-after-free errors
as well as detect leaked objects sooner (instead of only when program
terminates). Should not be defined if NO_FIND_LEAK or SHORT_DBG_HDRS is
defined.
GC_ABORT_ON_LEAK - Causes the application to be terminated once leaked or
smashed (corrupted on use-after-free) objects are found (after printing the
information about that objects).
SUNOS5SIGS - Solaris-like signal handling. This is probably misnamed,
since it really does not guarantee much more than POSIX. Currently is set
only for DRSNX, FreeBSD, HP/UX and Solaris.
GC_WIN32_PTHREADS (Win32 only) - Enables support for pthreads-win32 (or
other non-Cygwin pthreads library for Windows). This should be specified
instead of (or in addition to) GC_THREADS, otherwise Win32 native threads
API will be used.
PTW32_STATIC_LIB - Causes the static variant of the MinGW pthreads library
to be used. Requires GC_WIN32_PTHREADS macro defined.
GC_PTHREADS_PARAMARK - Causes pthreads-based parallel mark implementation
to be used even if GC_WIN32_PTHREADS macro is undefined. (Useful for
WinCE.)
ALL_INTERIOR_POINTERS - Allows all pointers to the interior of objects to be
recognized. (See gc_priv.h file for the consequences.) Alternatively,
GC_all_interior_pointers variable can be set at runtime before the collector
initialization.
SMALL_CONFIG - Tries to tune the collector for small heap sizes,
usually causing it to use less space in such situations. Incremental
collection no longer works in this case. Also, removes some
statistic-printing code. Turns off some optimization algorithms (like data
prefetching in the mark routine).
NO_CLOCK - Disables system clock usage. Disables some statistic printing.
GC_DISABLE_INCREMENTAL - Turns off the incremental collection support.
NO_INCREMENTAL - Causes the collector test programs to not invoke the
incremental mode of the collector. This has no impact on the generated
library, only on the test programs. (This is often useful for debugging
failures unrelated to the incremental collection.)
LARGE_CONFIG - Tunes the collector for unusually large heaps.
Necessary for heaps larger than about 4 GB on most (64-bit) machines.
Recommended for heaps larger than about 0.5 GB. Not recommended for
embedded systems. Could be used in conjunction with SMALL_CONFIG macro to
generate smaller code (by disabling incremental collection support,
statistic printing and some optimization algorithms).
DONT_ADD_BYTE_AT_END - Meaningful only with ALL_INTERIOR_POINTERS macro
defined (or GC_all_interior_pointers variable set to one). Normally
ALL_INTERIOR_POINTERS macro causes all objects to be padded so that pointers
just past the end of an object can be recognized. This can be expensive.
(The padding is normally more than one byte due to alignment constraints.)
DONT_ADD_BYTE_AT_END macro disables the padding.
NO_EXECUTE_PERMISSION - May cause some or all of the heap to not
have execute permission, i.e. it may be impossible to execute
code from the heap. Affects the incremental collector and memory unmapping.
It may greatly improve the performance, since this may avoid some expensive
cache synchronization. Instead of relying on this macro, if the execute
permission is required, portable clients should call
GC_set_pages_executable(1) at runtime, before the collector initialization.
REDIRECT_MALLOC=<X> - Causes malloc() to be defined as alias for X.
Unless the following macros are defined, realloc() is also redirected
to GC_realloc(), and free() is redirected to GC_free(); calloc(),
strdup() and strndup() are redefined in terms of the new malloc.
X should be either GC_malloc or GC_malloc_uncollectable, or
GC_debug_malloc_replacement. (The latter invokes GC_debug_malloc
with dummy source location information, but still results in properly
remembered call stacks on Linux/i686, Linux/x86_64 and Solaris/SPARC.
It requires that REDIRECT_REALLOC and REDIRECT_FREE macros also be used.
The former is occasionally useful to workaround leaks in code
you do not want to (or cannot) look at. It may not work for
existing code, but it often does. Neither works on all platforms,
since some ports use malloc or calloc to obtain system memory. Probably
works for UNIX and Win32.) If you build the collector with DBG_HDRS_ALL
macro defined, you should only use GC_debug_malloc_replacement as a malloc
replacement.
REDIRECT_REALLOC=<X> - Causes realloc() to be redirected to X. The
canonical use is REDIRECT_REALLOC=GC_debug_realloc_replacement, together
with REDIRECT_MALLOC=GC_debug_malloc_replacement to generate leak reports
with call stacks for both malloc() and realloc(). This also requires
REDIRECT_FREE macro defined.
REDIRECT_FREE=<X> - Causes free() to be redirected to X. The canonical
use is REDIRECT_FREE=GC_debug_free.
IGNORE_FREE - Turns calls to free() into a no-op. Only useful with
REDIRECT_MALLOC macro defined.
NO_DEBUGGING - Prevents providing of GC_count_set_marks_in_hblk,
GC_dump, GC_dump_named, GC_dump_finalization, GC_dump_regions,
GC_print_free_list functions. Reduces code size slightly at the expense of
debuggability.
GC_DISABLE_SNPRINTF - Prevents snprintf() usage by the collector itself
(except for call-stack printing code, if supported). The formatting string
is printed by GC_printf (and friends) as is, ignoring the rest of the
arguments. This might be needed for environments where static linking with
the standard snprintf() is not desired for the matter of code size.
GC_DUMP_REGULARLY - Causes generation of regular debugging dumps.
DEBUG_THREADS - Turns on printing of additional thread-support debugging
information.
GC_COLLECT_AT_MALLOC=<n> - Forces garbage collection at every
GC_malloc_* call when the size argument greater than the specified value.
(Might be useful for application debugging or in the find-leak mode.)
JAVA_FINALIZATION - Makes it somewhat safer to finalize objects out of
order by specifying a non-standard finalization mark procedure (see
finalize.c). Objects reachable from finalizable objects will be marked
in a separate post-pass, and hence their memory will not be reclaimed.
Not recommended unless you are implementing a language that specifies
these semantics. Actually, the macro determines only the initial value
of GC_java_finalization variable.
FINALIZE_ON_DEMAND - Causes finalizers to be run only in response to
explicit GC_invoke_finalizers() calls. Actually, the macro only determines
the initial value of GC_finalize_on_demand variable.
GC_NO_FINALIZATION - Excludes finalization support (for smaller code size).
GC_TOGGLE_REFS_NOT_NEEDED - Excludes toggle-refs support (for smaller code
size). Has no effect if GC_NO_FINALIZATION macro is defined.
GC_ATOMIC_UNCOLLECTABLE - Includes code for
GC_malloc_atomic_uncollectable. This is useful if either the vendor
malloc implementation is poor, or if REDIRECT_MALLOC macro is defined.
MARK_BIT_PER_OBJ - Requests that a mark bit (or a byte) be allocated for
each object. By default, a mark bit/byte is allocated per a granule - this
often improves speed, possibly at some cost in space and/or cache footprint.
HBLKSIZE=<ddd> - Explicitly sets the heap block size (where ddd is a power
of two between 512 and 65536). Each heap block is devoted to a single size
and kind of object. For the incremental collector it makes sense to match
the most likely page size. Otherwise large values result in more
fragmentation, but generally better performance for large heaps.
USE_MMAP - Forces to use mmap() instead of sbrk() to get new memory from
the OS. Works for Linux, FreeBSD, Cygwin, Solaris and Irix, at least.
USE_MUNMAP - Causes memory to be returned to the OS under the right
circumstances. Unsupported on some platforms. Requires USE_MMAP macro
defined (except for Windows).
USE_WINALLOC (Cygwin only) - Causes Win32 VirtualAlloc() to be used
(instead of sbrk() and mmap()) to get new memory. Useful if memory
unmapping is enabled (by defining USE_MUNMAP macro).
MUNMAP_THRESHOLD=<n> - Sets the default threshold of memory blocks
unmapping (the number of sequential garbage collections during those
a candidate block for unmapping should be marked as free). The special
value "0" completely disables unmapping.
GC_FORCE_UNMAP_ON_GCOLLECT - Sets "unmap as much as possible on explicit GC"
mode on by default. The mode could be changed at run-time. Has no effect
unless memory unmapping is turned on. Has no effect on implicitly-initiated
garbage collections.
PRINT_BLACK_LIST - Whenever a black list entry is added, i.e. whenever
the garbage collector detects a value that looks almost, but not quite,
like a pointer, print both the address containing the value, and the
value of the near-bogus-pointer. Can be used to identify regions of
memory that are likely to contribute misidentified pointers.
KEEP_BACK_PTRS - Turns on saving back pointers in debugging headers
for objects allocated with the debugging allocator. If all objects are
allocated through GC_MALLOC() with GC_DEBUG defined, this allows the
client to determine how particular or randomly chosen objects are reachable
for debugging/profiling purposes. The gc_backptr.h file interface is
implemented only if this is defined.
GC_ASSERTIONS - Enables some internal assertion checking in the collector.
It is intended primarily for debugging of the garbage collector itself, but
could also help to identify cases of incorrect usage of the collector by
a client.
VALGRIND_TRACKING - Supports tracking of GC_malloc and friends for heap
profiling tools like Valgrind's massif and KDE heaptrack. Such tools work by
intercepting dynamically linked allocator calls so that they can do their own
bookkeeping for tracking memory usage. Actually, the macro turns on export
of GC_free_profiler_hook no-op function which could be intercepted by the
profiling tools (thus, they could see which objects were freed).
DBG_HDRS_ALL - Makes sure that all objects have debug headers. Increases
the reliability (from 99.9999% to 100% mod. bugs) of some of the debugging
code (especially when KEEP_BACK_PTRS is defined). Makes SHORT_DBG_HDRS
possible. Assumes that all client allocation is done through debugging
allocators.
SHORT_DBG_HDRS - Assumes that all objects have debug headers. Shorten
the headers to minimize object size, at the expense of checking for
writes past the end of an object. This is intended for environments
in which most client code is written in a "safe" language, such as
Scheme or Java. Assumes that all client allocation is done using
the GC_debug_ functions, or through the macros that expand to these,
or by redirecting malloc() to GC_debug_malloc_replacement().
(Also eliminates the field for the requested object size.) It could be
useful for debugging of client code. In combination with NO_FIND_LEAK
macro, this could also be used to reduce code size slightly. Slows down
the collector somewhat (if the GC_debug_ functions are used), but not
drastically.
SAVE_CALL_COUNT=<n> - Sets the number of call frames saved with objects
allocated through the debugging interface. Affects the amount of
information generated in leak reports. Only matters on platforms on which
we can quickly generate call stacks, currently Linux/i686, Linux/x86_64,
Linux/SPARC, Solaris/SPARC, and on platforms that provide execinfo.h.
Default is zero. On i686, client code should not be compiled with
-fomit-frame-pointer option.
SAVE_CALL_NARGS=<n> - Sets the number of function arguments to be saved
with each call frame. Default is zero. Ignored if we do not know how to
retrieve arguments on the platform.
CHECKSUMS - Reports on erroneously clear dirty bits (at a substantial
performance cost). Use only for debugging of the incremental collector.
Not compatible with USE_MUNMAP and not compatible with threads.
GC_GCJ_SUPPORT - Includes support for gcj (and possibly other systems
that include a pointer to a type descriptor in each allocated object).
USE_I686_PREFETCH - Causes the collector to issue Pentium III style
prefetch instructions. Has no effect except on Linux/i686 platforms.
Empirically the code appears to still run correctly on Pentium II
processors, though with no performance benefit. May not run on other
i686 processors probably. In some cases this improves performance by 15%
or so.
USE_3DNOW_PREFETCH - Causes the collector to issue AMD 3DNow style
prefetch instructions. Same restrictions as for USE_I686_PREFETCH.
Minimally tested. Did not appear to be an obvious win on a K6-2/500.
USE_PPC_PREFETCH - Causes the collector to issue PowerPC style
prefetch instructions. Has no effect except on Darwin/PowerPC platforms.
The performance impact is untested.
GC_USE_LD_WRAP - In combination with the old flags listed in
README.linux causes the collector to handle some
system and pthreads calls in a more transparent fashion than the usual
macro-based approach. Requires GNU ld, and currently probably works only
with Linux.
GC_USE_DLOPEN_WRAP - Causes the collector to redefine malloc and
intercepted pthreads routines with their real names, and causes it to use
dlopen() and dlsym() to refer to the original versions. This makes it
possible to build an LD_PRELOAD'able malloc replacement library.
USE_RWLOCK - Uses rwlock for the allocator lock instead of mutex.
Thus enable usage of the reader (shared) mode of the allocator lock where
possible.
THREAD_LOCAL_ALLOC - Defines GC_malloc(), GC_malloc_atomic() and
GC_gcj_malloc() to use a per-thread set of free lists. Then these functions
allocate in a way that usually does not involve acquisition of the allocator
(global) lock. Recommended for multiprocessors.
USE_COMPILER_TLS - Causes thread-local allocation to use
the compiler-supported __thread thread-local variables. This is the
default in HP/UX. It may help performance on recent Linux installations.
GC_ATTR_TLS_FAST - Uses specific attributes for GC_thread_key like
__attribute__((tls_model("local-exec"))).
PARALLEL_MARK - Allows the marker to run in multiple threads. Recommended
for multiprocessors.
GC_BUILTIN_ATOMIC - Uses GCC atomic intrinsics instead of libatomic_ops
primitives.
GC_ALWAYS_MULTITHREADED - Forces the multi-threaded mode right at the
collector initialization.
GC_ENABLE_SUSPEND_THREAD (Linux only) - Turns on thread suspend/resume API
support.
GC_REUSE_SIG_SUSPEND (Linux only) - Uses same signal number to suspend and
resume threads. Alternatively, the same effect could be achieved at
runtime by calling GC_set_suspend_signal(GC_get_thr_restart_signal())
before the collector initialization. However, use of same signal
might slightly increase the overall time of resuming threads on some
architectures (because of an extra context save when resuming a thread).
GC_WINMAIN_REDIRECT (Win32 only) - Redirects (renames) an application
WinMain to GC_WinMain; implements the "real" WinMain which starts a new
thread to call GC_WinMain() after the collector initialization. Useful for
WinCE. Incompatible with GC_DLL macro.
GC_INSIDE_DLL (Win32 only) - Enables DllMain-based approach of threads
registering even in case GC_DLL macro is not defined.
GC_REGISTER_MEM_PRIVATE (Win32 only) - Forces to register MEM_PRIVATE R/W
sections as data roots. Might be needed for some WinCE 6.0+ custom builds.
(May result in numerous "Data Abort" messages logged to WinCE debugging
console.) Incompatible with any known GCC toolchain for WinCE.
NO_GETENV - Prevents the collector from looking at environment variables.
These may otherwise alter its configuration, or turn off garbage collection
altogether. Possibly worth defining the macro if the resulting process runs
as a privileged user or to reduce code size. Defined implicitly for WinCE.
EMPTY_GETENV_RESULTS - Workarounds a reputed Wine bug in getenv
(getenv() may return an empty string instead of NULL for a missing entry).
GC_READ_ENV_FILE (Win32 only) - Reads environment variables from the
collector "env" file (named as the program name plus ".gc.env" extension).
Useful for WinCE (which has no getenv). In the file, every variable is
specified in a separate line and the format is as <name>=<value> (without
spaces). A comment line may start with any character except for the Latin
letters, the digits and the underscore ("_"). The file encoding is expected
to be "Latin-1".
USE_GLOBAL_ALLOC (Win32 only) - Instructs the collector to use
GlobalAlloc() instead of VirtualAlloc() to allocate the heap. May be
needed to workaround a Windows NT/2000 issue. Incompatible with USE_MUNMAP
macro. See README.win32 for details.
MAKE_BACK_GRAPH - Enables GC_PRINT_BACK_HEIGHT environment variable. See
environment.md for details. Experimental. Limited platform
support. Implies DBG_HDRS_ALL macro is defined. All allocation should be
done using the collector debug interface.
GC_PRINT_BACK_HEIGHT - Permanently turns on the back-height printing mode
(useful when NO_GETENV macro is defined). See the similar environment
variable description in environment.md. Requires
MAKE_BACK_GRAPH macro to be defined.
HANDLE_FORK (UNIX and Cygwin only) - Attempts by default to make
GC_malloc() work in a child process fork'ed from a multi-threaded parent.
Not fully POSIX-compliant and could be disabled at runtime (before GC_INIT()
call).
POINTER_MASK=<0x...> - Causes candidate pointers to be AND'ed with the given
mask before being considered. If either this or POINTER_SHIFT macro is
defined, it will be assumed that all pointers stored in the heap need to be
processed this way. Stack and register pointers will be considered both
with and without processing. These macros are normally needed only to
support systems that use high-order pointer tags. Has no effect if
DYNAMIC_POINTER_MASK macro is defined.
POINTER_SHIFT=<n> - Causes the collector to left-shift candidate pointers
by the indicated amount (n) before trying to interpret them. Applied after
POINTER_MASK; see also the description of the latter macro.
DYNAMIC_POINTER_MASK - Allows to set pointer mask and shift at runtime,
typically before GC_INIT() call. Overrides (undefines) POINTER_MASK and
POINTER_SHIFT macros (i.e. the default mask and shift are assumed to be
zeros regardless of the latter two macros).
ENABLE_TRACE - Enables the GC_TRACE=<addr> environment setting to do its
job. By default this is not supported in order to keep the marker as fast as
possible.
DARWIN_DONT_PARSE_STACK - Causes the Darwin port to discover thread
stack bounds in the same way as other pthreads ports, without trying to
walk the frames on the stack. This is recommended only as a fall-back for
applications that do not support proper stack unwinding.
GC_NO_THREADS_DISCOVERY (Darwin and Win32+DLL only) - Excludes DllMain-based
(on Windows) and task-threads-based (on Darwin) thread registration support.
GC_DISCOVER_TASK_THREADS (Darwin and Win32+DLL only) - Forces to compile
the collector with the implicitly turned on task-threads-based (on Darwin) or
DllMain-based (on Windows) approach of threads registering. Only for
compatibility and for the case when it is not possible to call
GC_use_threads_discovery() early (before other garbage collector calls).
USE_PROC_FOR_LIBRARIES - Causes the Linux collector to treat writable
memory mappings (as reported by /proc) as roots, if it does not have
other information about them. It no longer traverses dynamic loader
data structures to find dynamic library static data. This may be
required for applications that store pointers in mmap'ed segments without
informing the collector. But it typically performs poorly, especially
since it will scan inactive but cached NPTL thread stacks completely.
IGNORE_DYNAMIC_LOADING - Prevents DYNAMIC_LOADING macro definition even if
the feature is supported by the platform (that is, build the collector with
disabled tracing of dynamic library data roots, probably for smaller code
size).
NO_PROC_STAT - Causes the collector to avoid relying on Linux
/proc/self/stat.
NO_GETCONTEXT - Causes the collector to not assume the existence of the
getcontext() on Linux-like platforms. This currently happens implicitly on
ARM, MIPS and some other architectures, as well as on some operating systems
like Android, Hurd, OpenBSD, OS X, etc. It is explicitly needed for some old
versions of FreeBSD.
STATIC=static - Causes various GC_ symbols that are local to a compilation
unit of the collector to be declared as static (this is the default if
NO_DEBUGGING macro is defined). Reduces the number of visible symbols
(letting the optimizer do its work better), which is probably cleaner, but may
make some kinds of debugging and profiling harder.
GC_DLL - Tunes to build dynamic-link library (or dynamic shared object).
For UNIX this causes the exported symbols to have default visibility
(ignored unless GCC v4+) and the internal ones to have hidden visibility.
NO_MSGBOX_ON_ERROR (Win32 only) - Prevents showing Windows message box with
"OK" button on a collector fatal error. Otherwise the client application is
terminated only once the user clicks "OK" button. Useful for non-GUI (or
non-interactive) applications.
DONT_USE_USER32_DLL (Win32 only) - Forces not to use user32 DLL import
library (containing MessageBox() entry).
GC_PREFER_MPROTECT_VDB - Causes MPROTECT_VDB to be chosen in case of
multiple virtual dirty bit strategies are implemented (at present useful on
Win32, Solaris and Linux to force MPROTECT_VDB strategy instead of the
default GWW_VDB, PROC_VDB or SOFT_VDB ones, respectively).
DONT_PROTECT_PTRFREE - Prevents mixing heap blocks with and without pointers
in a page, thus avoid protecting pointer-free pages (at the expense of
potentially bigger heap size). Has no effect unless MPROTECT_VDB is defined
and the page is larger than the heap block.
CHECK_SOFT_VDB - Turns on both MPROTECT_VDB and SOFT_VDB virtual dirty
bit strategies to check whether they are consistent. Use only for debugging
of the incremental collector.
NO_MANUAL_VDB - Turns off support of the manual VDB (virtual dirty bits)
mode.
GC_IGNORE_GCJ_INFO - Disables gcj-style type information. This might be
useful for client debugging on WinCE (which has no getenv).
GC_PRINT_VERBOSE_STATS - Permanently turns on verbose logging (useful for
debugging and profiling on WinCE).
GC_ONLY_LOG_TO_FILE - Prevents GC_stdout and GC_stderr redirection to
the collector log file specified by GC_LOG_FILE environment variable. Has
no effect unless the variable is set (to anything other than "0").
GC_ANDROID_LOG (Android only) - Forces the collector to output error/debug
information to Android log.
CONSOLE_LOG (Win32 only) - Forces the collector to output error/debug
information to stdout and stderr.
GC_DONT_EXPAND - Prevents expanding the heap unless explicitly requested or
forced to.
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 garbage collection cycle. It is likely to result in a larger working
set, but lower collection frequencies, and hence fewer instructions executed
in the collector. Actually, the macro determines only the initial value
of GC_use_entire_heap variable.
GC_INITIAL_HEAP_SIZE=<value> - Sets the desired default initial heap size,
in bytes.
GC_FREE_SPACE_DIVISOR=<value> - Sets the alternate default value of
GC_free_space_divisor variable.
GC_ALLOCD_BYTES_PER_FINALIZER=<value> - Sets the alternate default value of
GC_allocd_bytes_per_finalizer variable.
GC_TIME_LIMIT=<milliseconds> - Sets the alternate default value of
GC_time_limit variable (setting this to GC_TIME_UNLIMITED will essentially
disable incremental collection while leaving generational collection
enabled).
GC_FULL_FREQ=<n> - Sets the alternate default number of partial collections
between full collections (matters only if the incremental collection mode
is on).
NO_CANCEL_SAFE (POSIX platforms with threads only) - Stops bothering about
making the collector safe for thread cancellation. Assuming cancellation is
not used by client. (If cancellation is used anyway, threads may end up
getting canceled in unexpected places.) Even without this option,
PTHREAD_CANCEL_ASYNCHRONOUS is never safe with the collector. (We could
argue about its safety without the collector.)
UNICODE (Win32 only) - Forces to use the Unicode variant (with suffix "W")
of the Win32 API instead of ANSI/ASCII one (with suffix "A"). Useful for
WinCE.
HOST_ANDROID (or __ANDROID__) - Targets compilation for Android NDK
platform.
SN_TARGET_PS3 - Targets compilation for Sony PS/3.
USE_GET_STACKBASE_FOR_MAIN (Linux only) - Forces to use
pthread_attr_getstack() instead of __libc_stack_end (or instead of any
hard-coded value) for getting the primordial thread stack bottom (useful if
the client modifies the program's address space).
EMSCRIPTEN_ASYNCIFY (Emscripten only) - Forces to use Asyncify feature.
Note this is a relatively rarely used feature of Emscripten, as most
developers do not use it, and it does not scale well to moderate-to-large
code bases. But the feature is needed to pass gctest, at least. Requires
-sASYNCIFY linker flag.