Debian Codegraph @

gc/doc/README.macros

raw
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.)
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_NAMESPACE Tested by gc_cpp.h. Causes gc_cpp symbols to be defined
34 in "boehmgc" namespace.
35
36 GC_DEBUG_REPLACEMENT Tested by gc.h. Causes GC_MALLOC/REALLOC() to be
37 defined as GC_debug_malloc/realloc_replacement().
38
39 GC_NO_THREAD_REDIRECTS Tested by gc.h. Prevents redirection of thread
40 creation routines etc. to GC_ versions. Requires the
41 programmer to explicitly handle thread registration.
42
43 GC_NO_THREAD_DECLS Tested by gc.h. Windows only. Do not declare
44 Windows thread creation routines and do not include windows.h.
45
46 GC_DONT_INCLUDE_WINDOWS_H Tested by gc.h. Windows only. Do not include
47 windows.h from gc.h (but Windows-specific thread creation
48 routines are declared).
49
50 GC_UNDERSCORE_STDCALL Tested by gc.h. Explicitly prefix exported/imported
51 WINAPI (__stdcall) symbols with '_' (underscore). Could be
52 used with MinGW (for x86) compiler (in conjunction with
53 GC_DLL) to follow MS conventions for __stdcall symbols naming.
54
55 _ENABLE_ARRAYNEW
56 #define'd by the Digital Mars C++ compiler when
57 operator new[] and delete[] are separately
58 overloadable. Used in gc_cpp.h.
59
60 GC_NO_INLINE_STD_NEW Tested by gc_cpp.cc and gc_cpp.h. Windows only.
61 Define the system-wide new and delete operators in gccpp.dll
62 instead of providing an inline version of the operators.
63
64 _DLL Tested by gc_config_macros.h. Defined by Visual C++ if runtime
65 dynamic libraries are in use. Used (only if none of GC_DLL,
66 GC_NOT_DLL, __GNUC__ are defined) to test whether
67 __declspec(dllimport) needs to be added to declarations
68 to support the case in which the collector is in a DLL.
69
70 GC_DLL Defined by user if dynamic libraries are being built
71 or used. Also set by gc.h if _DLL is defined (except for
72 mingw) while GC_NOT_DLL and __GNUC__ are both undefined.
73 This is the macro that is tested internally to determine
74 whether the GC is in its own dynamic library. May need
75 to be set by clients before including gc.h. Note that
76 inside the GC implementation it indicates that the
77 collector is in its own dynamic library, should export
78 its symbols, etc. But in clients it indicates that the
79 GC resides in a different DLL, its entry points should
80 be referenced accordingly, and precautions may need to
81 be taken to properly deal with statically allocated
82 variables in the main program. Used for Windows.
83 Also used by GCC v4+ (only when the dynamic shared library
84 is being built) to hide internally used symbols.
85
86 GC_NOT_DLL User-settable macro that overrides _DLL, e.g. if runtime
87 dynamic libraries are used, but the collector is in a static
88 library. Tested by gc_config_macros.h.
89
90 GC_MARKERS=<n> Set the desired number of marker threads. If not defined or
91 defined to zero, then the collector decides based on the
92 number of CPU cores. Only if compiled with PARALLEL_MARK.
93
94
95 These define arguments influence the collector configuration:
96
97 GC_REQUIRE_WCSDUP Force GC to export GC_wcsdup() (the Unicode version
98 of GC_strdup); could be useful in the leak-finding mode. Clients should
99 define it before including gc.h if the function is needed.
100
101 FIND_LEAK Causes GC_find_leak to be initially set. This causes the
102 collector to assume that all inaccessible objects should have been
103 explicitly deallocated, and reports exceptions. Finalization and the test
104 program are not usable in this mode.
105
106 GC_FINDLEAK_DELAY_FREE Turns on deferred freeing of objects in the
107 leak-finding mode letting the collector to detect alter-object-after-free
108 errors as well as detect leaked objects sooner (instead of only when program
109 terminates). Has no effect if SHORT_DBG_HDRS.
110
111 GC_ABORT_ON_LEAK Causes the application to be terminated once leaked or
112 smashed (corrupted on use-after-free) objects are found (after printing the
113 information about that objects).
114
115 SUNOS5SIGS Solaris-like signal handling. This is probably misnamed,
116 since it really doesn't guarantee much more than POSIX. Currently set only
117 for DRSNX, FreeBSD, HP/UX and Solaris.
118
119 PCR Set if the collector is being built as part of the Xerox Portable
120 Common Runtime.
121
122 GC_THREADS Should set the appropriate one of the below macros,
123 except GC_WIN32_PTHREADS, which must be set explicitly. Tested by gc.h.
124 IMPORTANT: GC_THREADS macro (or the relevant platform-specific deprecated
125 one) must normally also be defined by the client before including gc.h.
126 This redefines thread primitives to invoke the GC_ wrappers instead.
127 Alternatively, linker-based symbol interception can be used on a few
128 platforms.
129
130 GC_SOLARIS_THREADS Enables support for Solaris pthreads.
131 Must also define _REENTRANT. Deprecated, use GC_THREADS instead.
132
133 GC_IRIX_THREADS Enables support for Irix pthreads. See README.sgi.
134 Deprecated, use GC_THREADS instead.
135
136 GC_HPUX_THREADS Enables support for HP/UX 11 pthreads.
137 Also requires _REENTRANT or _POSIX_C_SOURCE=199506L. See README.hp.
138 Deprecated, use GC_THREADS instead.
139
140 GC_LINUX_THREADS Enables support for Xavier Leroy's Linux threads
141 or NPTL threads. See README.linux. _REENTRANT may also be required.
142 Deprecated, use GC_THREADS instead.
143
144 GC_OSF1_THREADS Enables support for Tru64 pthreads. Deprecated, use
145 GC_THREADS instead.
146
147 GC_FREEBSD_THREADS Enables support for FreeBSD pthreads. Appeared to run
148 into some underlying thread problems. Deprecated, use GC_THREADS instead.
149
150 GC_NETBSD_THREADS Enables support for NetBSD pthreads. Deprecated, use
151 GC_THREADS instead.
152
153 GC_OPENBSD_THREADS Enables support for OpenBSD pthreads. Deprecated,
154 use GC_THREADS instead.
155
156 GC_DARWIN_THREADS Enables support for Mac OS X pthreads. Deprecated,
157 use GC_THREADS instead.
158
159 GC_AIX_THREADS Enables support for IBM AIX threads. Deprecated, use
160 GC_THREADS instead.
161
162 GC_DGUX386_THREADS Enables support for DB/UX x86 threads.
163 See README.DGUX386. (Probably has not been tested recently.) Deprecated,
164 use GC_THREADS instead.
165
166 GC_WIN32_THREADS Enables support for Win32 threads. Deprecated,
167 use GC_THREADS instead.
168
169 GC_WIN32_PTHREADS Enables support for pthreads-win32 (or other
170 non-Cygwin pthreads library for Windows). This cannot be enabled
171 automatically by GC_THREADS, which would assume Win32 native threads.
172
173 PTW32_STATIC_LIB Causes the static version of the Mingw pthreads
174 library to be used. Requires GC_WIN32_PTHREADS.
175
176 GC_PTHREADS_PARAMARK Causes pthread-based parallel mark implementation
177 to be used even if GC_WIN32_PTHREADS is undefined. (Useful for WinCE.)
178
179 ALL_INTERIOR_POINTERS Allows all pointers to the interior of objects to be
180 recognized. (See gc_priv.h for consequences.) Alternatively,
181 GC_all_interior_pointers can be set at process initialization time.
182
183 SMALL_CONFIG Tries to tune the collector for small heap sizes,
184 usually causing it to use less space in such situations. Incremental
185 collection no longer works in this case. Also, removes some
186 statistic-printing code. Turns off some optimization algorithms (like data
187 prefetching in the mark routine).
188
189 NO_CLOCK Do not use system clock. Disables some statistic printing.
190
191 GC_DISABLE_INCREMENTAL Turn off the incremental collection support.
192
193 NO_INCREMENTAL Causes the GC test programs to not invoke the incremental mode
194 of the collector. This has no impact on the generated library, only on the
195 test programs. (This is often useful for debugging failures unrelated to
196 incremental GC.)
197
198 LARGE_CONFIG Tunes the collector for unusually large heaps.
199 Necessary for heaps larger than about 4 GiB on most (64-bit) machines.
200 Recommended for heaps larger than about 500 MiB. Not recommended for
201 embedded systems. Could be used in conjunction with SMALL_CONFIG to
202 generate smaller code (by disabling incremental collection support,
203 statistic printing and some optimization algorithms).
204
205 DONT_ADD_BYTE_AT_END Meaningful only with ALL_INTERIOR_POINTERS or
206 GC_all_interior_pointers = 1. Normally ALL_INTERIOR_POINTERS
207 causes all objects to be padded so that pointers just past the end of
208 an object can be recognized. This can be expensive. (The padding
209 is normally more than one byte due to alignment constraints.)
210 DONT_ADD_BYTE_AT_END disables the padding.
211
212 NO_EXECUTE_PERMISSION May cause some or all of the heap to not
213 have execute permission, i.e. it may be impossible to execute
214 code from the heap. Affects the incremental collector and memory unmapping.
215 It may greatly improve the performance, since this may avoid some expensive
216 cache synchronization. Portable clients should call
217 GC_set_pages_executable(1) at the process initialization time if the
218 execute permission is required.
219
220 GC_NO_OPERATOR_NEW_ARRAY Declares that the C++ compiler does not
221 support the new syntax "operator new[]" for allocating and deleting arrays.
222 See gc_cpp.h for details. No effect on the C part of the collector.
223 This is defined implicitly in a few environments. Must also be defined
224 by clients that use gc_cpp.h.
225
226 REDIRECT_MALLOC=<X> Causes malloc to be defined as alias for X.
227 Unless the following macros are defined, realloc is also redirected
228 to GC_realloc, and free is redirected to GC_free.
229 Calloc and str[n]dup are redefined in terms of the new malloc. X should
230 be either GC_malloc or GC_malloc_uncollectable, or
231 GC_debug_malloc_replacement. (The latter invokes GC_debug_malloc
232 with dummy source location information, but still results in
233 properly remembered call stacks on Linux/x86 and Solaris/SPARC.
234 It requires that the following two macros also be used.)
235 The former is occasionally useful for working around leaks in code
236 you don't want to (or can't) look at. It may not work for
237 existing code, but it often does. Neither works on all platforms,
238 since some ports use malloc or calloc to obtain system memory.
239 (Probably works for UNIX, and Win32.) If you build with DBG_HDRS_ALL,
240 you should only use GC_debug_malloc_replacement as a malloc
241 replacement.
242
243 REDIRECT_REALLOC=<X> Causes realloc to be redirected to X.
244 The canonical use is REDIRECT_REALLOC=GC_debug_realloc_replacement,
245 together with REDIRECT_MALLOC=GC_debug_malloc_replacement to
246 generate leak reports with call stacks for both malloc and realloc.
247 This also requires REDIRECT_FREE.
248
249 REDIRECT_FREE=<X> Causes free to be redirected to X. The canonical use
250 is REDIRECT_FREE=GC_debug_free.
251
252 IGNORE_FREE Turns calls to free into a no-op. Only useful with
253 REDIRECT_MALLOC.
254
255 NO_DEBUGGING Removes GC_dump and the debugging routines it calls.
256 Reduces code size slightly at the expense of debuggability.
257
258 GC_DUMP_REGULARLY Generate regular debugging dumps.
259
260 DEBUG_THREADS Turn on printing additional thread-support debugging
261 information.
262
263 GC_COLLECT_AT_MALLOC=<n> Force garbage collection at every
264 GC_malloc_* call with the size greater than the specified value.
265 (Might be useful for application debugging or in find-leak mode.)
266
267 JAVA_FINALIZATION Makes it somewhat safer to finalize objects out of
268 order by specifying a nonstandard finalization mark procedure (see
269 finalize.c). Objects reachable from finalizable objects will be marked
270 in a separate post-pass, and hence their memory won't be reclaimed.
271 Not recommended unless you are implementing a language that specifies
272 these semantics. Actually, the macro determines only the initial value
273 of GC_java_finalization variable.
274
275 FINALIZE_ON_DEMAND Causes finalizers to be run only in response
276 to explicit GC_invoke_finalizers() calls. Actually, the macro only
277 determines the initial value of GC_finalize_on_demand.
278
279 GC_NO_FINALIZATION Exclude finalization support (for smaller code size).
280
281 GC_TOGGLE_REFS_NOT_NEEDED Exclude toggle-refs support.
282
283 GC_ATOMIC_UNCOLLECTABLE Includes code for GC_malloc_atomic_uncollectable.
284 This is useful if either the vendor malloc implementation is poor,
285 or if REDIRECT_MALLOC is used.
286
287 MARK_BIT_PER_GRANULE Requests that a mark bit (or often byte)
288 be allocated for each allocation granule, as opposed to each object.
289 This often improves speed, possibly at some cost in space and/or
290 cache footprint. Normally it is best to let this decision be
291 made automatically depending on platform.
292
293 MARK_BIT_PER_OBJ Requests that a mark bit be allocated for each
294 object instead of allocation granule. The opposite of
295 MARK_BIT_PER_GRANULE.
296
297 HBLKSIZE=<ddd> Explicitly sets the heap block size (where ddd is a power of
298 2 between 512 and 16384). Each heap block is devoted to a single size and
299 kind of object. For the incremental collector it makes sense to match
300 the most likely page size. Otherwise large values result in more
301 fragmentation, but generally better performance for large heaps.
302
303 USE_MMAP Use MMAP instead of sbrk to get new memory.
304 Works for Linux, FreeBSD, Cygwin, Solaris and Irix.
305
306 USE_MUNMAP Causes memory to be returned to the OS under the right
307 circumstances. Works under some Unix, Linux and Windows versions.
308 Requires USE_MMAP except for Windows.
309
310 USE_WINALLOC (Cygwin only) Use Win32 VirtualAlloc (instead of sbrk or mmap)
311 to get new memory. Useful if memory unmapping (USE_MUNMAP) is enabled.
312
313 MUNMAP_THRESHOLD=<value> Set the desired memory blocks unmapping
314 threshold (the number of sequential garbage collections for which
315 a candidate block for unmapping should remain free).
316
317 GC_FORCE_UNMAP_ON_GCOLLECT Set "unmap as much as possible on explicit GC"
318 mode on by default. The mode could be changed at run-time. Has no effect
319 unless unmapping is turned on. Has no effect on implicitly-initiated
320 garbage collections.
321
322 PRINT_BLACK_LIST Whenever a black list entry is added, i.e. whenever
323 the garbage collector detects a value that looks almost, but not quite,
324 like a pointer, print both the address containing the value, and the
325 value of the near-bogus-pointer. Can be used to identify regions of
326 memory that are likely to contribute misidentified pointers.
327
328 KEEP_BACK_PTRS Add code to save back pointers in debugging headers
329 for objects allocated with the debugging allocator. If all objects
330 through GC_MALLOC with GC_DEBUG defined, this allows the client
331 to determine how particular or randomly chosen objects are reachable
332 for debugging/profiling purposes. The gc_backptr.h interface is
333 implemented only if this is defined.
334
335 GC_ASSERTIONS Enable some internal GC assertion checking. It is intended
336 primarily for debugging of the garbage collector itself, but could also
337 help to identify cases of incorrect GC usage by a client.
338
339 DBG_HDRS_ALL Make sure that all objects have debug headers. Increases
340 the reliability (from 99.9999% to 100% mod. bugs) of some of the debugging
341 code (especially KEEP_BACK_PTRS). Makes SHORT_DBG_HDRS possible.
342 Assumes that all client allocation is done through debugging allocators.
343
344 SHORT_DBG_HDRS Assume that all objects have debug headers. Shorten
345 the headers to minimize object size, at the expense of checking for
346 writes past the end of an object. This is intended for environments
347 in which most client code is written in a "safe" language, such as
348 Scheme or Java. Assumes that all client allocation is done using
349 the GC_debug_ functions, or through the macros that expand to these,
350 or by redirecting malloc to GC_debug_malloc_replacement.
351 (Also eliminates the field for the requested object size.)
352 Occasionally could be useful for debugging of client code. Slows down the
353 collector somewhat, but not drastically.
354
355 SAVE_CALL_COUNT=<n> Set the number of call frames saved with objects
356 allocated through the debugging interface. Affects the amount of
357 information generated in leak reports. Only matters on platforms
358 on which we can quickly generate call stacks, currently Linux/x86,
359 Linux/SPARC, Solaris/SPARC, and platforms that provide execinfo.h.
360 Default is zero. On x86, client code should NOT be compiled with
361 -fomit-frame-pointer.
362
363 SAVE_CALL_NARGS=<n> Set the number of functions arguments to be saved
364 with each call frame. Default is zero. Ignored if we don't know how to
365 retrieve arguments on the platform.
366
367 CHECKSUMS Reports on erroneously clear dirty bits (at a substantial
368 performance cost). Use only for debugging of the incremental collector.
369 Not compatible with USE_MUNMAP or threads.
370
371 GC_GCJ_SUPPORT Includes support for gcj (and possibly other systems
372 that include a pointer to a type descriptor in each allocated object).
373
374 USE_I686_PREFETCH Causes the collector to issue Pentium III style
375 prefetch instructions. No effect except on Linux/x86 platforms.
376 Empirically the code appears to still run correctly on Pentium II
377 processors, though with no performance benefit. May not run on other
378 x86 processors probably. In some cases this improves performance by 15%
379 or so.
380
381 USE_3DNOW_PREFETCH Causes the collector to issue AMD 3DNow style
382 prefetch instructions. Same restrictions as USE_I686_PREFETCH.
383 Minimally tested. Didn't appear to be an obvious win on a K6-2/500.
384
385 USE_PPC_PREFETCH Causes the collector to issue PowerPC style
386 prefetch instructions. No effect except on PowerPC OS X platforms.
387 Performance impact untested.
388
389 GC_USE_LD_WRAP In combination with the old flags listed in README.linux
390 causes the collector some system and pthread calls in a more transparent
391 fashion than the usual macro-based approach. Requires GNU ld, and
392 currently probably works only with Linux.
393
394 GC_USE_DLOPEN_WRAP Causes the collector to redefine malloc and
395 intercepted pthread routines with their real names, and causes it to use
396 dlopen and dlsym to refer to the original versions. This makes it possible
397 to build an LD_PRELOADable malloc replacement library.
398
399 THREAD_LOCAL_ALLOC Defines GC_malloc(), GC_malloc_atomic() and
400 GC_gcj_malloc() to use a per-thread set of free-lists. These then allocate
401 in a way that usually does not involve acquisition of a global lock.
402 Recommended for multiprocessors.
403
404 USE_COMPILER_TLS Causes thread local allocation to use
405 the compiler-supported "__thread" thread-local variables. This is the
406 default in HP/UX. It may help performance on recent Linux installations.
407 (It failed for me on RedHat 8, but appears to work on RedHat 9.)
408
409 GC_ATTR_TLS_FAST Use specific attributes for GC_thread_key like
410 __attribute__((tls_model("local-exec"))).
411
412 PARALLEL_MARK Allows the marker to run in multiple threads. Recommended
413 for multiprocessors.
414
415 GC_BUILTIN_ATOMIC Use GCC atomic intrinsics instead of libatomic_ops
416 primitives.
417
418 GC_ALWAYS_MULTITHREADED Force multi-threaded mode at GC initialization.
419
420 GC_ENABLE_SUSPEND_THREAD (Linux only) Turn on thread suspend/resume API
421 support.
422
423 GC_WINMAIN_REDIRECT (Win32 only) Redirect (rename) an application
424 WinMain to GC_WinMain; implement the "real" WinMain which starts a new
425 thread to call GC_WinMain after initializing the GC. Useful for WinCE.
426 Incompatible with GC_DLL.
427
428 GC_REGISTER_MEM_PRIVATE (Win32 only) Force to register MEM_PRIVATE R/W
429 sections as data roots. Might be needed for some WinCE 6.0+ custom builds.
430 (May result in numerous "Data Abort" messages logged to WinCE debugging
431 console.) Incompatible with GCC toolchains for WinCE.
432
433 NO_GETENV Prevents the collector from looking at environment variables.
434 These may otherwise alter its configuration, or turn off GC altogether.
435 I don't know of a reason to disable this, except possibly if the resulting
436 process runs as a privileged user. (This is on by default for WinCE.)
437
438 EMPTY_GETENV_RESULTS Define to workaround a reputed Wine bug in getenv
439 (getenv() may return an empty string instead of NULL for a missing entry).
440
441 GC_READ_ENV_FILE (Win32 only) Read environment variables from the GC "env"
442 file (named as the program name plus ".gc.env" extension). Useful for WinCE
443 targets (which have no getenv()). In the file, every variable is specified
444 in a separate line and the format is as "<name>=<value>" (without spaces).
445 A comment line may start with any character except for the Latin letters,
446 the digits and the underscore ('_'). The file encoding is Latin-1.
447
448 USE_GLOBAL_ALLOC (Win32 only) Use GlobalAlloc() instead of VirtualAlloc()
449 to allocate the heap. May be needed to work around a Windows NT/2000 issue.
450 Incompatible with USE_MUNMAP. See README.win32 for details.
451
452 MAKE_BACK_GRAPH Enable GC_PRINT_BACK_HEIGHT environment variable.
453 See README.environment for details. Experimental. Limited platform
454 support. Implies DBG_HDRS_ALL. All allocation should be done using
455 the debug interface.
456
457 GC_PRINT_BACK_HEIGHT Permanently turn on back-height printing mode
458 (useful when NO_GETENV). See the similar environment variable description
459 in README.environment. Requires MAKE_BACK_GRAPH defined.
460
461 HANDLE_FORK (Unix and Cygwin only) Attempt by default to make GC_malloc()
462 work in a child process fork()'ed from a multi-threaded parent. Not fully
463 POSIX-compliant and could be disabled at runtime (before GC_INIT).
464
465 TEST_WITH_SYSTEM_MALLOC Causes gctest to allocate (and leak) large
466 chunks of memory with the standard system malloc. This will cause the root
467 set and collected heap to grow significantly if malloc'ed memory is somehow
468 getting traced by the collector. This has no impact on the generated
469 library; it only affects the test.
470
471 POINTER_MASK=<0x...> Causes candidate pointers to be AND'ed with the given
472 mask before being considered. If either this or the following macro is
473 defined, it will be assumed that all pointers stored in the heap need to be
474 processed this way. Stack and register pointers will be considered both
475 with and without processing. These macros are normally needed only to
476 support systems that use high-order pointer tags. EXPERIMENTAL.
477
478 POINTER_SHIFT=<n> Causes the collector to left shift candidate pointers
479 by the indicated amount before trying to interpret them. Applied after
480 POINTER_MASK. EXPERIMENTAL. See also the preceding macro.
481
482 ENABLE_TRACE Enables the GC_TRACE=addr environment setting to do its job.
483 By default this is not supported in order to keep the marker as fast as
484 possible.
485
486 DARWIN_DONT_PARSE_STACK Causes the Darwin port to discover thread
487 stack bounds in the same way as other pthread ports, without trying to
488 walk the frames on the stack. This is recommended only as a fall-back for
489 applications that don't support proper stack unwinding.
490
491 GC_NO_THREADS_DISCOVERY (Darwin and Win32+DLL only) Exclude DllMain-based
492 (on Windows) and task-threads-based (on Darwin) thread registration support.
493
494 GC_INSIDE_DLL (Win32 only) Enable DllMain-based approach of threads
495 registering even in case GC_DLL is not defined.
496
497 GC_DISCOVER_TASK_THREADS (Darwin and Win32+DLL only) Compile the collector
498 with the implicitly turned on task-threads-based (on Darwin) or
499 DllMain-based (on Windows) approach of threads registering. Only for
500 compatibility and for the case when it is not possible to call
501 GC_use_threads_discovery() early (before other GC calls).
502
503 USE_PROC_FOR_LIBRARIES Causes the Linux collector to treat writable
504 memory mappings (as reported by /proc) as roots, if it doesn't have
505 other information about them. It no longer traverses dynamic loader
506 data structures to find dynamic library static data. This may be
507 required for applications that store pointers in mmapped segments without
508 informing the collector. But it typically performs poorly, especially
509 since it will scan inactive but cached NPTL thread stacks completely.
510
511 IGNORE_DYNAMIC_LOADING Don't define DYNAMIC_LOADING even if supported by the
512 platform (that is, build the collector with disabled tracing of dynamic
513 library data roots).
514
515 NO_PROC_STAT Causes the collector to avoid relying on Linux
516 "/proc/self/stat".
517
518 NO_GETCONTEXT Causes the collector to not assume the existence of the
519 getcontext() function on linux-like platforms. This currently happens
520 implicitly on Darwin, Hurd, or ARM or MIPS hardware. It is explicitly
521 needed for some old versions of FreeBSD.
522
523 STATIC=static Causes various GC_ symbols that could logically be declared
524 static to be declared (this is the default if NO_DEBUGGING is specified).
525 Reduces the number of visible symbols (letting the optimizer do its work
526 better), which is probably cleaner, but may make some kinds of debugging
527 and profiling harder.
528
529 GC_DLL Build dynamic-link library (or dynamic shared object). For Unix this
530 causes the exported symbols to have 'default' visibility (ignored unless
531 GCC v4+) and the internal ones to have 'hidden' visibility.
532
533 NO_MSGBOX_ON_ERROR (Win32 only) Do not show Windows message box with
534 "OK" button on a GC fatal error. Otherwise the client application is
535 terminated only once the user clicks "OK" button. Useful for non-GUI (or
536 non-interactive) applications.
537
538 DONT_USE_USER32_DLL (Win32 only) Don't use "user32" DLL import library
539 (containing MessageBox() entry); useful for a static GC library.
540
541 GC_PREFER_MPROTECT_VDB Choose MPROTECT_VDB manually in case of multiple
542 virtual dirty bit strategies are implemented (at present useful on Win32,
543 Solaris and Linux to force MPROTECT_VDB strategy instead of the default
544 GWW_VDB, PROC_VDB or SOFT_VDB ones, respectively).
545
546 GC_IGNORE_GCJ_INFO Disable GCJ-style type information (useful for
547 debugging on WinCE).
548
549 GC_PRINT_VERBOSE_STATS Permanently turn on verbose logging (useful for
550 debugging and profiling on WinCE).
551
552 GC_ONLY_LOG_TO_FILE Don't redirect GC stdout and stderr to the log file
553 specified by GC_LOG_FILE environment variable. Has effect only when the
554 variable is set (to anything other than "0").
555
556 GC_ANDROID_LOG (Android only) Output error/debug information to Android log.
557
558 CONSOLE_LOG (Win32 only) Output error/debug information to stdout and
559 stderr.
560
561 GC_DONT_EXPAND Don't expand the heap unless explicitly requested or forced to.
562
563 GC_USE_ENTIRE_HEAP Causes the non-incremental collector to use the
564 entire heap before collecting. This sometimes results in more large block
565 fragmentation, since very large blocks will tend to get broken up during
566 each GC cycle. It is likely to result in a larger working set, but lower
567 collection frequencies, and hence fewer instructions executed in the
568 collector. This macro controls only the default GC_use_entire_heap value.
569
570 GC_INITIAL_HEAP_SIZE=<value> Set the desired default initial heap size
571 in bytes.
572
573 GC_FREE_SPACE_DIVISOR=<value> Set alternate default GC_free_space_divisor
574 value.
575
576 GC_ALLOCD_BYTES_PER_FINALIZER=<value> Set alternate default value of
577 GC_allocd_bytes_per_finalizer.
578
579 GC_TIME_LIMIT=<milliseconds> Set alternate default GC_time_limit value
580 (setting this to GC_TIME_UNLIMITED will essentially disable incremental
581 collection while leaving generational collection enabled).
582
583 GC_FULL_FREQ=<value> Set alternate default number of partial collections
584 between full collections (matters only if incremental collection is on).
585
586 NO_CANCEL_SAFE (Posix platforms with threads only) Don't bother trying
587 to make the collector safe for thread cancellation; cancellation is not
588 used. (Note that if cancellation is used anyway, threads may end up
589 getting canceled in unexpected places.) Even without this option,
590 PTHREAD_CANCEL_ASYNCHRONOUS is never safe with the collector. (We could
591 argue about its safety without the collector.)
592
593 UNICODE (Win32 only) Use the Unicode variant ('W') of the Win32 API instead
594 of ANSI/ASCII one ('A'). Useful for WinCE.
595
596 HOST_ANDROID (or __ANDROID__) Compile for Android NDK platform.
597
598 SN_TARGET_PS3 Compile for Sony PS/3.
599
600 USE_GET_STACKBASE_FOR_MAIN (Linux only) Use pthread_attr_getstack() instead
601 of __libc_stack_end (or instead of any hard-coded value) for getting the
602 primordial thread stack bottom (useful if the client modifies the program's
603 address space).
604
605 EMSCRIPTEN_ASYNCIFY (Emscripten only) Use Asyncify feature. Note this is
606 a relatively rarely used feature of Emscripten, most developers do not use
607 it, and it does not scale well to moderate-to-large code bases. But the
608 feature is needed to pass gctest, at least. Requires -sASYNCIFY linker
609 flag.