document -feager-blackholing

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

diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index 3c19be5..439fb58 100644 (file)
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -841,7 +841,7 @@ ghc -c Foo.hs</screen>
     of warnings which are generally likely to indicate bugs in your
     program.  These are:
     <option>-fwarn-overlapping-patterns</option>,
-    <option>-fwarn-deprecations</option>,
+    <option>-fwarn-warnings-deprecations</option>,
     <option>-fwarn-deprecated-flags</option>,
     <option>-fwarn-duplicate-exports</option>,
     <option>-fwarn-missing-fields</option>,
@@ -919,15 +919,16 @@ ghc -c Foo.hs</screen>
     <variablelist>
 
       <varlistentry>
-       <term><option>-fwarn-deprecations</option>:</term>
+       <term><option>-fwarn-warnings-deprecations</option>:</term>
        <listitem>
-         <indexterm><primary><option>-fwarn-deprecations</option></primary>
+         <indexterm><primary><option>-fwarn-warnings-deprecations</option></primary>
          </indexterm>
+         <indexterm><primary>warnings</primary></indexterm>
          <indexterm><primary>deprecations</primary></indexterm>
-         <para>Causes a warning to be emitted when a deprecated
-         function or type is used.  Entities can be marked as
-         deprecated using a pragma, see <xref
-         linkend="deprecated-pragma"/>.</para>
+         <para>Causes a warning to be emitted when a
+         module, function or type with a WARNING or DEPRECATED pragma
+      is used. See <xref linkend="warning-deprecated-pragma"/> for more
+      details on the pragmas.</para>
 
          <para>This option is on by default.</para>
        </listitem>
@@ -1178,7 +1179,8 @@ f foo = foo { x = 6 }
          <para>The trouble with orphans is that GHC must pro-actively read the interface
            files for all orphan modules, just in case their instances or rules
            play a role, whether or not the module's interface would otherwise 
-           be of any use.  Other things being equal, avoid orphan modules.</para>
+           be of any use.  See <xref linkend="orphan-modules"/> for details.
+            </para>
        </listitem>
       </varlistentry>
 
@@ -1763,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>
@@ -1904,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