readme.environment

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

The garbage collector looks at a number of environment variables which are
then used to affect its operation.  These are examined only on Un*x-like
platforms and win32.

GC_INITIAL_HEAP_SIZE=<bytes> -	Initial heap size in bytes.  May speed up
				process start-up.

GC_MAXIMUM_HEAP_SIZE=<bytes> - Maximum collected heap size.

GC_LOOP_ON_ABORT - Causes the collector abort routine to enter a tight loop.
		   This may make it easier to debug, such a process, especially
		   for multithreaded platforms that don't produce usable core
		   files, or if a core file would be too large.  On some
		   platforms, this also causes SIGSEGV to be caught and
		   result in an infinite loop in a handler, allowing
		   similar debugging techniques.

GC_PRINT_STATS - Turn on GC logging.  Not functional with -DSMALL_CONFIG.

GC_LOG_FILE - The name of the log file.  Stderr by default.

GC_PRINT_VERBOSE_STATS - Turn on even more logging.

GC_DUMP_REGULARLY - Generate a GC debugging dump GC_dump() on startup
		    and during every collection.  Very verbose.  Useful
		    if you have a bug to report, but please include only the
		    last complete dump.

GC_BACKTRACES=<n> - Generate n random backtraces (for heap profiling) after
		    each GC.  Collector must have been built with
		    KEEP_BACK_PTRS.  This won't generate useful output unless
		    most objects in the heap were allocated through debug
		    allocators.  This is intended to be only a statistical
		    sample;  individual traces may be erroneous due to
		    concurrent heap mutation.

GC_PRINT_ADDRESS_MAP - Linux only.  Dump /proc/self/maps, i.e. various address
		       maps for the process, to stderr on every GC.  Useful for
		       mapping root addresses to source for deciphering leak
		       reports.

GC_NPROCS=<n> - Linux w/threads only.  Explicitly sets the number of processors
	        that the GC should expect to use.  Note that setting this to 1
		when multiple processors are available will preserve
		correctness, but may lead to really horrible performance,
		since the lock implementation will immediately yield without
		first spinning.

GC_MARKERS=<n> - Linux w/threads and parallel marker only.  Set the number
		of marker threads.  This is normally set to the number of
		processors.  It is safer to adjust GC_MARKERS than GC_NPROCS,
		since GC_MARKERS has no impact on the lock implementation.

GC_NO_BLACKLIST_WARNING - Prevents the collector from issuing
		warnings about allocations of very large blocks.
		Deprecated.  Use GC_LARGE_ALLOC_WARN_INTERVAL instead.

GC_LARGE_ALLOC_WARN_INTERVAL=<n> - Print every nth warning about very large
		block allocations, starting with the nth one.  Small values
		of n are generally benign, in that a bounded number of
		such warnings generally indicate at most a bounded leak.
		For best results it should be set at 1 during testing.
		Default is 5.  Very large numbers effectively disable the
		warning.

GC_IGNORE_GCJ_INFO - Ignore the type descriptors implicitly supplied by
		     GC_gcj_malloc and friends.  This is useful for debugging
		     descriptor generation problems, and possibly for
		     temporarily working around such problems.  It forces a
		     fully conservative scan of all heap objects except
		     those known to be pointerfree, and may thus have other
		     adverse effects.

GC_PRINT_BACK_HEIGHT - Print max length of chain through unreachable objects
		     ending in a reachable one.  If this number remains
		     bounded, then the program is "GC robust".  This ensures
		     that a fixed number of misidentified pointers can only
		     result in a bounded space leak.  This currently only
		     works if debugging allocation is used throughout.
		     It increases GC space and time requirements appreciably.
		     This feature is still somewhat experimental, and requires
		     that the collector have been built with MAKE_BACK_GRAPH
		     defined.  For details, see Boehm, "Bounding Space Usage
		     of Conservative Garbage Collectors", POPL 2001, or
		     http://lib.hpl.hp.com/techpubs/2001/HPL-2001-251.html .

GC_RETRY_SIGNALS, GC_NO_RETRY_SIGNALS - Try to compensate for lost
		     thread suspend signals in linux_threads.c.  On by
		     default for GC_OSF1_THREADS, off otherwise.  Note 
		     that this does not work around a possible loss of
		     thread restart signals.  This seems to be necessary for
		     some versions of Tru64.  Since we've previously seen
		     similar issues on some other operating systems, it
		     was turned into a runtime flag to enable last-minute
		     work-arounds.

The following turn on runtime flags that are also program settable.  Checked
only during initialization.  We expect that they will usually be set through
other means, but this may help with debugging and testing:

GC_ENABLE_INCREMENTAL - Turn on incremental collection at startup.  Note that,
		     depending on platform and collector configuration, this
		     may involve write protecting pieces of the heap to
		     track modifications.  These pieces may include pointerfree
		     objects or not.  Although this is intended to be
		     transparent, it may cause unintended system call failures.
		     Use with caution.

GC_PAUSE_TIME_TARGET - Set the desired garbage collector pause time in msecs.
		     This only has an effect if incremental collection is
		     enabled.  If a collection requires appreciably more time
		     than this, the client will be restarted, and the collector
		     will need to do additional work to compensate.  The
		     special value "999999" indicates that pause time is
		     unlimited, and the incremental collector will behave
		     completely like a simple generational collector.  If
		     the collector is configured for parallel marking, and
		     run on a multiprocessor, incremental collection should
		     only be used with unlimited pause time.

GC_FIND_LEAK - Turns on GC_find_leak and thus leak detection.  Forces a
	       collection at program termination to detect leaks that would
	       otherwise occur after the last GC.

GC_ALL_INTERIOR_POINTERS - Turns on GC_all_interior_pointers and thus interior
			   pointer recognition.

GC_DONT_GC - Turns off garbage collection.  Use cautiously.

GC_TRACE=addr - Intended for collector debugging.  Requires that the collector
		have been built with ENABLE_TRACE defined.  Causes the debugger
		to log information about the tracing of address ranges containing
		addr.  Typically addr is the address that contains a pointer to
		an object that mysteriously failed to get marked.  Addr must be
		specified as a hexadecimal integer.