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

diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index 3c19be5..439fb58 100644
--- 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