X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fusing.xml;h=439fb58c90b6ba96d19432e3d75b264d2e0c86bd;hb=a078252410f284229e5f2440e7b8a9b32a6cfd33;hp=e26cbddc1e08c52eb247571af72734a5d948245e;hpb=2f979bf83bad9b012efa225c38cfcd7ea91b2b29;p=ghc-hetmet.git

diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index e26cbdd..439fb58 100644
--- 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>
@@ -1906,7 +1949,7 @@ statements or clauses.
 
   <para>GHC can dump its optimized intermediate code (said to be in &ldquo;Core&rdquo; format) 
   to a file as a side-effect of compilation. Non-GHC back-end tools can read and process Core files; these files have the suffix
-  <filename>.hcr</filename>. The Core format is described in <ulink url="http://www.haskell.org/ghc/docs/papers/core.ps.gz">
+  <filename>.hcr</filename>. The Core format is described in <ulink url="../ext-core/core.pdf">
   <citetitle>An External Representation for the GHC Core Language</citetitle></ulink>, 
   and sample tools
   for manipulating Core files (in Haskell) are in the GHC source distribution