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.  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
   8 GC_LOOP_ON_ABORT - Causes the collector abort routine to enter a tight loop.
   9                    This may make it easier to debug, such a process, especially
  10                    for multithreaded platforms that don't produce usable core
  11                    files, or if a core file would be too large.  On some
  12                    platforms, this also causes SIGSEGV to be caught and
  13                    result in an infinite loop in a handler, allowing
  14                    similar debugging techniques.
  15
  16 GC_PRINT_STATS - Turn on as much logging as is easily feasible without
  17                  adding signifcant runtime overhead.  Doesn't work if
  18                  the collector is built with SMALL_CONFIG.  Overridden
  19                  by setting GC_quiet.  On by default if the collector
  20                  was built without -DSILENT.
  21
  22 GC_PRINT_ADDRESS_MAP - Linux only.  Dump /proc/self/maps, i.e. various address
  23                        maps for the process, to stderr on every GC.  Useful for
  24                        mapping root addresses to source for deciphering leak
  25                        reports.
  26
  27 GC_NPROCS=<n> - Linux w/threads only.  Explicitly sets the number of processors
  28                 that the GC should expect to use.  Note that setting this to 1
  29                 when multiple processors are available will preserve
  30                 correctness, but may lead to really horrible performance.
  31
  32 GC_NO_BLACKLIST_WARNING - Prevents the collector from issuing
  33                 warnings about allocations of very large blocks.
  34                 Deprecated.  Use GC_LARGE_ALLOC_WARN_INTERVAL instead.
  35
  36 GC_LARGE_ALLOC_WARN_INTERVAL=<n> - Print every nth warning about very large
  37                 block allocations, starting with the nth one.  Small values
  38                 of n are generally benign, in that a bounded number of
  39                 such warnings generally indicate at most a bounded leak.
  40                 For best results it should be set at 1 during testing.
  41                 Default is 5.  Very large numbers effectively disable the
  42                 warning.
  43
  44 GC_IGNORE_GCJ_INFO - Ignore the type descriptors implicitly supplied by
  45                      GC_gcj_malloc and friends.  This is useful for debugging
  46                      descriptor generation problems, and possibly for
  47                      temporarily working around such problems.  It forces a
  48                      fully conservative scan of all heap objects except
  49                      those known to be pointerfree, and may thus have other
  50                      adverse effects.
  51
  52 GC_PRINT_BACK_HEIGHT - Print max length of chain through unreachable objects
  53                      ending in a reachable one.  If this number remains
  54                      bounded, then the program is "GC robust".  This ensures
  55                      that a fixed number of misidentified pointers can only
  56                      result in a bounded space leak.  This currently only
  57                      works if debugging allocation is used throughout.
  58                      It increases GC space and time requirements appreciably.
  59                      This feature is still somewhat experimental, and requires
  60                      that the collector have been built with MAKE_BACK_GRAPH
  61                      defined.  For details, see Boehm, "Bounding Space Usage
  62                      of Conservative Garbage Collectors", POPL 2001, or
  63                      http://lib.hpl.hp.com/techpubs/2001/HPL-2001-251.html .
  64
  65 GC_ENABLE_INCREMENTAL - Turn on incremental collection at startup.  Note that,
  66                      depending on platform and collector configuration, this
  67                      may involve write protecting pieces of the heap to
  68                      track modifications.  These pieces may include pointerfree
  69                      objects or not.  Although this is intended to be
  70                      transparent, it may cause unintended system call failures.
  71                      Use with caution.
  72
  73 GC_PAUSE_TIME_TARGET - Set the desired garbage collector pause time in msecs.
  74                      This only has an effect if incremental collection is enabled.
  75                      If a collection requires appreciably more time than this,
  76                      the client will be restarted, and the collector will need
  77                      to do additional work to compensate.  The special value
  78                      "999999" indicates that pause time is unlimited, and the
  79                      incremental collector will behave completely like a
  80                      simple generational collector.  If the collector is
  81                      configured for parallel marking, and run on a multiprocessor,
  82                      incremental collection should only be used with unlimited
  83                      pause time.
  84
  85 The following turn on runtime flags that are also program settable.  Checked
  86 only during initialization.  We expect that they will usually be set through
  87 other means, but this may help with debugging and testing:
  88
  89 GC_FIND_LEAK - Turns on GC_find_leak and thus leak detection.
  90
  91 GC_ALL_INTERIOR_POINTERS - Turns on GC_all_interior_pointers and thus interior
  92                            pointer recognition.
  93
  94 GC_DONT_GC - Turns off garbage collection.  Use cautiously.