document paralel GC option: +RTS -g

diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml
index 62a01ac..183cd9c 100644 (file)
--- a/docs/users_guide/runtime_control.xml
+++ b/docs/users_guide/runtime_control.xml
@@ -268,6 +268,43 @@
       </varlistentry>
 
       <varlistentry>
+        <term>
+          <option>-g</option><replaceable>threads</replaceable>
+          <indexterm><primary><option>-g</option></primary><secondary>RTS option</secondary></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>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
        <term>
           <option>-H</option><replaceable>size</replaceable>
           <indexterm><primary><option>-H</option></primary><secondary>RTS option</secondary></indexterm>