diff gc/doc/README.environment @ 51488:5de98dce4bd1

*** empty log message ***

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/gc/doc/README.environment	Thu Jun 05 17:49:22 2003 +0000
@@ -0,0 +1,120 @@
+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.
+
+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 as much logging as is easily feasible without
+		 adding signifcant runtime overhead.  Doesn't work if
+		 the collector is built with SMALL_CONFIG.  Overridden
+		 by setting GC_quiet.  On by default if the collector
+		 was built without -DSILENT.
+
+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_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 normaly 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.