Document new GC options -q1 and -qg<n>

diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml
index 94995b3..3170f09 100644 (file)
--- a/docs/users_guide/runtime_control.xml
+++ b/docs/users_guide/runtime_control.xml
@@ -298,38 +298,52 @@
 
       <varlistentry>
         <term>
-          <option>-g</option><replaceable>threads</replaceable>
-          <indexterm><primary><option>-g</option></primary><secondary>RTS option</secondary></indexterm>
+          <option>-q1</option>
+          <indexterm><primary><option>-q1</option><secondary>RTS
+          option</secondary></primary></indexterm>
         </term>
         <listitem>
-          <para>&lsqb;Default: 1&rsqb; &lsqb;new in GHC 6.10&rsqb; Set the number
-            of threads to use for garbage collection.  This option is
-            only accepted when the program was linked with the
-            <option>-threaded</option> option; see <xref
-            linkend="options-linker" />.</para>
-
-          <para>The garbage collector is able to work in parallel when
-            given more than one OS thread.  Experiments have shown
-            that this usually results in a performance improvement
-            given 3 cores or more; with 2 cores it may or may not be
-            beneficial, depending on the workload.  Bigger heaps work
-            better with parallel GC, so set your <option>-H</option>
-            value high (3 or more times the maximum residency).  Look
-            at the timing stats with <option>+RTS -s</option> to
-            see whether you're getting any benefit from parallel GC or
-            not.  If you find parallel GC is
-            significantly <emphasis>slower</emphasis> (in elapsed
-            time) than sequential GC, please report it as a
-            bug.</para>
-
-          <para>This value is set automatically when the
-            <option>-N</option> option is used, so the only reason to
-            use <option>-g</option> would be if you wanted to use a
-            different number of threads for GC than for execution.
-            For example, if your program is strictly single-threaded
-            but you still want to benefit from parallel GC, then it
-            might make sense to use <option>-g</option> rather than
-            <option>-N</option>.</para>
+          <para>&lsqb;New in GHC 6.12.1&rsqb; Disable the parallel GC.
+            The parallel GC is turned on automatically when parallel
+            execution is enabled with the <option>-N</option> option;
+            this option is available to turn it off if
+            necessary.</para>
+          
+          <para>Experiments have shown that parallel GC usually
+            results in a performance improvement given 3 cores or
+            more; with 2 cores it may or may not be beneficial,
+            depending on the workload.  Bigger heaps work better with
+            parallel GC, so set your <option>-H</option> value high (3
+            or more times the maximum residency).  Look at the timing
+            stats with <option>+RTS -s</option> to see whether you're
+            getting any benefit from parallel GC or not.  If you find
+            parallel GC is significantly <emphasis>slower</emphasis>
+            (in elapsed time) than sequential GC, please report it as
+            a bug.</para>
+
+          <para>In GHC 6.10.1 it was possible to use a different
+            number of threads for GC than for execution, because the GC
+            used its own pool of threads.  Now, the GC uses the same
+            threads as the mutator (for executing the program).</para>
+        </listitem>
+      </varlistentry>        
+
+      <varlistentry>
+        <term>
+          <option>-qg<replaceable>n</replaceable></option>
+          <indexterm><primary><option>-qg</option><secondary>RTS
+          option</secondary></primary></indexterm>
+        </term>
+        <listitem>
+          <para>
+            &lsqb;Default: 1&rsqb; &lsqb;New in GHC 6.12.1&rsqb;
+            Enable the parallel GC only in
+            generation <replaceable>n</replaceable> and greater.
+            Parallel GC is often not worthwhile for collections in
+            generation 0 (the young generation), so it is enabled by
+            default only for collections in generation 1 (and higher,
+            if applicable).
+          </para>
         </listitem>
       </varlistentry>