| 1 |
The garbage collector looks at a number of environment variables which are, |
| 2 |
then, used to affect its operation. |
| 3 |
|
| 4 |
GC_INITIAL_HEAP_SIZE=<bytes> - Initial heap size in bytes. May speed up |
| 5 |
process start-up. Optionally, may be |
| 6 |
specified with a multiplier ('k', 'M' or 'G') |
| 7 |
suffix. |
| 8 |
|
| 9 |
GC_MAXIMUM_HEAP_SIZE=<bytes> - Maximum collected heap size. Allows |
| 10 |
a multiplier suffix. |
| 11 |
|
| 12 |
GC_LOOP_ON_ABORT - Causes the collector abort routine to enter a tight loop. |
| 13 |
This may make it easier to debug, such a process, especially |
| 14 |
for multi-threaded platforms that don't produce usable core |
| 15 |
files, or if a core file would be too large. On some |
| 16 |
platforms, this also causes SIGSEGV to be caught and |
| 17 |
result in an infinite loop in a handler, allowing |
| 18 |
similar debugging techniques. |
| 19 |
|
| 20 |
GC_PRINT_STATS - Turn on GC logging. Not functional with SMALL_CONFIG. |
| 21 |
|
| 22 |
GC_LOG_FILE - The name of the log file. Stderr by default. Not functional |
| 23 |
with SMALL_CONFIG. |
| 24 |
|
| 25 |
GC_ONLY_LOG_TO_FILE - Turns off redirection of GC stdout and stderr to the log |
| 26 |
file specified by GC_LOG_FILE. Has no effect unless |
| 27 |
GC_LOG_FILE is set. Not functional with SMALL_CONFIG. |
| 28 |
|
| 29 |
GC_PRINT_VERBOSE_STATS - Turn on even more logging. Not functional with |
| 30 |
SMALL_CONFIG. |
| 31 |
|
| 32 |
GC_DUMP_REGULARLY - Generate a GC debugging dump (by GC_dump_named) on startup |
| 33 |
and during every collection. Very verbose. Useful |
| 34 |
if you have a bug to report, but please include only the |
| 35 |
last complete dump. |
| 36 |
|
| 37 |
GC_COLLECT_AT_MALLOC=<n> - Override the default value specified by |
| 38 |
GC_COLLECT_AT_MALLOC macro. Has no effect unless |
| 39 |
GC is built with GC_COLLECT_AT_MALLOC defined. |
| 40 |
|
| 41 |
GC_BACKTRACES=<n> - Generate n random back-traces (for heap profiling) after |
| 42 |
each GC. Collector must have been built with |
| 43 |
KEEP_BACK_PTRS. This won't generate useful output unless |
| 44 |
most objects in the heap were allocated through debug |
| 45 |
allocators. This is intended to be only a statistical |
| 46 |
sample; individual traces may be erroneous due to |
| 47 |
concurrent heap mutation. |
| 48 |
|
| 49 |
GC_PRINT_ADDRESS_MAP - Linux only. Dump /proc/self/maps, i.e. various address |
| 50 |
maps for the process, to stderr on every GC. Useful for |
| 51 |
mapping root addresses to source for deciphering leak |
| 52 |
reports. |
| 53 |
|
| 54 |
GC_NPROCS=<n> - Linux w/threads only. Explicitly sets the number of processors |
| 55 |
that the GC should expect to use. Note that setting this to 1 |
| 56 |
when multiple processors are available will preserve |
| 57 |
correctness, but may lead to really horrible performance, |
| 58 |
since the lock implementation will immediately yield without |
| 59 |
first spinning. |
| 60 |
|
| 61 |
GC_MARKERS=<n> - Only if compiled with PARALLEL_MARK. Set the number |
| 62 |
of marker threads. This is normally set to the number of |
| 63 |
processors. It is safer to adjust GC_MARKERS than GC_NPROCS, |
| 64 |
since GC_MARKERS has no impact on the lock implementation. |
| 65 |
|
| 66 |
GC_NO_BLACKLIST_WARNING - Prevents the collector from issuing |
| 67 |
warnings about allocations of very large blocks. |
| 68 |
Deprecated. Use GC_LARGE_ALLOC_WARN_INTERVAL instead. |
| 69 |
|
| 70 |
GC_LARGE_ALLOC_WARN_INTERVAL=<n> - Print every nth warning about very large |
| 71 |
block allocations, starting with the nth one. Small values |
| 72 |
of n are generally benign, in that a bounded number of |
| 73 |
such warnings generally indicate at most a bounded leak. |
| 74 |
For best results it should be set at 1 during testing. |
| 75 |
Default is 5. Very large numbers effectively disable the |
| 76 |
warning. |
| 77 |
|
| 78 |
GC_IGNORE_GCJ_INFO - Ignore the type descriptors implicitly supplied by |
| 79 |
GC_gcj_malloc and friends. This is useful for debugging |
| 80 |
descriptor generation problems, and possibly for |
| 81 |
temporarily working around such problems. It forces a |
| 82 |
fully conservative scan of all heap objects except |
| 83 |
those known to be pointer-free, and may thus have other |
| 84 |
adverse effects. |
| 85 |
|
| 86 |
GC_PRINT_BACK_HEIGHT - Print max length of chain through unreachable objects |
| 87 |
ending in a reachable one. If this number remains |
| 88 |
bounded, then the program is "GC robust". This ensures |
| 89 |
that a fixed number of misidentified pointers can only |
| 90 |
result in a bounded space leak. This currently only |
| 91 |
works if debugging allocation is used throughout. |
| 92 |
It increases GC space and time requirements appreciably. |
| 93 |
This feature is still somewhat experimental, and requires |
| 94 |
that the collector have been built with MAKE_BACK_GRAPH |
| 95 |
defined. For details, see Boehm, "Bounding Space Usage |
| 96 |
of Conservative Garbage Collectors", POPL 2001 |
| 97 |
(http://www.hpl.hp.com/techreports/2001/HPL-2001-251.html). |
| 98 |
|
| 99 |
GC_RETRY_SIGNALS - Try to compensate for lost |
| 100 |
thread suspend and restart signals (Pthreads only). |
| 101 |
On by default for OSF1 (Tru64) or if the library is |
| 102 |
sanitized, off otherwise. Since we've previously seen |
| 103 |
similar issues on some other operating systems, it |
| 104 |
was turned into a runtime flag to enable last-minute |
| 105 |
work-arounds. "0" value means "do not retry signals". |
| 106 |
|
| 107 |
GC_USE_GETWRITEWATCH=<n> - Only if MPROTECT_VDB and (GWW_VDB or SOFT_VDB) are |
| 108 |
both defined (Win32 and Linux only). Explicitly specify |
| 109 |
which strategy of keeping track of dirtied pages should |
| 110 |
be used. If n=0, then fall back to protecting pages and |
| 111 |
catching memory faults strategy), else the collector |
| 112 |
tries to use GetWriteWatch-based strategy (GWW_VDB) or |
| 113 |
soft-dirty bits strategy (SOFT_VDB) first if available. |
| 114 |
|
| 115 |
GC_DISABLE_INCREMENTAL - Ignore runtime requests to enable incremental GC. |
| 116 |
Useful for debugging. |
| 117 |
|
| 118 |
The following turn on runtime flags that are also program settable. Checked |
| 119 |
only during initialization. We expect that they will usually be set through |
| 120 |
other means, but this may help with debugging and testing: |
| 121 |
|
| 122 |
GC_ENABLE_INCREMENTAL - Turn on incremental collection at startup. Note that, |
| 123 |
depending on platform and collector configuration, this |
| 124 |
may involve write protecting pieces of the heap to |
| 125 |
track modifications. These pieces may include |
| 126 |
pointer-free objects or not. Although this is intended |
| 127 |
to be transparent, it may cause unintended system call |
| 128 |
failures. Use with caution. |
| 129 |
|
| 130 |
GC_PAUSE_TIME_TARGET - Set the desired garbage collector pause time in |
| 131 |
milliseconds (ms). This only has an effect if incremental |
| 132 |
collection is enabled. If a collection requires |
| 133 |
appreciably more time than this, the client will be |
| 134 |
restarted, and the collector will need to do additional |
| 135 |
work to compensate. The special value "999999" indicates |
| 136 |
that pause time is unlimited, and the incremental |
| 137 |
collector will behave completely like a simple |
| 138 |
generational collector. Any value, except for the given |
| 139 |
special one, disables parallel marker (almost fully) for |
| 140 |
now. |
| 141 |
|
| 142 |
GC_FULL_FREQUENCY - Set the desired number of partial collections between full |
| 143 |
collections. Matters only if GC_incremental is set. |
| 144 |
Not functional with SMALL_CONFIG. |
| 145 |
|
| 146 |
GC_FREE_SPACE_DIVISOR - Set GC_free_space_divisor to the indicated value. |
| 147 |
Setting it to larger values decreases space consumption |
| 148 |
and increases GC frequency. |
| 149 |
|
| 150 |
GC_UNMAP_THRESHOLD - Set the desired memory blocks unmapping threshold (the |
| 151 |
number of sequential garbage collections for which |
| 152 |
a candidate block for unmapping should remain free). The |
| 153 |
special value "0" completely disables unmapping. |
| 154 |
|
| 155 |
GC_FORCE_UNMAP_ON_GCOLLECT - Turn "unmap as much as possible on explicit GC" |
| 156 |
mode on (overrides the default value). Has no effect on |
| 157 |
implicitly-initiated garbage collections. Has no effect if |
| 158 |
memory unmapping is disabled (or not compiled in) or if the |
| 159 |
unmapping threshold is 1. |
| 160 |
|
| 161 |
GC_FIND_LEAK - Turns on GC_find_leak and thus leak detection. Forces a |
| 162 |
collection at program termination to detect leaks that would |
| 163 |
otherwise occur after the last GC. |
| 164 |
|
| 165 |
GC_FINDLEAK_DELAY_FREE - Turns on deferred freeing of objects in the |
| 166 |
leak-finding mode (see the corresponding macro |
| 167 |
description for more information). |
| 168 |
|
| 169 |
GC_ABORT_ON_LEAK - Causes the application to be terminated once leaked or |
| 170 |
smashed objects are found. |
| 171 |
|
| 172 |
GC_ALL_INTERIOR_POINTERS - Turns on GC_all_interior_pointers and thus interior |
| 173 |
pointer recognition. |
| 174 |
|
| 175 |
GC_DONT_GC - Turns off garbage collection. Use cautiously. |
| 176 |
|
| 177 |
GC_USE_ENTIRE_HEAP - Set desired GC_use_entire_heap value at start-up. See |
| 178 |
the similar macro description in README.macros. |
| 179 |
|
| 180 |
GC_TRACE=addr - Intended for collector debugging. Requires that the collector |
| 181 |
have been built with ENABLE_TRACE defined. Causes the debugger |
| 182 |
to log information about the tracing of address ranges |
| 183 |
containing addr. Typically addr is the address that contains |
| 184 |
a pointer to an object that mysteriously failed to get marked. |
| 185 |
Addr must be specified as a hexadecimal integer. |