Make some profiling flags dynamic

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

diff --git a/docs/users_guide/parallel.xml b/docs/users_guide/parallel.xml
index fc7ca94..37cafd2 100644 (file)
--- a/docs/users_guide/parallel.xml
+++ b/docs/users_guide/parallel.xml
@@ -5,7 +5,7 @@
   </indexterm>
 
   <para>GHC implements some major extensions to Haskell to support 
   </indexterm>
 
   <para>GHC implements some major extensions to Haskell to support 

-  concurrent and parallel programming.  Let us first etablish terminology:
+  concurrent and parallel programming.  Let us first establish terminology:

   <itemizedlist>
        <listitem><para><emphasis>Parallelism</emphasis> means running
          a Haskell program on multiple processors, with the goal of improving
   <itemizedlist>
        <listitem><para><emphasis>Parallelism</emphasis> means running
          a Haskell program on multiple processors, with the goal of improving

@@ -33,12 +33,12 @@
              url="http://research.microsoft.com/copyright/accept.asp?path=/users/simonpj/papers/concurrent-haskell.ps.gz">
              Concurrent Haskell paper</ulink> is still an excellent
              resource, as is <ulink
              url="http://research.microsoft.com/copyright/accept.asp?path=/users/simonpj/papers/concurrent-haskell.ps.gz">
              Concurrent Haskell paper</ulink> is still an excellent
              resource, as is <ulink

-             url="http://research.microsoft.com/%7Esimonpj/papers/marktoberdorf">Tackling
+             url="http://research.microsoft.com/%7Esimonpj/papers/marktoberdorf/">Tackling

              the awkward squad</ulink>.
   </para><para>
   To the programmer, Concurrent Haskell introduces no new language constructs;
   rather, it appears simply as a library, <ulink
              the awkward squad</ulink>.
   </para><para>
   To the programmer, Concurrent Haskell introduces no new language constructs;
   rather, it appears simply as a library, <ulink

-  url="http://www.haskell.org/ghc/docs/latest/html/libraries/base/Control-Concurrent.html">
+  url="../libraries/base/Control-Concurrent.html">

              Control.Concurrent</ulink>.  The functions exported by this
              library include:
   <itemizedlist>
              Control.Concurrent</ulink>.  The functions exported by this
              library include:
   <itemizedlist>

@@ -62,7 +62,7 @@ the FFI with concurrency</ulink>.</para></listitem>
     it.</para>
 
    <para>The main library you need to use STM is <ulink
     it.</para>
 
    <para>The main library you need to use STM is <ulink

-  url="http://www.haskell.org/ghc/docs/latest/html/libraries/stm/Control-Concurrent-STM.html">
+  url="../libraries/stm/Control-Concurrent-STM.html">

              Control.Concurrent.STM</ulink>. The main features supported are these:
 <itemizedlist>
 <listitem><para>Atomic blocks.</para></listitem>
              Control.Concurrent.STM</ulink>. The main features supported are these:
 <itemizedlist>
 <listitem><para>Atomic blocks.</para></listitem>

@@ -83,7 +83,7 @@ All these features are described in the papers mentioned earlier.
   By default GHC runs your program on one processor; if you
      want it to run in parallel you must link your program
       with the <option>-threaded</option>, and run it with the RTS
   By default GHC runs your program on one processor; if you
      want it to run in parallel you must link your program
       with the <option>-threaded</option>, and run it with the RTS

-      <option>-N</option> option; see  <xref linkend="sec-using-smp" />).
+      <option>-N</option> option; see  <xref linkend="using-smp" />).

       The runtime will
       schedule the running Haskell threads among the available OS
       threads, running as many in parallel as you specified with the
       The runtime will
       schedule the running Haskell threads among the available OS
       threads, running as many in parallel as you specified with the

@@ -110,14 +110,14 @@ All these features are described in the papers mentioned earlier.
     linkend="concurrent-haskell"/>), but the simplest mechanism for extracting parallelism from pure code is
       to use the <literal>par</literal> combinator, which is closely related to (and often used
       with) <literal>seq</literal>.  Both of these are available from <ulink
     linkend="concurrent-haskell"/>), but the simplest mechanism for extracting parallelism from pure code is
       to use the <literal>par</literal> combinator, which is closely related to (and often used
       with) <literal>seq</literal>.  Both of these are available from <ulink

-       url="../libraries/base/Control-Parallel.html"><literal>Control.Parallel</literal></ulink>:</para>
+       url="../libraries/parallel/Control-Parallel.html"><literal>Control.Parallel</literal></ulink>:</para>

 
 <programlisting>
 infixr 0 `par`
 
 <programlisting>
 infixr 0 `par`

-infixr 1 `seq`
+infixr 1 `pseq`

 
 

-par :: a -&#62; b -&#62; b
-seq :: a -&#62; b -&#62; b</programlisting>
+par  :: a -&#62; b -&#62; b
+pseq :: a -&#62; b -&#62; b</programlisting>

 
     <para>The expression <literal>(x `par` y)</literal>
       <emphasis>sparks</emphasis> the evaluation of <literal>x</literal>
 
     <para>The expression <literal>(x `par` y)</literal>
       <emphasis>sparks</emphasis> the evaluation of <literal>x</literal>

@@ -136,24 +136,35 @@ import Control.Parallel
 
 nfib :: Int -&#62; Int
 nfib n | n &#60;= 1 = 1
 
 nfib :: Int -&#62; Int
 nfib n | n &#60;= 1 = 1

-       | otherwise = par n1 (seq n2 (n1 + n2 + 1))
+       | otherwise = par n1 (pseq n2 (n1 + n2 + 1))

                      where n1 = nfib (n-1)
                            n2 = nfib (n-2)</programlisting>
 
     <para>For values of <varname>n</varname> greater than 1, we use
       <function>par</function> to spark a thread to evaluate <literal>nfib (n-1)</literal>,
                      where n1 = nfib (n-1)
                            n2 = nfib (n-2)</programlisting>
 
     <para>For values of <varname>n</varname> greater than 1, we use
       <function>par</function> to spark a thread to evaluate <literal>nfib (n-1)</literal>,

-      and then we use <function>seq</function> to force the
+      and then we use <function>pseq</function> to force the

       parent thread to evaluate <literal>nfib (n-2)</literal> before going on
       to add together these two subexpressions.  In this divide-and-conquer
       approach, we only spark a new thread for one branch of the computation
       (leaving the parent to evaluate the other branch).  Also, we must use
       parent thread to evaluate <literal>nfib (n-2)</literal> before going on
       to add together these two subexpressions.  In this divide-and-conquer
       approach, we only spark a new thread for one branch of the computation
       (leaving the parent to evaluate the other branch).  Also, we must use

-      <function>seq</function> to ensure that the parent will evaluate
+      <function>pseq</function> to ensure that the parent will evaluate

       <varname>n2</varname> <emphasis>before</emphasis> <varname>n1</varname>
       in the expression <literal>(n1 + n2 + 1)</literal>.  It is not sufficient
       to reorder the expression as <literal>(n2 + n1 + 1)</literal>, because
       the compiler may not generate code to evaluate the addends from left to
       right.</para>
 
       <varname>n2</varname> <emphasis>before</emphasis> <varname>n1</varname>
       in the expression <literal>(n1 + n2 + 1)</literal>.  It is not sufficient
       to reorder the expression as <literal>(n2 + n1 + 1)</literal>, because
       the compiler may not generate code to evaluate the addends from left to
       right.</para>
 

+    <para>
+      Note that we use <literal>pseq</literal> rather
+      than <literal>seq</literal>.  The two are almost equivalent, but
+      differ in their runtime behaviour in a subtle
+      way: <literal>seq</literal> can evaluate its arguments in either
+      order, but <literal>pseq</literal> is required to evaluate its
+      first argument before its second, which makes it more suitable
+      for controlling the evaluation order in conjunction
+      with <literal>par</literal>.
+    </para>
+

     <para>When using <literal>par</literal>, the general rule of thumb is that
       the sparked computation should be required at a later time, but not too
       soon.  Also, the sparked computation should not be too small, otherwise
     <para>When using <literal>par</literal>, the general rule of thumb is that
       the sparked computation should be required at a later time, but not too
       soon.  Also, the sparked computation should not be too small, otherwise

@@ -161,14 +172,26 @@ nfib n | n &#60;= 1 = 1
       amount of parallelism gained.  Getting these factors right is tricky in
       practice.</para>
 
       amount of parallelism gained.  Getting these factors right is tricky in
       practice.</para>
 

+    <para>It is possible to glean a little information about how
+      well <literal>par</literal> is working from the runtime
+      statistics; see <xref linkend="rts-options-gc" />.</para>
+

     <para>More sophisticated combinators for expressing parallelism are
       available from the <ulink
     <para>More sophisticated combinators for expressing parallelism are
       available from the <ulink

-       url="../libraries/base/Control-Parallel-Strategies.html"><literal>Control.Parallel.Strategies</literal></ulink> module.
+       url="../libraries/parallel/Control-Parallel-Strategies.html"><literal>Control.Parallel.Strategies</literal></ulink> module.

       This module builds functionality around <literal>par</literal>,
       expressing more elaborate patterns of parallel computation, such as
       parallel <literal>map</literal>.</para>
   </sect2>
 
       This module builds functionality around <literal>par</literal>,
       expressing more elaborate patterns of parallel computation, such as
       parallel <literal>map</literal>.</para>
   </sect2>
 

+<sect2><title>Data Parallel Haskell</title>
+  <para>GHC includes experimental support for Data Parallel Haskell (DPH). This code
+        is highly unstable and is only provided as a technology preview. More
+        information can be found on the corresponding <ulink
+        url="http://www.haskell.org/haskellwiki/GHC/Data_Parallel_Haskell">DPH
+        wiki page</ulink>.</para>
+</sect2>
+

 </sect1>
 
 <!-- Emacs stuff:
 </sect1>
 
 <!-- Emacs stuff: