Return to README.environment CVS log

Up to [local] / OpenXM_contrib2 / asir2000 / gc / doc

Annotation of OpenXM_contrib2/asir2000/gc/doc/README.environment, Revision 1.2

1.1       noro        1: The garbage collector looks at a number of environment variables which are
                      2: then used to affect its operation.  These are examined only on Un*x-like
                      3: platforms.
                      4:
                      5: GC_INITIAL_HEAP_SIZE=<bytes> - Initial heap size in bytes.  May speed up
                      6:                                process start-up.
                      7:
1.2     ! noro        8: GC_MAXIMUM_HEAP_SIZE=<bytes> - Maximum collected heap size.
        !             9:
1.1       noro       10: GC_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:
                     18: GC_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:
1.2     ! noro       24: GC_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:
1.1       noro       29: GC_PRINT_ADDRESS_MAP - Linux only.  Dump /proc/self/maps, i.e. various address
                     30:                       maps for the process, to stderr on every GC.  Useful for
                     31:                       mapping root addresses to source for deciphering leak
                     32:                       reports.
                     33:
                     34: GC_NPROCS=<n> - Linux w/threads only.  Explicitly sets the number of processors
                     35:                that the GC should expect to use.  Note that setting this to 1
                     36:                when multiple processors are available will preserve
                     37:                correctness, but may lead to really horrible performance,
                     38:                since the lock implementation will immediately yield without
                     39:                first spinning.
                     40:
                     41: GC_MARKERS=<n> - Linux w/threads and parallel marker only.  Set the number
                     42:                of marker threads.  This is normaly set to the number of
                     43:                processors.  It is safer to adjust GC_MARKERS than GC_NPROCS,
                     44:                since GC_MARKERS has no impact on the lock implementation.
                     45:
                     46: GC_NO_BLACKLIST_WARNING - Prevents the collector from issuing
                     47:                warnings about allocations of very large blocks.
                     48:                Deprecated.  Use GC_LARGE_ALLOC_WARN_INTERVAL instead.
                     49:
                     50: GC_LARGE_ALLOC_WARN_INTERVAL=<n> - Print every nth warning about very large
                     51:                block allocations, starting with the nth one.  Small values
                     52:                of n are generally benign, in that a bounded number of
                     53:                such warnings generally indicate at most a bounded leak.
                     54:                For best results it should be set at 1 during testing.
                     55:                Default is 5.  Very large numbers effectively disable the
                     56:                warning.
                     57:
                     58: GC_IGNORE_GCJ_INFO - Ignore the type descriptors implicitly supplied by
                     59:                     GC_gcj_malloc and friends.  This is useful for debugging
                     60:                     descriptor generation problems, and possibly for
                     61:                     temporarily working around such problems.  It forces a
                     62:                     fully conservative scan of all heap objects except
                     63:                     those known to be pointerfree, and may thus have other
                     64:                     adverse effects.
                     65:
                     66: GC_PRINT_BACK_HEIGHT - Print max length of chain through unreachable objects
                     67:                     ending in a reachable one.  If this number remains
                     68:                     bounded, then the program is "GC robust".  This ensures
                     69:                     that a fixed number of misidentified pointers can only
                     70:                     result in a bounded space leak.  This currently only
                     71:                     works if debugging allocation is used throughout.
                     72:                     It increases GC space and time requirements appreciably.
                     73:                     This feature is still somewhat experimental, and requires
                     74:                     that the collector have been built with MAKE_BACK_GRAPH
                     75:                     defined.  For details, see Boehm, "Bounding Space Usage
                     76:                     of Conservative Garbage Collectors", POPL 2001, or
                     77:                     http://lib.hpl.hp.com/techpubs/2001/HPL-2001-251.html .
                     78:
1.2     ! noro       79: GC_RETRY_SIGNALS, GC_NO_RETRY_SIGNALS - Try to compensate for lost
        !            80:                     thread suspend signals in linux_threads.c.  On by
        !            81:                     default for GC_OSF1_THREADS, off otherwise.  Note
        !            82:                     that this does not work around a possible loss of
        !            83:                     thread restart signals.  This seems to be necessary for
        !            84:                     some versions of Tru64.  Since we've previously seen
        !            85:                     similar issues on some other operating systems, it
        !            86:                     was turned into a runtime flag to enable last-minute
        !            87:                     work-arounds.
        !            88:
1.1       noro       89: The following turn on runtime flags that are also program settable.  Checked
                     90: only during initialization.  We expect that they will usually be set through
                     91: other means, but this may help with debugging and testing:
                     92:
                     93: GC_ENABLE_INCREMENTAL - Turn on incremental collection at startup.  Note that,
                     94:                     depending on platform and collector configuration, this
                     95:                     may involve write protecting pieces of the heap to
                     96:                     track modifications.  These pieces may include pointerfree
                     97:                     objects or not.  Although this is intended to be
                     98:                     transparent, it may cause unintended system call failures.
                     99:                     Use with caution.
                    100:
                    101: GC_PAUSE_TIME_TARGET - Set the desired garbage collector pause time in msecs.
                    102:                     This only has an effect if incremental collection is
                    103:                     enabled.  If a collection requires appreciably more time
                    104:                     than this, the client will be restarted, and the collector
                    105:                     will need to do additional work to compensate.  The
                    106:                     special value "999999" indicates that pause time is
                    107:                     unlimited, and the incremental collector will behave
                    108:                     completely like a simple generational collector.  If
                    109:                     the collector is configured for parallel marking, and
                    110:                     run on a multiprocessor, incremental collection should
                    111:                     only be used with unlimited pause time.
                    112:
1.2     ! noro      113: GC_FIND_LEAK - Turns on GC_find_leak and thus leak detection.  Forces a
        !           114:               collection at program termination to detect leaks that would
        !           115:               otherwise occur after the last GC.
1.1       noro      116:
                    117: GC_ALL_INTERIOR_POINTERS - Turns on GC_all_interior_pointers and thus interior
                    118:                           pointer recognition.
                    119:
                    120: GC_DONT_GC - Turns off garbage collection.  Use cautiously.