| 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. |