source: trunk/gc6.8/doc/README.environment

Last change on this file was 132, checked in by cinc, 19 years ago

Boehm-Demers-Weiser garbage collector. Single-threaded for OS/2.
File size: 7.5 KB
Line 
1The garbage collector looks at a number of environment variables which are
2then used to affect its operation. These are examined only on Un*x-like
3platforms and win32.
4
5GC_INITIAL_HEAP_SIZE=<bytes> - Initial heap size in bytes. May speed up
6 process start-up.
7
8GC_MAXIMUM_HEAP_SIZE=<bytes> - Maximum collected heap size.
9
10GC_LOOP_ON_ABORT - Causes the collector abort routine to enter a tight loop.
11 This may make it easier to debug, such a process, especially
12 for multithreaded platforms that don't produce usable core
13 files, or if a core file would be too large. On some
14 platforms, this also causes SIGSEGV to be caught and
15 result in an infinite loop in a handler, allowing
16 similar debugging techniques.
17
18GC_PRINT_STATS - Turn on as much logging as is easily feasible without
19 adding signifcant runtime overhead. Doesn't work if
20 the collector is built with SMALL_CONFIG. Overridden
21 by setting GC_quiet. On by default if the collector
22 was built without -DSILENT.
23
24GC_DUMP_REGULARLY - Generate a GC debugging dump GC_dump() on startup
25 and during every collection. Very verbose. Useful
26 if you have a bug to report, but please include only the
27 last complete dump.
28
29GC_BACKTRACES=<n> - Generate n random backtraces (for heap profiling) after
30 each GC. Collector must have been built with
31 KEEP_BACK_PTRS. This won't generate useful output unless
32 most objects in the heap were allocated through debug
33 allocators. This is intended to be only a statistical
34 sample; individual traces may be erroneous due to
35 concurrent heap mutation.
36
37GC_PRINT_ADDRESS_MAP - Linux only. Dump /proc/self/maps, i.e. various address
38 maps for the process, to stderr on every GC. Useful for
39 mapping root addresses to source for deciphering leak
40 reports.
41
42GC_NPROCS=<n> - Linux w/threads only. Explicitly sets the number of processors
43 that the GC should expect to use. Note that setting this to 1
44 when multiple processors are available will preserve
45 correctness, but may lead to really horrible performance,
46 since the lock implementation will immediately yield without
47 first spinning.
48
49GC_MARKERS=<n> - Linux w/threads and parallel marker only. Set the number
50 of marker threads. This is normaly set to the number of
51 processors. It is safer to adjust GC_MARKERS than GC_NPROCS,
52 since GC_MARKERS has no impact on the lock implementation.
53
54GC_NO_BLACKLIST_WARNING - Prevents the collector from issuing
55 warnings about allocations of very large blocks.
56 Deprecated. Use GC_LARGE_ALLOC_WARN_INTERVAL instead.
57
58GC_LARGE_ALLOC_WARN_INTERVAL=<n> - Print every nth warning about very large
59 block allocations, starting with the nth one. Small values
60 of n are generally benign, in that a bounded number of
61 such warnings generally indicate at most a bounded leak.
62 For best results it should be set at 1 during testing.
63 Default is 5. Very large numbers effectively disable the
64 warning.
65
66GC_IGNORE_GCJ_INFO - Ignore the type descriptors implicitly supplied by
67 GC_gcj_malloc and friends. This is useful for debugging
68 descriptor generation problems, and possibly for
69 temporarily working around such problems. It forces a
70 fully conservative scan of all heap objects except
71 those known to be pointerfree, and may thus have other
72 adverse effects.
73
74GC_PRINT_BACK_HEIGHT - Print max length of chain through unreachable objects
75 ending in a reachable one. If this number remains
76 bounded, then the program is "GC robust". This ensures
77 that a fixed number of misidentified pointers can only
78 result in a bounded space leak. This currently only
79 works if debugging allocation is used throughout.
80 It increases GC space and time requirements appreciably.
81 This feature is still somewhat experimental, and requires
82 that the collector have been built with MAKE_BACK_GRAPH
83 defined. For details, see Boehm, "Bounding Space Usage
84 of Conservative Garbage Collectors", POPL 2001, or
85 http://lib.hpl.hp.com/techpubs/2001/HPL-2001-251.html .
86
87GC_RETRY_SIGNALS, GC_NO_RETRY_SIGNALS - Try to compensate for lost
88 thread suspend signals in linux_threads.c. On by
89 default for GC_OSF1_THREADS, off otherwise. Note
90 that this does not work around a possible loss of
91 thread restart signals. This seems to be necessary for
92 some versions of Tru64. Since we've previously seen
93 similar issues on some other operating systems, it
94 was turned into a runtime flag to enable last-minute
95 work-arounds.
96
97GC_IGNORE_FB[=<n>] - (Win32 only.) Try to avoid treating a mapped
98 frame buffer as part of the root set. Certain (higher end?)
99 graphics cards seems to result in the graphics memory mapped
100 into the user address space as writable memory.
101 Unfortunately, there seems to be no systematic way to
102 identify such memory. Setting the environment variable to n
103 causes the collector to ignore mappings longer than n MB.
104 The default value of n is currently 15. (This should cover
105 a 16 MB graphics card, since the mapping appears to be slightly
106 shorter than all of graphics memory. It will fail if a dll
107 writes pointers to collectable objects into a data segment
108 whose length is >= 15MB. Empirically that's rare, but
109 certainly possible.) WARNING: Security sensitive applications
110 should probably disable this feature by setting
111 GC_disallow_ignore_fb, or by building with -DNO_GETENV,
112 since small values could force collection of reachable
113 objects, which is conceivably a (difficult to exploit)
114 security hole. GC_IGNORE_FB values less than 3 MB
115 are never honored, eliminating this risk for most,
116 but not all, applications. This feature is likely to disappear
117 if/when we find a less disgusting "solution".
118 IN VERSION 6.4 AND LATER, THIS SHOULD BE UNNECESSARY.
119
120The following turn on runtime flags that are also program settable. Checked
121only during initialization. We expect that they will usually be set through
122other means, but this may help with debugging and testing:
123
124GC_ENABLE_INCREMENTAL - Turn on incremental collection at startup. Note that,
125 depending on platform and collector configuration, this
126 may involve write protecting pieces of the heap to
127 track modifications. These pieces may include pointerfree
128 objects or not. Although this is intended to be
129 transparent, it may cause unintended system call failures.
130 Use with caution.
131
132GC_PAUSE_TIME_TARGET - Set the desired garbage collector pause time in msecs.
133 This only has an effect if incremental collection is
134 enabled. If a collection requires appreciably more time
135 than this, the client will be restarted, and the collector
136 will need to do additional work to compensate. The
137 special value "999999" indicates that pause time is
138 unlimited, and the incremental collector will behave
139 completely like a simple generational collector. If
140 the collector is configured for parallel marking, and
141 run on a multiprocessor, incremental collection should
142 only be used with unlimited pause time.
143
144GC_FIND_LEAK - Turns on GC_find_leak and thus leak detection. Forces a
145 collection at program termination to detect leaks that would
146 otherwise occur after the last GC.
147
148GC_ALL_INTERIOR_POINTERS - Turns on GC_all_interior_pointers and thus interior
149 pointer recognition.
150
151GC_DONT_GC - Turns off garbage collection. Use cautiously.
Note: See TracBrowser for help on using the repository browser.