document -feager-blackholing

diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
index aa84b81..05794df 100644 (file)
--- a/docs/users_guide/flags.xml
+++ b/docs/users_guide/flags.xml
@@ -1429,6 +1429,13 @@
              <entry>static</entry>
              <entry>-</entry>
            </row>
+
+           <row>
+             <entry><option>-feager-blackholing</option></entry>
+             <entry>Turn on <link linkend="parallel-compile-options">eager blackholing</link></entry>
+             <entry>dynamic</entry>
+             <entry>-</entry>
+           </row>
          </tbody>
        </tgroup>
       </informaltable>

diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index ce7ef76..439fb58 100644 (file)
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -1765,15 +1765,58 @@ f "2"    = 2
        linkend="lang-parallel" /> we describe the language features that affect
     parallelism.</para>
     
-    <sect2 id="parallel-options">
-      <title>Options for SMP parallelism</title>
+    <sect2 id="parallel-compile-options">
+      <title>Compile-time options for SMP parallelism</title>
 
       <para>In order to make use of multiple CPUs, your program must be
        linked with the <option>-threaded</option> option (see <xref
-         linkend="options-linker" />).  Then, to run a program on multiple
-       CPUs, use the RTS <option>-N</option> option:</para>
+         linkend="options-linker" />).  Additionally, the following
+       compiler options affect parallelism:</para>
       
       <variablelist>
+        <varlistentry>
+          <term><option>-feager-blackholing</option></term>
+          <indexterm><primary><option>-feager-blackholing</option></primary></indexterm>
+          <listitem>
+          <para>
+            Blackholing is the act of marking a thunk (lazy
+            computuation) as being under evaluation.  It is useful for
+            three reasons: firstly it lets us detect certain kinds of
+            infinite loop (the <literal>NonTermination</literal>
+            exception), secondly it avoids certain kinds of space
+            leak, and thirdly it avoids repeating a computation in a
+            parallel program, because we can tell when a computation
+            is already in progress.</para>
+
+          <para>
+            The option <option>-feager-blackholing</option> causes
+            each thunk to be blackholed as soon as evaluation begins.
+            The default is "lazy blackholing", whereby thunks are only
+            marked as being under evaluation when a thread is paused
+            for some reason.  Lazy blackholing is typically more
+            efficient (by 1-2&percnt; or so), because most thunks don't
+            need to be blackholed.  However, eager blackholing can
+            avoid more repeated computation in a parallel program, and
+            this often turns out to be important for parallelism.
+          </para>
+
+          <para>
+            We recommend compiling any code that is intended to be run
+            in parallel with the <option>-feager-blackholing</option>
+            flag.
+          </para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect2>
+
+    <sect2 id="parallel-options">
+      <title>RTS options for SMP parallelism</title>
+
+      <para>To run a program on multiple CPUs, use the
+       RTS <option>-N</option> option:</para>
+
+      <variablelist>
        <varlistentry>
          <term><option>-N<replaceable>x</replaceable></option></term>
          <listitem>