Debian Codegraph @

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.
96
97 GC_RETRY_SIGNALS - Try to compensate for lost
98 thread suspend and restart signals (Pthreads only).
99 On by default for OSF1 (Tru64) or if the library is
100 sanitized, off otherwise. 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
103 work-arounds. "0" value means "do not retry signals".
104
105 GC_USE_GETWRITEWATCH=<n> - Only if MPROTECT_VDB and (GWW_VDB or SOFT_VDB) are
106 both defined (Win32 and Linux only). Explicitly specify
107 which strategy of keeping track of dirtied pages should
108 be used. If n=0, then fall back to protecting pages and
109 catching memory faults strategy), else the collector
110 tries to use GetWriteWatch-based strategy (GWW_VDB) or
111 soft-dirty bits strategy (SOFT_VDB) first if available.
112
113 GC_DISABLE_INCREMENTAL - Ignore runtime requests to enable incremental GC.
114 Useful for debugging.
115
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:
119
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.
127
128 GC_PAUSE_TIME_TARGET - Set the desired garbage collector pause time in
129 milliseconds (ms). This only has an effect if incremental
130 collection is enabled. If a collection requires
131 appreciably more time than this, the client will be
132 restarted, and the collector will need to do additional
133 work to compensate. The special value "999999" indicates
134 that pause time is unlimited, and the incremental
135 collector will behave completely like a simple
136 generational collector. Any value, except for the given
137 special one, disables parallel marker (almost fully) for
138 now.
139
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.
143
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.
147
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.
152
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.
158
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.
162
163 GC_FINDLEAK_DELAY_FREE - Turns on deferred freeing of objects in the
164 find-leak mode (see the corresponding macro
165 description for more information).
166
167 GC_ABORT_ON_LEAK - Causes the application to be terminated once leaked or
168 smashed objects are found.
169
170 GC_ALL_INTERIOR_POINTERS - Turns on GC_all_interior_pointers and thus interior
171 pointer recognition.
172
173 GC_DONT_GC - Turns off garbage collection. Use cautiously.
174
175 GC_USE_ENTIRE_HEAP - Set desired GC_use_entire_heap value at start-up. See
176 the similar macro description in README.macros.
177
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.