[project @ 2001-08-13 16:33:43 by simonmar]

[ghc-hetmet.git] / ghc / docs / users_guide / runtime_control.sgml

diff --git a/ghc/docs/users_guide/runtime_control.sgml b/ghc/docs/users_guide/runtime_control.sgml
index b7b6fab..bbf4dc3 100644 (file)
--- a/ghc/docs/users_guide/runtime_control.sgml
+++ b/ghc/docs/users_guide/runtime_control.sgml
@@ -60,10 +60,35 @@
   <literal>+RTS -M128m -RTS</literal>
   to the command line.</para>
 
+  <sect2 id="rts-optinos-environment">
+    <title>Setting global RTS options</title>
+
+    <indexterm><primary>RTS options</primary><secondary>from the environment</secondary></indexterm>
+    <indexterm><primary>environment variable</primary><secondary>for
+    setting RTS options</secondary></indexterm>
+
+    <para>RTS options are also taken from the environment variable
+    <envar>GHCRTS</envar><indexterm><primary><envar>GHCRTS</envar></primary>
+      </indexterm>.  For example, to set the maximum heap size
+    to 128M for all GHC-compiled programs (using an
+    <literal>sh</literal>-like shell):</para>
+
+<screen>
+   GHCRTS='-M128m'
+   export GHCRTS
+</screen>
+
+    <para>RTS options taken from the <envar>GHCRTS</envar> environment
+    variable can be overriden by options given on the command
+    line.</para>
+
+  </sect2>
+
   <sect2 id="rts-options-gc">
-    <title>RTS options to control the garbage-collector</title>
+    <title>RTS options to control the garbage collector</title>
 
-    <indexterm><primary>RTS options, garbage-collection</primary></indexterm>
+    <indexterm><primary>garbage collector</primary><secondary>options</secondary></indexterm>
+    <indexterm><primary>RTS options</primary><secondary>garbage collection</secondary></indexterm>
 
     <para>There are several options to give you precise control over
     garbage collection.  Hopefully, you won't need any of these in
@@ -96,6 +121,48 @@
       </varlistentry>
 
       <varlistentry>
+       <term><option>-c</option></term>
+       <indexterm><primary><option>-c</option></primary><secondary>RTS option</secondary>
+       </indexterm>
+       <indexterm><primary>garbage collection</primary><secondary>compacting</secondary>
+       </indexterm>
+       <indexterm><primary>compacting garbage collection</primary></indexterm>
+
+       <listitem>
+         <para>Use a compacting algorithm for collecting the oldest
+         generation.  By default, the oldest generation is collected
+         using a copying algorithm; this option causes it to be
+         compacted in-place instead.  The compaction algorithm is
+         slower than the copying algorithm, but the savings in memory
+         use can be considerable.</para>
+
+         <para>For a given heap size (using the <option>-H</option>
+         option), compaction can in fact reduce the GC cost by
+         allowing fewer GCs to be performed.  This is more likely
+         when the ratio of live data to heap size is high, say
+         &gt;30&percnt;.</para>
+
+         <para>NOTE: compaction doesn't currently work when a single
+         generation is requested using the <option>-G1</option>
+         option.</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term><option>-c</option><replaceable>n</replaceable></term>
+
+       <listitem>
+         <para>&lsqb;Default: 30&rsqb; Automatically enable
+         compacting collection when the live data exceeds
+         <replaceable>n</replaceable>&percnt; of the maximum heap size
+         (see the <option>-M</option> option).  Note that the maximum
+         heap size is unlimited by default, so this option has no
+         effect unless the maximum heap size is set with
+         <option>-M</option><replaceable>size</replaceable>. </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
        <term><option>-F</option><replaceable>factor</replaceable></Term>
        <listitem>
          <indexterm><primary><option>-F</option></primary><secondary>RTS option</secondary></indexterm>
@@ -216,7 +283,7 @@
        <indexterm><primary><option>-M</option></primary><secondary>RTS option</secondary></indexterm>
        <indexterm><primary>heap size, maximum</primary></indexterm>
        <listitem>
-         <para>&lsqb;Default: 64M&rsqb; Set the maximum heap size to
+         <para>&lsqb;Default: unlimited&rsqb; Set the maximum heap size to
           <replaceable>size</replaceable> bytes.  The heap normally
           grows and shrinks according to the memory requirements of
           the program.  The only reason for having this option is to
@@ -224,6 +291,14 @@
           available swap space, which at the least will result in the
           program being summarily killed by the operating
           system.</para>
+
+         <para>The maximum heap size also affects other garbage
+         collection parameters: when the amount of live data in the
+         heap exceeds a certain fraction of the maximum heap size,
+         compacting collection will be automatically enabled for the
+         oldest generation, and the <option>-F</option> parameter
+         will be reduced in order to avoid exceeding the maximum heap
+         size.</para>
        </listitem>
       </varlistentry>