Debian Codegraph @

gc/doc/README.environment

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