gc-7.2/doc/README.environment

   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 GC_dump() 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_BACKTRACES=<n> - Generate n random back-traces (for heap profiling) after
  38                     each GC.  Collector must have been built with
  39                     KEEP_BACK_PTRS.  This won't generate useful output unless
  40                     most objects in the heap were allocated through debug
  41                     allocators.  This is intended to be only a statistical
  42                     sample;  individual traces may be erroneous due to
  43                     concurrent heap mutation.
  44
  45 GC_PRINT_ADDRESS_MAP - Linux only.  Dump /proc/self/maps, i.e. various address
  46                        maps for the process, to stderr on every GC.  Useful for
  47                        mapping root addresses to source for deciphering leak
  48                        reports.
  49
  50 GC_NPROCS=<n> - Linux w/threads only.  Explicitly sets the number of processors
  51                 that the GC should expect to use.  Note that setting this to 1
  52                 when multiple processors are available will preserve
  53                 correctness, but may lead to really horrible performance,
  54                 since the lock implementation will immediately yield without
  55                 first spinning.
  56
  57 GC_MARKERS=<n> - Only if compiled with PARALLEL_MARK.  Set the number
  58                 of marker threads.  This is normally set to the number of
  59                 processors.  It is safer to adjust GC_MARKERS than GC_NPROCS,
  60                 since GC_MARKERS has no impact on the lock implementation.
  61
  62 GC_NO_BLACKLIST_WARNING - Prevents the collector from issuing
  63                 warnings about allocations of very large blocks.
  64                 Deprecated.  Use GC_LARGE_ALLOC_WARN_INTERVAL instead.
  65
  66 GC_LARGE_ALLOC_WARN_INTERVAL=<n> - Print every nth warning about very large
  67                 block allocations, starting with the nth one.  Small values
  68                 of n are generally benign, in that a bounded number of
  69                 such warnings generally indicate at most a bounded leak.
  70                 For best results it should be set at 1 during testing.
  71                 Default is 5.  Very large numbers effectively disable the
  72                 warning.
  73
  74 GC_IGNORE_GCJ_INFO - Ignore the type descriptors implicitly supplied by
  75                      GC_gcj_malloc and friends.  This is useful for debugging
  76                      descriptor generation problems, and possibly for
  77                      temporarily working around such problems.  It forces a
  78                      fully conservative scan of all heap objects except
  79                      those known to be pointer-free, and may thus have other
  80                      adverse effects.
  81
  82 GC_PRINT_BACK_HEIGHT - Print max length of chain through unreachable objects
  83                      ending in a reachable one.  If this number remains
  84                      bounded, then the program is "GC robust".  This ensures
  85                      that a fixed number of misidentified pointers can only
  86                      result in a bounded space leak.  This currently only
  87                      works if debugging allocation is used throughout.
  88                      It increases GC space and time requirements appreciably.
  89                      This feature is still somewhat experimental, and requires
  90                      that the collector have been built with MAKE_BACK_GRAPH
  91                      defined.  For details, see Boehm, "Bounding Space Usage
  92                      of Conservative Garbage Collectors", POPL 2001, or
  93                      http://lib.hpl.hp.com/techpubs/2001/HPL-2001-251.html .
  94
  95 GC_RETRY_SIGNALS, GC_NO_RETRY_SIGNALS - Try to compensate for lost
  96                      thread suspend signals in linux_threads.c.  On by
  97                      default for GC_OSF1_THREADS, off otherwise.  Note
  98                      that this does not work around a possible loss of
  99                      thread restart signals.  This seems to be necessary for
 100                      some versions of Tru64.  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.
 104
 105 GC_USE_GETWRITEWATCH=<n> - Only if MPROTECT_VDB and GWW_VDB are both defined
 106                      (Win32 only).  Explicitly specify which strategy of
 107                      keeping track of dirtied pages should be used.
 108                      If n=0 then GetWriteWatch() is not used (falling back to
 109                      protecting pages and catching memory faults strategy)
 110                      else the collector tries to use GetWriteWatch-based
 111                      strategy (GWW_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 msecs.
 129                      This only has an effect if incremental collection is
 130                      enabled.  If a collection requires appreciably more time
 131                      than this, the client will be restarted, and the collector
 132                      will need to do additional work to compensate.  The
 133                      special value "999999" indicates that pause time is
 134                      unlimited, and the incremental collector will behave
 135                      completely like a simple generational collector.  If
 136                      the collector is configured for parallel marking, and
 137                      run on a multiprocessor, incremental collection should
 138                      only be used with unlimited pause time.
 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                        leak-finding 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.