boehm-gc/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_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.  For details, see Boehm, "Bounding Space Usage
  96                      of Conservative Garbage Collectors", POPL 2001, or
  97                      http://lib.hpl.hp.com/techpubs/2001/HPL-2001-251.html .
  98
  99 GC_RETRY_SIGNALS, GC_NO_RETRY_SIGNALS - Try to compensate for lost
 100                      thread suspend signals in linux_threads.c.  On by
 101                      default for GC_OSF1_THREADS, off otherwise.  Note
 102                      that this does not work around a possible loss of
 103                      thread restart signals.  This seems to be necessary for
 104                      some versions of Tru64.  Since we've previously seen
 105                      similar issues on some other operating systems, it
 106                      was turned into a runtime flag to enable last-minute
 107                      work-arounds.
 108
 109 GC_USE_GETWRITEWATCH=<n> - Only if MPROTECT_VDB and GWW_VDB are both defined
 110                      (Win32 only).  Explicitly specify which strategy of
 111                      keeping track of dirtied pages should be used.
 112                      If n=0 then GetWriteWatch() is not used (falling back to
 113                      protecting pages and catching memory faults strategy)
 114                      else the collector tries to use GetWriteWatch-based
 115                      strategy (GWW_VDB) first if available.
 116
 117 GC_DISABLE_INCREMENTAL - Ignore runtime requests to enable incremental GC.
 118                      Useful for debugging.
 119
 120 The following turn on runtime flags that are also program settable.  Checked
 121 only during initialization.  We expect that they will usually be set through
 122 other means, but this may help with debugging and testing:
 123
 124 GC_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
 128                      pointer-free objects or not.  Although this is intended
 129                      to be transparent, it may cause unintended system call
 130                      failures.  Use with caution.
 131
 132 GC_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
 144 GC_FULL_FREQUENCY - Set the desired number of partial collections between full
 145                     collections.  Matters only if GC_incremental is set.
 146                     Not functional with SMALL_CONFIG.
 147
 148 GC_FREE_SPACE_DIVISOR - Set GC_free_space_divisor to the indicated value.
 149                       Setting it to larger values decreases space consumption
 150                       and increases GC frequency.
 151
 152 GC_UNMAP_THRESHOLD - Set the desired memory blocks unmapping threshold (the
 153                    number of sequential garbage collections for which
 154                    a candidate block for unmapping should remain free).  The
 155                    special value "0" completely disables unmapping.
 156
 157 GC_FORCE_UNMAP_ON_GCOLLECT - Turn "unmap as much as possible on explicit GC"
 158                 mode on (overrides the default value).  Has no effect on
 159                 implicitly-initiated garbage collections.  Has no effect if
 160                 memory unmapping is disabled (or not compiled in) or if the
 161                 unmapping threshold is 1.
 162
 163 GC_FIND_LEAK - Turns on GC_find_leak and thus leak detection.  Forces a
 164                collection at program termination to detect leaks that would
 165                otherwise occur after the last GC.
 166
 167 GC_FINDLEAK_DELAY_FREE - Turns on deferred freeing of objects in the
 168                        leak-finding mode (see the corresponding macro
 169                        description for more information).
 170
 171 GC_ABORT_ON_LEAK - Causes the application to be terminated once leaked or
 172                    smashed objects are found.
 173
 174 GC_ALL_INTERIOR_POINTERS - Turns on GC_all_interior_pointers and thus interior
 175                            pointer recognition.
 176
 177 GC_DONT_GC - Turns off garbage collection.  Use cautiously.
 178
 179 GC_USE_ENTIRE_HEAP - Set desired GC_use_entire_heap value at start-up.  See
 180                      the similar macro description in README.macros.
 181
 182 GC_TRACE=addr - Intended for collector debugging.  Requires that the collector
 183                 have been built with ENABLE_TRACE defined.  Causes the debugger
 184                 to log information about the tracing of address ranges
 185                 containing addr.  Typically addr is the address that contains
 186                 a pointer to an object that mysteriously failed to get marked.
 187                 Addr must be specified as a hexadecimal integer.