libgc/doc/README.environment

   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 and win32.
   4
   5 GC_INITIAL_HEAP_SIZE=<bytes> -  Initial heap size in bytes.  May speed up
   6                                 process start-up.
   7
   8 GC_MAXIMUM_HEAP_SIZE=<bytes> - Maximum collected heap size.
   9
  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
  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
  29 GC_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
  37 GC_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
  42 GC_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
  49 GC_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
  54 GC_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
  58 GC_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
  66 GC_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
  74 GC_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
  87 GC_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
  97 GC_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
 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 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
 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_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
 148 GC_ALL_INTERIOR_POINTERS - Turns on GC_all_interior_pointers and thus interior
 149                            pointer recognition.
 150
 151 GC_DONT_GC - Turns off garbage collection.  Use cautiously.