src/mm/boehm-gc/doc/README.macros

   1 The collector uses a large amount of conditional compilation in order to
   2 deal with platform dependencies.  This violates a number of known coding
   3 standards.  On the other hand, it seems to be the only practical way to
   4 support this many platforms without excessive code duplication.
   5
   6 A few guidelines have mostly been followed in order to keep this manageable:
   7
   8 1) #if and #ifdef directives are properly indented whenever easily possible.
   9 All known C compilers allow whitespace between the "#" and the "if" to make
  10 this possible.  ANSI C also allows white space before the "#", though we
  11 avoid that.  It has the known disadvantages that it differs from the normal
  12 GNU conventions, and that it makes patches larger than otherwise necessary.
  13 In my opinion, it's still well worth it, for the same reason that we indent
  14 ordinary "if" statements.
  15
  16 2) Whenever possible, tests are performed on the macros defined in gcconfig.h
  17 instead of directly testing platform-specific predefined macros.  This makes
  18 it relatively easy to adapt to new compilers with a different set of
  19 predefined macros.  Currently these macros generally identify platforms
  20 instead of features.  In many cases, this is a mistake.
  21
  22 Many of the tested configuration macros are at least somewhat defined in
  23 either include/private/gcconfig.h or in Makefile.direct.  Here is an attempt
  24 at documenting these macros:  (Thanks to Walter Bright for suggesting
  25 this.  This is a work in progress)
  26
  27 MACRO           EXPLANATION
  28 -----           -----------
  29
  30 GC_DEBUG        Tested by gc.h.  Causes all-upper-case macros to
  31                 expand to calls to debug versions of collector routines.
  32
  33 GC_NO_THREAD_REDIRECTS  Tested by gc.h.  Prevents redirection of thread
  34                 creation routines etc. to GC_ versions.  Requires the
  35                 programmer to explicitly handle thread registration.
  36
  37 GC_NO_THREAD_DECLS      Tested by gc.h.  MS Windows only.  Do not declare
  38                 Windows thread creation routines and do not include windows.h.
  39
  40 GC_UNDERSCORE_STDCALL   Tested by gc.h.  Explicitly prefix exported/imported
  41                 WINAPI (__stdcall) symbols with '_' (underscore).  Could be
  42                 used with MinGW (for x86) compiler (in conjunction with
  43                 GC_DLL) to follow MS conventions for __stdcall symbols naming.
  44
  45 _ENABLE_ARRAYNEW
  46                 #define'd by the Digital Mars C++ compiler when
  47                 operator new[] and delete[] are separately
  48                 overloadable. Used in gc_cpp.h.
  49
  50 _DLL            Tested by gc_config_macros.h. Defined by Visual C++ if runtime
  51                 dynamic libraries are in use.  Used (only if none of GC_DLL,
  52                 GC_NOT_DLL, __GNUC__ are defined) to test whether
  53                 __declspec(dllimport) needs to be added to declarations
  54                 to support the case in which the collector is in a DLL.
  55
  56 GC_DLL          Defined by user if dynamic libraries are being built
  57                 or used.  Also set by gc.h if _DLL is defined (except for
  58                 mingw) while GC_NOT_DLL and __GNUC__ are both undefined.
  59                 This is the macro that is tested internally to determine
  60                 whether the GC is in its own dynamic library.  May need
  61                 to be set by clients before including gc.h.  Note that
  62                 inside the GC implementation it indicates that the
  63                 collector is in its own dynamic library, should export
  64                 its symbols, etc.  But in clients it indicates that the
  65                 GC resides in a different DLL, its entry points should
  66                 be referenced accordingly, and precautions may need to
  67                 be taken to properly deal with statically allocated
  68                 variables in the main program.  Used for MS Windows.
  69                 Also used by GCC v4+ (only when the dynamic shared library
  70                 is being built) to hide internally used symbols.
  71
  72 GC_NOT_DLL      User-settable macro that overrides _DLL, e.g. if runtime
  73                 dynamic libraries are used, but the collector is in a static
  74                 library.  Tested by gc_config_macros.h.
  75
  76
  77 These define arguments influence the collector configuration:
  78 FIND_LEAK causes GC_find_leak to be initially set.
  79   This causes the collector to assume that all inaccessible
  80   objects should have been explicitly deallocated, and reports exceptions.
  81   Finalization and the test program are not usable in this mode.
  82
  83 SUNOS5SIGS      Solaris-like signal handling.  This is probably misnamed,
  84                 since it really doesn't guarantee much more than Posix.
  85                 Currently set only for Solaris2.X, HPUX, and DRSNX.  Should
  86                 probably be set for some other platforms.
  87
  88 PCR             Set if the collector is being built as part of the Xerox
  89                 Portable Common Runtime.
  90
  91 USE_COMPILER_TLS  Assume the existence of __thread-style thread-local
  92                 storage.  Set automatically for thread-local allocation with
  93                 the HP/UX vendor compiler.  Usable with gcc on sufficiently
  94                 up-to-date ELF platforms.
  95
  96 IMPORTANT: Any of the _THREADS options must normally also be defined in
  97   the client before including gc.h.  This redefines thread primitives to
  98   invoke the GC_ versions instead.  Alternatively, linker-based symbol
  99   interception can be used on a few platforms.
 100
 101 GC_THREADS      Should set the appropriate one of the below macros,
 102   except GC_WIN32_PTHREADS, which must be set explicitly.  Tested by gc.h.
 103
 104 GC_SOLARIS_THREADS      Enables support for Solaris pthreads.
 105   Must also define _REENTRANT.
 106
 107 GC_IRIX_THREADS         Enables support for Irix pthreads.  See README.sgi.
 108
 109 GC_HPUX_THREADS         Enables support for HP/UX 11 pthreads.
 110   Also requires _REENTRANT or _POSIX_C_SOURCE=199506L. See README.hp.
 111
 112 GC_LINUX_THREADS        Enables support for Xavier Leroy's Linux threads
 113   or NPTL threads. See README.linux.  _REENTRANT may also be required.
 114
 115 GC_OSF1_THREADS         Enables support for Tru64 pthreads.
 116
 117 GC_FREEBSD_THREADS      Enables support for FreeBSD pthreads.
 118   Appeared to run into some underlying thread problems.
 119
 120 GC_NETBSD_THREADS       Enables support for NetBSD pthreads.
 121
 122 GC_OPENBSD_THREADS      Enables support for OpenBSD pthreads.
 123
 124 GC_DARWIN_THREADS       Enables support for Mac OS X pthreads.
 125
 126 GC_AIX_THREADS  Enables support for IBM AIX threads.
 127
 128 GC_DGUX386_THREADS      Enables support for DB/UX on I386 threads.
 129   See README.DGUX386.  (Probably has not been tested recently.)
 130
 131 GC_WIN32_THREADS        Enables support for win32 threads.  That makes sense
 132   for this Makefile only under Cygwin.
 133
 134 GC_WIN32_PTHREADS       Enables support for Ming32 pthreads.  This cannot be
 135   enabled automatically by GC_THREADS, which would assume Win32 native
 136   threads.
 137
 138 PTW32_STATIC_LIB        Causes the static version of the Mingw pthreads
 139   library to be used.  Requires GC_WIN32_PTHREADS.
 140
 141 GC_PTHREADS_PARAMARK    Causes pthread-based parallel mark implementation
 142   to be used even if GC_WIN32_PTHREADS is undefined.  (Useful for WinCE.)
 143
 144 ALL_INTERIOR_POINTERS   Allows all pointers to the interior of objects to be
 145   recognized.  (See gc_priv.h for consequences.)  Alternatively,
 146   GC_all_interior_pointers can be set at process initialization time.
 147
 148 SMALL_CONFIG    Tries to tune the collector for small heap sizes,
 149   usually causing it to use less space in such situations.
 150   Incremental collection no longer works in this case.
 151
 152 GC_DISABLE_INCREMENTAL  Turn off the incremental collection support.
 153
 154 NO_INCREMENTAL  Causes the gctest program to not invoke the incremental
 155   collector.  This has no impact on the generated library, only on the test
 156   program.  (This is often useful for debugging failures unrelated to
 157   incremental GC.)
 158
 159 LARGE_CONFIG    Tunes the collector for unusually large heaps.
 160   Necessary for heaps larger than about 4 GiB on most (64-bit) machines.
 161   Recommended for heaps larger than about 500 MiB.  Not recommended for
 162   embedded systems.
 163
 164 DONT_ADD_BYTE_AT_END    Meaningful only with ALL_INTERIOR_POINTERS or
 165   GC_all_interior_pointers = 1.  Normally ALL_INTERIOR_POINTERS
 166   causes all objects to be padded so that pointers just past the end of
 167   an object can be recognized.  This can be expensive.  (The padding
 168   is normally more than one byte due to alignment constraints.)
 169   DONT_ADD_BYTE_AT_END disables the padding.
 170
 171 NO_EXECUTE_PERMISSION   May cause some or all of the heap to not
 172   have execute permission, i.e. it may be impossible to execute
 173   code from the heap.  Currently this only affects the incremental
 174   collector on UNIX machines.  It may greatly improve its performance,
 175   since this may avoid some expensive cache synchronization.
 176
 177 GC_NO_OPERATOR_NEW_ARRAY        Declares that the C++ compiler does not
 178   support the  new syntax "operator new[]" for allocating and deleting arrays.
 179   See gc_cpp.h for details.  No effect on the C part of the collector.
 180   This is defined implicitly in a few environments.  Must also be defined
 181   by clients that use gc_cpp.h.
 182
 183 REDIRECT_MALLOC=<X>     Causes malloc to be defined as alias for X.
 184   Unless the following macros are defined, realloc is also redirected
 185   to GC_realloc, and free is redirected to GC_free.
 186   Calloc and strdup are redefined in terms of the new malloc.  X should
 187   be either GC_malloc or GC_malloc_uncollectable, or
 188   GC_debug_malloc_replacement.  (The latter invokes GC_debug_malloc
 189   with dummy source location information, but still results in
 190   properly remembered call stacks on Linux/X86 and Solaris/SPARC.
 191   It requires that the following two macros also be used.)
 192   The former is occasionally useful for working around leaks in code
 193   you don't want to (or can't) look at.  It may not work for
 194   existing code, but it often does.  Neither works on all platforms,
 195   since some ports use malloc or calloc to obtain system memory.
 196   (Probably works for UNIX, and win32.)  If you build with DBG_HDRS_ALL,
 197   you should only use GC_debug_malloc_replacement as a malloc
 198   replacement.
 199
 200 REDIRECT_REALLOC=<X>    Causes GC_realloc to be redirected to X.
 201   The canonical use is REDIRECT_REALLOC=GC_debug_realloc_replacement,
 202   together with REDIRECT_MALLOC=GC_debug_malloc_replacement to
 203   generate leak reports with call stacks for both malloc and realloc.
 204   This also requires REDIRECT_FREE.
 205
 206 REDIRECT_FREE=<X>       Causes free to be redirected to X.  The canonical use
 207   is REDIRECT_FREE=GC_debug_free.
 208
 209 IGNORE_FREE     Turns calls to free into a no-op.  Only useful with
 210   REDIRECT_MALLOC.
 211
 212 NO_DEBUGGING    Removes GC_dump and the debugging routines it calls.
 213   Reduces code size slightly at the expense of debuggability.
 214
 215 DEBUG_THREADS   Turn on printing additional thread-support debugging
 216   information.
 217
 218 JAVA_FINALIZATION       Makes it somewhat safer to finalize objects out of
 219   order by specifying a nonstandard finalization mark procedure  (see
 220   finalize.c).  Objects reachable from finalizable objects will be marked
 221   in a separate post-pass, and hence their memory won't be reclaimed.
 222   Not recommended unless you are implementing a language that specifies
 223   these semantics.  Since 5.0, determines only the initial value
 224   of GC_java_finalization variable.
 225
 226 FINALIZE_ON_DEMAND      Causes finalizers to be run only in response
 227   to explicit GC_invoke_finalizers() calls.
 228   In 5.0 this became runtime adjustable, and this only determines the
 229   initial value of GC_finalize_on_demand.
 230
 231 ATOMIC_UNCOLLECTABLE    Includes code for GC_malloc_atomic_uncollectable.
 232   This is useful if either the vendor malloc implementation is poor,
 233   or if REDIRECT_MALLOC is used.
 234
 235 MARK_BIT_PER_GRANULE    Requests that a mark bit (or often byte)
 236   be allocated for each allocation granule, as opposed to each object.
 237   This often improves speed, possibly at some cost in space and/or
 238   cache footprint.  Normally it is best to let this decision be
 239   made automatically depending on platform.
 240
 241 MARK_BIT_PER_OBJ        Requests that a mark bit be allocated for each
 242   object instead of allocation granule.  The opposite of
 243   MARK_BIT_PER_GRANULE.
 244
 245 HBLKSIZE=<ddd>  Explicitly sets the heap block size (where ddd is a power of
 246   2 between 512 and 16384).  Each heap block is devoted to a single size and
 247   kind of object.  For the incremental collector it makes sense to match
 248   the most likely page size.  Otherwise large values result in more
 249   fragmentation, but generally better performance for large heaps.
 250
 251 USE_MMAP        Use MMAP instead of sbrk to get new memory.
 252   Works for Linux, FreeBSD, Cygwin, Solaris and Irix.
 253
 254 USE_MUNMAP      Causes memory to be returned to the OS under the right
 255   circumstances.  This currently disables VM-based incremental collection
 256   (except for Win32 with GetWriteWatch() available).
 257   Works under some Unix, Linux and Windows versions.
 258   Requires USE_MMAP except for Windows.
 259
 260 MUNMAP_THRESHOLD=<value>        Set the desired memory blocks unmapping
 261   threshold (the number of sequential garbage collections for which
 262   a candidate block for unmapping should remain free).
 263
 264 GC_FORCE_UNMAP_ON_GCOLLECT      Set "unmap as much as possible on explicit GC"
 265   mode on by default.  The mode could be changed at run-time.  Has no effect
 266   unless unmapping is turned on.  Has no effect on implicitly-initiated
 267   garbage collections.
 268
 269 MMAP_STACKS (for Solaris threads)       Use mmap from /dev/zero rather than
 270   GC_scratch_alloc() to get stack memory.
 271
 272 PRINT_BLACK_LIST        Whenever a black list entry is added, i.e. whenever
 273   the garbage collector detects a value that looks almost, but not quite,
 274   like a pointer, print both the address containing the value, and the
 275   value of the near-bogus-pointer.  Can be used to identify regions of
 276   memory that are likely to contribute misidentified pointers.
 277
 278 KEEP_BACK_PTRS  Add code to save back pointers in debugging headers
 279   for objects allocated with the debugging allocator.  If all objects
 280   through GC_MALLOC with GC_DEBUG defined, this allows the client
 281   to determine how particular or randomly chosen objects are reachable
 282   for debugging/profiling purposes.  The gc_backptr.h interface is
 283   implemented only if this is defined.
 284
 285 GC_ASSERTIONS   Enable some internal GC assertion checking.  Currently
 286   this facility is only used in a few places.  It is intended primarily
 287   for debugging of the garbage collector itself, but could also...
 288
 289 DBG_HDRS_ALL    Make sure that all objects have debug headers.  Increases
 290   the reliability (from 99.9999% to 100% mod. bugs) of some of the debugging
 291   code (especially KEEP_BACK_PTRS).  Makes SHORT_DBG_HDRS possible.
 292   Assumes that all client allocation is done through debugging allocators.
 293
 294 SHORT_DBG_HDRS  Assume that all objects have debug headers.  Shorten
 295   the headers to minimize object size, at the expense of checking for
 296   writes past the end of an object.  This is intended for environments
 297   in which most client code is written in a "safe" language, such as
 298   Scheme or Java.  Assumes that all client allocation is done using
 299   the GC_debug_ functions, or through the macros that expand to these,
 300   or by redirecting malloc to GC_debug_malloc_replacement.
 301   (Also eliminates the field for the requested object size.)
 302   Occasionally could be useful for debugging of client code.  Slows down the
 303   collector somewhat, but not drastically.
 304
 305 SAVE_CALL_COUNT=<n>     Set the number of call frames saved with objects
 306   allocated through the debugging interface.  Affects the amount of
 307   information generated in leak reports.  Only matters on platforms
 308   on which we can quickly generate call stacks, currently Linux/(X86 & SPARC)
 309   and Solaris/SPARC and platforms that provide execinfo.h.
 310   Default is zero.  On X86, client
 311   code should NOT be compiled with -fomit-frame-pointer.
 312
 313 SAVE_CALL_NARGS=<n>     Set the number of functions arguments to be saved
 314   with each call frame.  Default is zero.  Ignored if we don't know how to
 315   retrieve arguments on the platform.
 316
 317 CHECKSUMS       Reports on erroneously clear dirty bits, and unexpectedly
 318   altered stubborn objects, at substantial performance cost.  Use only for
 319   debugging of the incremental collector.  Not compatible with USE_MUNMAP
 320   or threads.
 321
 322 GC_GCJ_SUPPORT  Includes support for gcj (and possibly other systems
 323   that include a pointer to a type descriptor in each allocated object).
 324   Building this way requires an ANSI C compiler.
 325
 326 USE_I686_PREFETCH       Causes the collector to issue Pentium III style
 327   prefetch instructions.  No effect except on X86 Linux platforms.
 328   Assumes a very recent gcc-compatible compiler and assembler.
 329   (Gas prefetcht0 support was added around May 1999.)
 330   Empirically the code appears to still run correctly on Pentium II
 331   processors, though with no performance benefit.  May not run on other
 332   X86 processors?  In some cases this improves performance by
 333   15% or so.
 334
 335 USE_3DNOW_PREFETCH      Causes the collector to issue AMD 3DNow style
 336   prefetch instructions.  Same restrictions as USE_I686_PREFETCH.
 337   Minimally tested.  Didn't appear to be an obvious win on a K6-2/500.
 338
 339 USE_PPC_PREFETCH        Causes the collector to issue PowerPC style
 340   prefetch instructions.  No effect except on PowerPC OS X platforms.
 341   Performance impact untested.
 342
 343 GC_USE_LD_WRAP  In combination with the old flags listed in README.linux
 344   causes the collector some system and pthread calls in a more transparent
 345   fashion than the usual macro-based approach.  Requires GNU ld, and
 346   currently probably works only with Linux.
 347
 348 GC_USE_DLOPEN_WRAP      Causes the collector to redefine malloc and
 349   intercepted pthread routines with their real names, and causes it to use
 350   dlopen and dlsym to refer to the original versions.  This makes it possible
 351   to build an LD_PRELOADable malloc replacement library.
 352
 353 THREAD_LOCAL_ALLOC      Defines GC_malloc(), GC_malloc_atomic() and
 354   GC_gcj_malloc() to use a per-thread set of free-lists. These then allocate
 355   in a way that usually does not involve acquisition of a global lock.
 356   Recommended for multiprocessors.  Requires explicit GC_INIT() call, unless
 357   REDIRECT_MALLOC is defined and GC_malloc is used first.
 358
 359 USE_COMPILER_TLS        Causes thread local allocation to use
 360   the compiler-supported "__thread" thread-local variables.  This is the
 361   default in HP/UX.  It may help performance on recent Linux installations.
 362   (It failed for me on RedHat 8, but appears to work on RedHat 9.)
 363
 364 PARALLEL_MARK   Allows the marker to run in multiple threads.  Recommended
 365   for multiprocessors.
 366
 367 DONT_USE_SIGNALANDWAIT (Win32 only)     Use an alternate implementation for
 368   marker threads (if PARALLEL_MARK defined) synchronization routines based
 369   on InterlockedExchange() (instead of AO_fetch_and_add()) and on multiple
 370   event objects (one per each marker instead of that based on Win32
 371   SignalObjectAndWait() using a single event object).  This is the default
 372   for WinCE.
 373
 374 GC_WINMAIN_REDIRECT (Win32 only)        Redirect (rename) an application
 375   WinMain to GC_WinMain; implement the "real" WinMain which starts a new
 376   thread to call GC_WinMain after initializing the GC.  Useful for WinCE.
 377   Incompatible with GC_DLL.
 378
 379 GC_REGISTER_MEM_PRIVATE (Win32 only)    Force to register MEM_PRIVATE R/W
 380   sections as data roots.  Might be needed for some WinCE 6.0+ custom builds.
 381   (May result in numerous "Data Abort" messages logged to WinCE debugging
 382   console.)  Incompatible with GCC toolchains for WinCE.
 383
 384 NO_GETENV       Prevents the collector from looking at environment variables.
 385   These may otherwise alter its configuration, or turn off GC altogether.
 386   I don't know of a reason to disable this, except possibly if the resulting
 387   process runs as a privileged user.  (This is on by default for WinCE.)
 388
 389 EMPTY_GETENV_RESULTS    Define to workaround a reputed Wine bug in getenv
 390   (getenv() may return an empty string instead of NULL for a missing entry).
 391
 392 USE_GLOBAL_ALLOC (Win32 only)   Use GlobalAlloc() instead of VirtualAlloc()
 393   to allocate the heap.  May be needed to work around a Windows NT/2000 issue.
 394   Incompatible with USE_MUNMAP.  See README.win32 for details.
 395
 396 MAKE_BACK_GRAPH         Enable GC_PRINT_BACK_HEIGHT environment variable.
 397   See README.environment for details.  Experimental. Limited platform
 398   support.  Implies DBG_HDRS_ALL.  All allocation should be done using
 399   the debug interface.
 400
 401 STUBBORN_ALLOC  Allows allocation of "hard to change" objects, and thus
 402   makes incremental collection easier.  Was enabled by default until 6.0.
 403   Rarely used, to my knowledge.
 404
 405 HANDLE_FORK     Attempts to make GC_malloc() work in a child process fork()'ed
 406   from a multithreaded parent.  Currently only supported by pthread_support.c.
 407   (Similar code should work on Solaris or Irix, but it hasn't been tried.)
 408
 409 TEST_WITH_SYSTEM_MALLOC         Causes gctest to allocate (and leak) large
 410   chunks of memory with the standard system malloc.  This will cause the root
 411   set and collected heap to grow significantly if malloc'ed memory is somehow
 412   getting traced by the collector.  This has no impact on the generated
 413   library; it only affects the test.
 414
 415 POINTER_MASK=<0x...>    Causes candidate pointers to be AND'ed with the given
 416   mask before being considered.  If either this or the following macro is
 417   defined, it will be assumed that all pointers stored in the heap need to be
 418   processed this way.  Stack and register pointers will be considered both
 419   with and without processing.  These macros are normally needed only to
 420   support systems that use high-order pointer tags.  EXPERIMENTAL.
 421
 422 POINTER_SHIFT=<n>       Causes the collector to left shift candidate pointers
 423   by the indicated amount before trying to interpret them.  Applied after
 424   POINTER_MASK. EXPERIMENTAL.  See also the preceding macro.
 425
 426 ENABLE_TRACE    Enables the GC_TRACE=addr environment setting to do its job.
 427   By default this is not supported in order to keep the marker as fast as
 428   possible.
 429
 430 DARWIN_DONT_PARSE_STACK         Causes the Darwin port to discover thread
 431   stack bounds in the same way as other pthread ports, without trying to
 432   walk the frames onthe stack.  This is recommended only as a fallback for
 433   applications that don't support proper stack unwinding.
 434
 435 USE_PROC_FOR_LIBRARIES  Causes the Linux collector to treat writable
 436   memory mappings (as reported by /proc) as roots, if it doesn't have
 437   other information about them.  It no longer traverses dynamic loader
 438   data structures to find dynamic library static data.  This may be
 439   required for applications that store pointers in mmapped segments without
 440   informing the collector.  But it typically performs poorly, especially
 441   since it will scan inactive but cached NPTL thread stacks completely.
 442
 443 NO_PROC_STAT    Causes the collector to avoid relying on Linux
 444   "/proc/self/stat".
 445
 446 NO_GETCONTEXT   Causes the collector to not assume the existence of the
 447   getcontext() function on linux-like platforms.  This currently happens
 448   implicitly on Darwin, Hurd, or ARM or MIPS hardware.  It is explicitly
 449   needed for some old versions of FreeBSD.
 450
 451 STATIC=static   Causes various GC_ symbols that could logically be declared
 452   static to be declared (this is the default if NO_DEBUGGING is specified).
 453   Reduces the number of visible symbols (letting the optimizer do its work
 454   better), which is probably cleaner, but may make some kinds of debugging
 455   and profiling harder.
 456
 457 GC_DLL  Build dynamic-link library (or dynamic shared object).  For Unix this
 458   causes the exported symbols to have 'default' visibility (ignored unless
 459   GCC v4+) and the internal ones to have 'hidden' visibility.
 460
 461 DONT_USE_USER32_DLL (Win32 only)        Don't use "user32" DLL import library
 462   (containing MessageBox() entry); useful for a static GC library.
 463
 464 GC_PREFER_MPROTECT_VDB  Choose MPROTECT_VDB manually in case of multiple
 465   virtual dirty bit strategies are implemented (at present useful on Win32
 466   to force MPROTECT_VDB strategy instead of the default GWW_VDB one).
 467
 468 GC_NO_DLLMAIN (Win32+DLL only)  Exclude DllMain-based thread registration
 469   support.
 470
 471 GC_IGNORE_GCJ_INFO      Disable GCJ-style type information (useful for
 472   debugging on WinCE).
 473
 474 GC_PRINT_VERBOSE_STATS  Permanently turn on verbose logging (useful for
 475   debugging and profiling on WinCE).
 476
 477 GC_DONT_EXPAND  Don't expand the heap unless explicitly requested or forced to.
 478
 479 GC_INITIAL_HEAP_SIZE=<value>    Set the desired default initial heap size
 480   in bytes.
 481
 482 GC_FREE_SPACE_DIVISOR=<value>   Set alternate default GC_free_space_divisor
 483   value.
 484
 485 GC_TIME_LIMIT=<milliseconds>    Set alternate default GC_time_limit value
 486   (setting this to GC_TIME_UNLIMITED will essentially disable incremental
 487   collection while leaving generational collection enabled).
 488
 489 GC_FULL_FREQ=<value>    Set alternate default number of partial collections
 490   between full collections (matters only if incremental collection is on).
 491
 492 NO_CANCEL_SAFE (Posix platforms with threads only)      Don't bother trying
 493   to make the collector safe for thread cancellation; cancellation is not
 494   used.  (Note that if cancellation is used anyway, threads may end up
 495   getting cancelled in unexpected places.)  Even without this option,
 496   PTHREAD_CANCEL_ASYNCHRONOUS is never safe with the collector.  (We could
 497   argue about its safety without the collector.)