X-Git-Url: http://wien.tomnetworks.com/gitweb/?p=hs-boehmgc.git;a=blobdiff_plain;f=gc-7.2%2Fdoc%2FREADME.environment;fp=gc-7.2%2Fdoc%2FREADME.environment;h=866e905591bfe92cc4eb2e8f4487c8f7c42d3fb2;hp=0000000000000000000000000000000000000000;hb=324587ba93dc77f37406d41fd2a20d0e0d94fb1d;hpb=2a4ea609491b225a1ceb06da70396e93916f137a diff --git a/gc-7.2/doc/README.environment b/gc-7.2/doc/README.environment new file mode 100644 index 0000000..866e905 --- /dev/null +++ b/gc-7.2/doc/README.environment @@ -0,0 +1,183 @@ +The garbage collector looks at a number of environment variables which are, +then, used to affect its operation. + +GC_INITIAL_HEAP_SIZE= - Initial heap size in bytes. May speed up + process start-up. Optionally, may be + specified with a multiplier ('k', 'M' or 'G') + suffix. + +GC_MAXIMUM_HEAP_SIZE= - Maximum collected heap size. Allows + a multiplier suffix. + +GC_LOOP_ON_ABORT - Causes the collector abort routine to enter a tight loop. + This may make it easier to debug, such a process, especially + for multi-threaded platforms that don't produce usable core + files, or if a core file would be too large. On some + platforms, this also causes SIGSEGV to be caught and + result in an infinite loop in a handler, allowing + similar debugging techniques. + +GC_PRINT_STATS - Turn on GC logging. Not functional with SMALL_CONFIG. + +GC_LOG_FILE - The name of the log file. Stderr by default. Not functional + with SMALL_CONFIG. + +GC_ONLY_LOG_TO_FILE - Turns off redirection of GC stdout and stderr to the log + file specified by GC_LOG_FILE. Has no effect unless + GC_LOG_FILE is set. Not functional with SMALL_CONFIG. + +GC_PRINT_VERBOSE_STATS - Turn on even more logging. Not functional with + SMALL_CONFIG. + +GC_DUMP_REGULARLY - Generate a GC debugging dump GC_dump() on startup + and during every collection. Very verbose. Useful + if you have a bug to report, but please include only the + last complete dump. + +GC_BACKTRACES= - Generate n random back-traces (for heap profiling) after + each GC. Collector must have been built with + KEEP_BACK_PTRS. This won't generate useful output unless + most objects in the heap were allocated through debug + allocators. This is intended to be only a statistical + sample; individual traces may be erroneous due to + concurrent heap mutation. + +GC_PRINT_ADDRESS_MAP - Linux only. Dump /proc/self/maps, i.e. various address + maps for the process, to stderr on every GC. Useful for + mapping root addresses to source for deciphering leak + reports. + +GC_NPROCS= - Linux w/threads only. Explicitly sets the number of processors + that the GC should expect to use. Note that setting this to 1 + when multiple processors are available will preserve + correctness, but may lead to really horrible performance, + since the lock implementation will immediately yield without + first spinning. + +GC_MARKERS= - Only if compiled with PARALLEL_MARK. Set the number + of marker threads. This is normally set to the number of + processors. It is safer to adjust GC_MARKERS than GC_NPROCS, + since GC_MARKERS has no impact on the lock implementation. + +GC_NO_BLACKLIST_WARNING - Prevents the collector from issuing + warnings about allocations of very large blocks. + Deprecated. Use GC_LARGE_ALLOC_WARN_INTERVAL instead. + +GC_LARGE_ALLOC_WARN_INTERVAL= - Print every nth warning about very large + block allocations, starting with the nth one. Small values + of n are generally benign, in that a bounded number of + such warnings generally indicate at most a bounded leak. + For best results it should be set at 1 during testing. + Default is 5. Very large numbers effectively disable the + warning. + +GC_IGNORE_GCJ_INFO - Ignore the type descriptors implicitly supplied by + GC_gcj_malloc and friends. This is useful for debugging + descriptor generation problems, and possibly for + temporarily working around such problems. It forces a + fully conservative scan of all heap objects except + those known to be pointer-free, and may thus have other + adverse effects. + +GC_PRINT_BACK_HEIGHT - Print max length of chain through unreachable objects + ending in a reachable one. If this number remains + bounded, then the program is "GC robust". This ensures + that a fixed number of misidentified pointers can only + result in a bounded space leak. This currently only + works if debugging allocation is used throughout. + It increases GC space and time requirements appreciably. + This feature is still somewhat experimental, and requires + that the collector have been built with MAKE_BACK_GRAPH + defined. For details, see Boehm, "Bounding Space Usage + of Conservative Garbage Collectors", POPL 2001, or + http://lib.hpl.hp.com/techpubs/2001/HPL-2001-251.html . + +GC_RETRY_SIGNALS, GC_NO_RETRY_SIGNALS - Try to compensate for lost + thread suspend signals in linux_threads.c. On by + default for GC_OSF1_THREADS, off otherwise. Note + that this does not work around a possible loss of + thread restart signals. This seems to be necessary for + some versions of Tru64. Since we've previously seen + similar issues on some other operating systems, it + was turned into a runtime flag to enable last-minute + work-arounds. + +GC_USE_GETWRITEWATCH= - Only if MPROTECT_VDB and GWW_VDB are both defined + (Win32 only). Explicitly specify which strategy of + keeping track of dirtied pages should be used. + If n=0 then GetWriteWatch() is not used (falling back to + protecting pages and catching memory faults strategy) + else the collector tries to use GetWriteWatch-based + strategy (GWW_VDB) first if available. + +GC_DISABLE_INCREMENTAL - Ignore runtime requests to enable incremental GC. + Useful for debugging. + +The following turn on runtime flags that are also program settable. Checked +only during initialization. We expect that they will usually be set through +other means, but this may help with debugging and testing: + +GC_ENABLE_INCREMENTAL - Turn on incremental collection at startup. Note that, + depending on platform and collector configuration, this + may involve write protecting pieces of the heap to + track modifications. These pieces may include + pointer-free objects or not. Although this is intended + to be transparent, it may cause unintended system call + failures. Use with caution. + +GC_PAUSE_TIME_TARGET - Set the desired garbage collector pause time in msecs. + This only has an effect if incremental collection is + enabled. If a collection requires appreciably more time + than this, the client will be restarted, and the collector + will need to do additional work to compensate. The + special value "999999" indicates that pause time is + unlimited, and the incremental collector will behave + completely like a simple generational collector. If + the collector is configured for parallel marking, and + run on a multiprocessor, incremental collection should + only be used with unlimited pause time. + +GC_FULL_FREQUENCY - Set the desired number of partial collections between full + collections. Matters only if GC_incremental is set. + Not functional with SMALL_CONFIG. + +GC_FREE_SPACE_DIVISOR - Set GC_free_space_divisor to the indicated value. + Setting it to larger values decreases space consumption + and increases GC frequency. + +GC_UNMAP_THRESHOLD - Set the desired memory blocks unmapping threshold (the + number of sequential garbage collections for which + a candidate block for unmapping should remain free). The + special value "0" completely disables unmapping. + +GC_FORCE_UNMAP_ON_GCOLLECT - Turn "unmap as much as possible on explicit GC" + mode on (overrides the default value). Has no effect on + implicitly-initiated garbage collections. Has no effect if + memory unmapping is disabled (or not compiled in) or if the + unmapping threshold is 1. + +GC_FIND_LEAK - Turns on GC_find_leak and thus leak detection. Forces a + collection at program termination to detect leaks that would + otherwise occur after the last GC. + +GC_FINDLEAK_DELAY_FREE - Turns on deferred freeing of objects in the + leak-finding mode (see the corresponding macro + description for more information). + +GC_ABORT_ON_LEAK - Causes the application to be terminated once leaked or + smashed objects are found. + +GC_ALL_INTERIOR_POINTERS - Turns on GC_all_interior_pointers and thus interior + pointer recognition. + +GC_DONT_GC - Turns off garbage collection. Use cautiously. + +GC_USE_ENTIRE_HEAP - Set desired GC_use_entire_heap value at start-up. See + the similar macro description in README.macros. + +GC_TRACE=addr - Intended for collector debugging. Requires that the collector + have been built with ENABLE_TRACE defined. Causes the debugger + to log information about the tracing of address ranges + containing addr. Typically addr is the address that contains + a pointer to an object that mysteriously failed to get marked. + Addr must be specified as a hexadecimal integer.