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