Remove redundant fromIntegral calls

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

diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml
index 776b65f..725ee88 100644 (file)
--- a/docs/users_guide/runtime_control.xml
+++ b/docs/users_guide/runtime_control.xml
@@ -110,7 +110,7 @@
          increase the resolution of the time profiler.</para>
 
          <para>Using a value of zero disables the RTS clock
-         completetly, and has the effect of disabling timers that
+         completely, and has the effect of disabling timers that
          depend on it: the context switch timer and the heap profiling
          timer.  Context switches will still happen, but
          deterministically and at a rate much faster than normal.
@@ -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>
@@ -399,46 +436,35 @@
       </varlistentry>
 
       <varlistentry>
+        <term>
+          <option>-t</option><optional><replaceable>file</replaceable></optional>
+          <indexterm><primary><option>-t</option></primary><secondary>RTS option</secondary></indexterm>
+        </term>
        <term>
-          <option>-s</option><replaceable>file</replaceable>
+          <option>-s</option><optional><replaceable>file</replaceable></optional>
           <indexterm><primary><option>-s</option></primary><secondary>RTS option</secondary></indexterm>
         </term>
        <term>
-          <option>-S</option><replaceable>file</replaceable>
+          <option>-S</option><optional><replaceable>file</replaceable></optional>
           <indexterm><primary><option>-S</option></primary><secondary>RTS option</secondary></indexterm>
         </term>
        <listitem>
-         <para>Write modest (<option>-s</option>) or verbose
-          (<option>-S</option>) garbage-collector statistics into file
-          <replaceable>file</replaceable>. The default
-          <replaceable>file</replaceable> is
-          <filename><replaceable>program</replaceable>.stat</filename>. The
-          <replaceable>file</replaceable> <constant>stderr</constant>
-          is treated specially, with the output really being sent to
-          <constant>stderr</constant>.</para>
-
-         <para>This option is useful for watching how the storage
-          manager adjusts the heap size based on the current amount of
-          live data.</para>
-       </listitem>
-      </varlistentry>
+         <para>These options produce runtime-system statistics, such
+         as the amount of time spent executing the program and in the
+         garbage collector, the amount of memory allocated, the
+         maximum size of the heap, and so on.  The three
+         variants give different levels of detail:
+         <option>-t</option> produces a single line of output in the
+         same format as GHC's <option>-Rghc-timing</option> option,
+         <option>-s</option> produces a more detailed summary at the
+         end of the program, and <option>-S</option> additionally
+         produces information about each and every garbage
+         collection.</para>
 
-      <varlistentry>
-       <term>
-          <option>-t<replaceable>file</replaceable></option>
-          <indexterm><primary><option>-t</option></primary><secondary>RTS option</secondary></indexterm>
-        </term>
-       <listitem>
-         <para>Write a one-line GC stats summary after running the
-         program.  This output is in the same format as that produced
-         by the <option>-Rghc-timing</option> option.</para>
-
-         <para>As with <option>-s</option>, the default
-          <replaceable>file</replaceable> is
-          <filename><replaceable>program</replaceable>.stat</filename>. The
-          <replaceable>file</replaceable> <constant>stderr</constant>
-          is treated specially, with the output really being sent to
-          <constant>stderr</constant>.</para>
+          <para>The output is placed in
+          <replaceable>file</replaceable>.  If
+          <replaceable>file</replaceable> is omitted, then the output
+          is sent to <constant>stderr</constant>.</para>
        </listitem>
       </varlistentry>
     </variablelist>