<?xml version="1.0" encoding="iso-8859-1"?>
-<sect1 id="concurrent-and-parallel">
-<title>Concurrent and Parallel Haskell</title>
-
-<para>
-<indexterm><primary>Concurrent Haskell</primary></indexterm>
-<indexterm><primary>Parallel Haskell</primary></indexterm>
-Concurrent and Parallel Haskell are Glasgow extensions to Haskell
-which let you structure your program as a group of independent
-`threads'.
-</para>
-
-<para>
-Concurrent and Parallel Haskell have very different purposes.
-</para>
-
-<para>
-Concurrent Haskell is for applications which have an inherent
-structure of interacting, concurrent tasks (i.e. `threads'). Threads
-in such programs may be <emphasis>required</emphasis>. For example, if a concurrent thread has been spawned to handle a mouse click, it isn't
-optional—the user wants something done!
-</para>
-
-<para>
-A Concurrent Haskell program implies multiple `threads' running within
-a single Unix process on a single processor.
-</para>
-
-<para>
-You will find at least one paper about Concurrent Haskell hanging off
-of <ulink url="http://research.microsoft.com/~simonpj/">Simon Peyton
-Jones's Web page</ulink>.
-</para>
-
-<para>
-Parallel Haskell is about <emphasis>speed</emphasis>—spawning
-threads onto multiple processors so that your program will run faster.
-The `threads' are always <emphasis>advisory</emphasis>—if the
-runtime system thinks it can get the job done more quickly by
-sequential execution, then fine.
-</para>
-
-<para>
-A Parallel Haskell program implies multiple processes running on
-multiple processors, under a PVM (Parallel Virtual Machine) framework.
-An MPI interface is under development but not fully functional, yet.
-</para>
-
-<para>
-Parallel Haskell is still relatively new; it is more about “research
-fun” than about “speed.” That will change.
-</para>
-
-<para>
-Check the <ulink url="http://www.cee.hw.ac.uk/~dsg/gph/">GPH Page</ulink>
-for more information on “GPH” (Haskell98 with extensions for
-parallel execution), the latest version of “GUM” (the runtime
-system to enable parallel executions) and papers on research issues. A
-list of publications about GPH and about GUM is also available from Simon's
-Web Page.
-</para>
-
-<para>
-Some details about Parallel Haskell follow. For more information
-about concurrent Haskell, see the module
-<literal>Control.Concurrent</literal> in the library documentation.
-</para>
-
-<sect2>
-<title>Features specific to Parallel Haskell
-<indexterm><primary>Parallel Haskell—features</primary></indexterm></title>
-
-<sect3>
-<title>The <literal>Parallel</literal> interface (recommended)
-<indexterm><primary>Parallel interface</primary></indexterm></title>
-
-<para>
-GHC provides two functions for controlling parallel execution, through
-the <literal>Parallel</literal> interface:
-</para>
-
-<para>
+<sect1 id="lang-parallel">
+ <title>Parallel Haskell</title>
+ <indexterm><primary>parallelism</primary>
+ </indexterm>
+
+ <para>There are two implementations of Parallel Haskell: SMP paralellism
+ <indexterm><primary>SMP</primary></indexterm>
+ which is built-in to GHC (see <xref linkend="sec-using-smp" />) and
+ supports running Parallel Haskell programs on a single multiprocessor
+ machine, and
+ Glasgow Parallel Haskell<indexterm><primary>Glasgow Parallel Haskell</primary></indexterm>
+ (GPH) which supports running Parallel Haskell
+ programs on both clusters of machines or single multiprocessors. GPH is
+ developed and distributed
+ separately from GHC (see <ulink url="http://www.cee.hw.ac.uk/~dsg/gph/">The
+ GPH Page</ulink>).</para>
+
+ <para>Ordinary single-threaded Haskell programs will not benefit from
+ enabling SMP parallelism alone. You must expose parallelism to the
+ compiler in one of the following two ways.</para>
+
+ <sect2>
+ <title>Running Concurrent Haskell programs in parallel</title>
+
+ <para>The first possibility is to use concurrent threads to structure your
+ program, and make sure
+ that you spread computation amongst the threads. The runtime will
+ schedule the running Haskell threads among the available OS
+ threads, running as many in parallel as you specified with the
+ <option>-N</option> RTS option.</para>
+ </sect2>
+
+ <sect2>
+ <title>Annotating pure code for parallelism</title>
+
+ <para>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>
<programlisting>
-interface Parallel where
infixr 0 `par`
infixr 1 `seq`
par :: a -> b -> b
-seq :: a -> b -> b
-</programlisting>
-
-</para>
+seq :: a -> b -> b</programlisting>
-<para>
-The expression <literal>(x `par` y)</literal> <emphasis>sparks</emphasis> the evaluation of <literal>x</literal>
-(to weak head normal form) and returns <literal>y</literal>. Sparks are queued for
-execution in FIFO order, but are not executed immediately. At the
-next heap allocation, the currently executing thread will yield
-control to the scheduler, and the scheduler will start a new thread
-(until reaching the active thread limit) for each spark which has not
-already been evaluated to WHNF.
-</para>
+ <para>The expression <literal>(x `par` y)</literal>
+ <emphasis>sparks</emphasis> the evaluation of <literal>x</literal>
+ (to weak head normal form) and returns <literal>y</literal>. Sparks are
+ queued for execution in FIFO order, but are not executed immediately. If
+ the runtime detects that there is an idle CPU, then it may convert a
+ spark into a real thread, and run the new thread on the idle CPU. In
+ this way the available parallelism is spread amongst the real
+ CPUs.</para>
-<para>
-The expression <literal>(x `seq` y)</literal> evaluates <literal>x</literal> to weak head normal
-form and then returns <literal>y</literal>. The <function>seq</function> primitive can be used to
-force evaluation of an expression beyond WHNF, or to impose a desired
-execution sequence for the evaluation of an expression.
-</para>
-
-<para>
-For example, consider the following parallel version of our old
-nemesis, <function>nfib</function>:
-</para>
-
-<para>
+ <para>For example, consider the following parallel version of our old
+ nemesis, <function>nfib</function>:</para>
<programlisting>
-import Parallel
+import Control.Parallel
nfib :: Int -> Int
nfib n | n <= 1 = 1
| otherwise = par n1 (seq n2 (n1 + n2 + 1))
where n1 = nfib (n-1)
- n2 = nfib (n-2)
-</programlisting>
-
-</para>
-
-<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
-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 <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>
-
-</sect3>
-
-<sect3>
-<title>Underlying functions and primitives
-<indexterm><primary>parallelism primitives</primary></indexterm>
-<indexterm><primary>primitives for parallelism</primary></indexterm></title>
-
-<para>
-The functions <function>par</function> and <function>seq</function> are wired into GHC, and unfold
-into uses of the <function>par#</function> and <function>seq#</function> primitives, respectively. If
-you'd like to see this with your very own eyes, just run GHC with the
-<option>-ddump-simpl</option> option. (Anything for a good time…)
-</para>
-
-</sect3>
-
-<sect3>
-<title>Scheduling policy for concurrent threads
-<indexterm><primary>Scheduling—concurrent</primary></indexterm>
-<indexterm><primary>Concurrent scheduling</primary></indexterm></title>
-
-<para>
-Runnable threads are scheduled in round-robin fashion. Context
-switches are signalled by the generation of new sparks or by the
-expiry of a virtual timer (the timer interval is configurable with the
-<option>-C[<num>]</option><indexterm><primary>-C<num> RTS option (concurrent,
-parallel)</primary></indexterm> RTS option). However, a context switch doesn't
-really happen until the current heap block is full. You can't get any
-faster context switching than this.
-</para>
-
-<para>
-When a context switch occurs, pending sparks which have not already
-been reduced to weak head normal form are turned into new threads.
-However, there is a limit to the number of active threads (runnable or
-blocked) which are allowed at any given time. This limit can be
-adjusted with the <option>-t<num></option><indexterm><primary>-t <num> RTS option (concurrent, parallel)</primary></indexterm>
-RTS option (the default is 32). Once the
-thread limit is reached, any remaining sparks are deferred until some
-of the currently active threads are completed.
-</para>
-
-</sect3>
-
-<sect3>
-<title>Scheduling policy for parallel threads
-<indexterm><primary>Scheduling—parallel</primary></indexterm>
-<indexterm><primary>Parallel scheduling</primary></indexterm></title>
-
-<para>
-In GUM we use an unfair scheduler, which means that a thread continues to
-perform graph reduction until it blocks on a closure under evaluation, on a
-remote closure or until the thread finishes.
-</para>
-
-</sect3>
-
-</sect2>
+ 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
+ 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
+ <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>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
+ the cost of forking it in parallel will be too large relative to the
+ amount of parallelism gained. Getting these factors right is tricky in
+ practice.</para>
+
+ <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.
+ This module builds functionality around <literal>par</literal>,
+ expressing more elaborate patterns of parallel computation, such as
+ parallel <literal>map</literal>.</para>
+ </sect2>
</sect1>
</variablelist>
</sect1>
-<sect1 id="sec-using-parallel">
-<title>Using parallel Haskell</title>
-
-<para>
-<indexterm><primary>Parallel Haskell</primary><secondary>using</secondary></indexterm>
-[NOTE: GHC does not support Parallel Haskell by default, you need to
- obtain a special version of GHC from the <ulink
- url="http://www.cee.hw.ac.uk/~dsg/gph/">GPH</ulink> site. Also,
-you won't be able to execute parallel Haskell programs unless PVM3
-(parallel Virtual Machine, version 3) is installed at your site.]
-</para>
-
-<para>
-To compile a Haskell program for parallel execution under PVM, use the
-<option>-parallel</option> option,<indexterm><primary>-parallel
-option</primary></indexterm> both when compiling <emphasis>and
-linking</emphasis>. You will probably want to <literal>import
-Control.Parallel</literal> into your Haskell modules.
-</para>
-
-<para>
-To run your parallel program, once PVM is going, just invoke it
-“as normal”. The main extra RTS option is
-<option>-qp<n></option>, to say how many PVM
-“processors” your program to run on. (For more details of
-all relevant RTS options, please see <xref
-linkend="parallel-rts-opts"/>.)
-</para>
-
-<para>
-In truth, running parallel Haskell programs and getting information
-out of them (e.g., parallelism profiles) is a battle with the vagaries of
-PVM, detailed in the following sections.
-</para>
-
-<sect2 id="pvm-dummies">
-<title>Dummy's guide to using PVM</title>
-
-<para>
-<indexterm><primary>PVM, how to use</primary></indexterm>
-<indexterm><primary>parallel Haskell—PVM use</primary></indexterm>
-Before you can run a parallel program under PVM, you must set the
-required environment variables (PVM's idea, not ours); something like,
-probably in your <filename>.cshrc</filename> or equivalent:
-
-<programlisting>
-setenv PVM_ROOT /wherever/you/put/it
-setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
-setenv PVM_DPATH $PVM_ROOT/lib/pvmd
-</programlisting>
-
-</para>
-
-<para>
-Creating and/or controlling your “parallel machine” is a purely-PVM
-business; nothing specific to parallel Haskell. The following paragraphs
-describe how to configure your parallel machine interactively.
-</para>
-
-<para>
-If you use parallel Haskell regularly on the same machine configuration it
-is a good idea to maintain a file with all machine names and to make the
-environment variable PVM_HOST_FILE point to this file. Then you can avoid
-the interactive operations described below by just saying
-</para>
-
-<programlisting>
-pvm $PVM_HOST_FILE
-</programlisting>
-
-<para>
-You use the <command>pvm</command><indexterm><primary>pvm command</primary></indexterm> command to start PVM on your
-machine. You can then do various things to control/monitor your
-“parallel machine;” the most useful being:
-</para>
-
-<para>
-<informaltable>
-<tgroup cols="2">
-<colspec align="left"/>
-<tbody>
-
-<row>
-<entry><keycombo><keycap>Control</keycap><keycap>D</keycap></keycombo></entry>
-<entry>exit <command>pvm</command>, leaving it running</entry>
-</row>
-
-<row>
-<entry><command>halt</command></entry>
-<entry>kill off this “parallel machine” & exit</entry>
-</row>
-
-<row>
-<entry><command>add <host></command></entry>
-<entry>add <command><host></command> as a processor</entry>
-</row>
-
-<row>
-<entry><command>delete <host></command></entry>
-<entry>delete <command><host></command></entry>
-</row>
-
-<row>
-<entry><command>reset</command></entry>
-<entry>kill what's going, but leave PVM up</entry>
-</row>
-
-<row>
-<entry><command>conf</command></entry>
-<entry>list the current configuration</entry>
-</row>
-
-<row>
-<entry><command>ps</command></entry>
-<entry>report processes' status</entry>
-</row>
-
-<row>
-<entry><command>pstat <pid></command></entry>
-<entry>status of a particular process</entry>
-</row>
-
-</tbody>
-</tgroup>
-</informaltable>
-</para>
-
-<para>
-The PVM documentation can tell you much, much more about <command>pvm</command>!
-</para>
-
-</sect2>
-
-<sect2 id="par-profiles">
-<title>parallelism profiles</title>
-
-<para>
-<indexterm><primary>parallelism profiles</primary></indexterm>
-<indexterm><primary>profiles, parallelism</primary></indexterm>
-<indexterm><primary>visualisation tools</primary></indexterm>
-</para>
-
-<para>
-With parallel Haskell programs, we usually don't care about the
-results—only with “how parallel” it was! We want pretty pictures.
-</para>
-
-<para>
-parallelism profiles (à la <command>hbcpp</command>) can be generated with the
-<option>-qP</option><indexterm><primary>-qP RTS option</primary></indexterm> RTS option. The
-per-processor profiling info is dumped into files named
-<filename><full-path><program>.gr</filename>. These are then munged into a PostScript picture,
-which you can then display. For example, to run your program
-<filename>a.out</filename> on 8 processors, then view the parallelism profile, do:
-</para>
-
-<para>
-
-<screen>
-<prompt>$</prompt> ./a.out +RTS -qP -qp8
-<prompt>$</prompt> grs2gr *.???.gr > temp.gr # combine the 8 .gr files into one
-<prompt>$</prompt> gr2ps -O temp.gr # cvt to .ps; output in temp.ps
-<prompt>$</prompt> ghostview -seascape temp.ps # look at it!
-</screen>
+ <sect1 id="sec-using-smp">
+ <title>Using SMP parallelism</title>
+ <indexterm><primary>parallelism</primary>
+ </indexterm>
+ <indexterm><primary>SMP</primary>
+ </indexterm>
-</para>
-
-<para>
-The scripts for processing the parallelism profiles are distributed
-in <filename>ghc/utils/parallel/</filename>.
-</para>
-
-</sect2>
-
-<sect2>
-<title>Other useful info about running parallel programs</title>
-
-<para>
-The “garbage-collection statistics” RTS options can be useful for
-seeing what parallel programs are doing. If you do either
-<option>+RTS -Sstderr</option><indexterm><primary>-Sstderr RTS option</primary></indexterm> or <option>+RTS -sstderr</option>, then
-you'll get mutator, garbage-collection, etc., times on standard
-error. The standard error of all PE's other than the `main thread'
-appears in <filename>/tmp/pvml.nnn</filename>, courtesy of PVM.
-</para>
-
-<para>
-Whether doing <option>+RTS -Sstderr</option> or not, a handy way to watch
-what's happening overall is: <command>tail -f /tmp/pvml.nnn</command>.
-</para>
-
-</sect2>
-
-<sect2 id="parallel-rts-opts">
-<title>RTS options for Parallel Haskell
-</title>
-
-<para>
-<indexterm><primary>RTS options, parallel</primary></indexterm>
-<indexterm><primary>parallel Haskell—RTS options</primary></indexterm>
-</para>
-
-<para>
-Besides the usual runtime system (RTS) options
-(<xref linkend="runtime-control"/>), there are a few options particularly
-for parallel execution.
-</para>
-
-<para>
-<variablelist>
-
-<varlistentry>
-<term><option>-qp<N></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-qp<N> RTS option</primary></indexterm>
-(paraLLEL ONLY) Use <literal><N></literal> PVM processors to run this program;
-the default is 2.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-C[<s>]</option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-C<s> RTS option</primary></indexterm> Sets
-the context switch interval to <literal><s></literal> seconds.
-A context switch will occur at the next heap block allocation after
-the timer expires (a heap block allocation occurs every 4k of
-allocation). With <option>-C0</option> or <option>-C</option>,
-context switches will occur as often as possible (at every heap block
-allocation). By default, context switches occur every 20ms. Note that GHC's internal timer ticks every 20ms, and
-the context switch timer is always a multiple of this timer, so 20ms
-is the maximum granularity available for timed context switches.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-q[v]</option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-q RTS option</primary></indexterm>
-(paraLLEL ONLY) Produce a quasi-parallel profile of thread activity,
-in the file <filename><program>.qp</filename>. In the style of <command>hbcpp</command>, this profile
-records the movement of threads between the green (runnable) and red
-(blocked) queues. If you specify the verbose suboption (<option>-qv</option>), the
-green queue is split into green (for the currently running thread
-only) and amber (for other runnable threads). We do not recommend
-that you use the verbose suboption if you are planning to use the
-<command>hbcpp</command> profiling tools or if you are context switching at every heap
-check (with <option>-C</option>).
--->
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-qt<num></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-qt<num> RTS option</primary></indexterm>
-(paraLLEL ONLY) Limit the thread pool size, i.e. the number of
-threads per processor to <literal><num></literal>. The default is
-32. Each thread requires slightly over 1K <emphasis>words</emphasis> in
-the heap for thread state and stack objects. (For 32-bit machines, this
-translates to 4K bytes, and for 64-bit machines, 8K bytes.)
-</para>
-</listitem>
-</varlistentry>
-<!-- no more -HWL
-<varlistentry>
-<term><option>-d</option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-d RTS option (parallel)</primary></indexterm>
-(paraLLEL ONLY) Turn on debugging. It pops up one xterm (or GDB, or
-something…) per PVM processor. We use the standard <command>debugger</command>
-script that comes with PVM3, but we sometimes meddle with the
-<command>debugger2</command> script. We include ours in the GHC distribution,
-in <filename>ghc/utils/pvm/</filename>.
-</para>
-</listitem>
-</varlistentry>
--->
-<varlistentry>
-<term><option>-qe<num></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-qe<num> RTS option
-(parallel)</primary></indexterm> (paraLLEL ONLY) Limit the spark pool size
-i.e. the number of pending sparks per processor to
-<literal><num></literal>. The default is 100. A larger number may be
-appropriate if your program generates large amounts of parallelism
-initially.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-qQ<num></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-qQ<num> RTS option (parallel)</primary></indexterm>
-(paraLLEL ONLY) Set the size of packets transmitted between processors
-to <literal><num></literal>. The default is 1024 words. A larger number may be
-appropriate if your machine has a high communication cost relative to
-computation speed.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-qh<num></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-qh<num> RTS option (parallel)</primary></indexterm>
-(paraLLEL ONLY) Select a packing scheme. Set the number of non-root thunks to pack in one packet to
-<num>-1 (0 means infinity). By default GUM uses full-subgraph
-packing, i.e. the entire subgraph with the requested closure as root is
-transmitted (provided it fits into one packet). Choosing a smaller value
-reduces the amount of pre-fetching of work done in GUM. This can be
-advantageous for improving data locality but it can also worsen the balance
-of the load in the system.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-qg<num></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-qg<num> RTS option
-(parallel)</primary></indexterm> (paraLLEL ONLY) Select a globalisation
-scheme. This option affects the
-generation of global addresses when transferring data. Global addresses are
-globally unique identifiers required to maintain sharing in the distributed
-graph structure. Currently this is a binary option. With <num>=0 full globalisation is used
-(default). This means a global address is generated for every closure that
-is transmitted. With <num>=1 a thunk-only globalisation scheme is
-used, which generated global address only for thunks. The latter case may
-lose sharing of data but has a reduced overhead in packing graph structures
-and maintaining internal tables of global addresses.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-</sect2>
+ <para>GHC supports running Haskell programs in parallel on an SMP
+ (symmetric multiprocessor).</para>
+
+ <para>There's a fine distinction between
+ <emphasis>concurrency</emphasis> and <emphasis>parallelism</emphasis>:
+ parallelism is all about making your program run
+ <emphasis>faster</emphasis> by making use of multiple processors
+ simultaneously. Concurrency, on the other hand, is a means of
+ abstraction: it is a convenient way to structure a program that must
+ respond to multiple asynchronous events.</para>
+
+ <para>However, the two terms are certainly related. By making use of
+ multiple CPUs it is possible to run concurrent threads in parallel,
+ and this is exactly what GHC's SMP parallelism support does. But it
+ is also possible to obtain performance improvements with parallelism
+ on programs that do not use concurrency. This section describes how to
+ use GHC to compile and run parallel programs, in <xref
+ linkend="lang-parallel" /> we desribe the language features that affect
+ parallelism.</para>
+
+ <sect2 id="parallel-options">
+ <title>Options to enable SMP parallelism</title>
-</sect1>
+ <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>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-N<replaceable>x</replaceable></option></term>
+ <listitem>
+ <para><indexterm><primary><option>-N<replaceable>x</replaceable></option></primary><secondary>RTS option</secondary></indexterm>
+ Use <replaceable>x</replaceable> simultaneous threads when
+ running the program. Normally <replaceable>x</replaceable>
+ should be chosen to match the number of CPU cores on the machine.
+ There is no means (currently) by which this value may vary after
+ the program has started.</para>
+
+ <para>For example, on a dual-core machine we would probably use
+ <literal>+RTS -N2 -RTS</literal>.</para>
+
+ <para>Whether hyperthreading cores should be counted or not is an
+ open question; please feel free to experiment and let us know what
+ results you find.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Hints for using SMP parallelism</title>
+
+ <para>Add the <literal>-sstderr</literal> RTS option when
+ running the program to see timing stats, which will help to tell you
+ whether your program got faster by using more CPUs or not. If the user
+ time is greater than
+ the elapsed time, then the program used more than one CPU. You should
+ also run the program without <literal>-N</literal> for comparison.</para>
+
+ <para>GHC's parallelism support is new and experimental. It may make your
+ program go faster, or it might slow it down - either way, we'd be
+ interested to hear from you.</para>
+
+ <para>One significant limitation with the current implementation is that
+ the garbage collector is still single-threaded, and all execution must
+ stop when GC takes place. This can be a significant bottleneck in a
+ parallel program, especially if your program does a lot of GC. If this
+ happens to you, then try reducing the cost of GC by tweaking the GC
+ settings (<xref linkend="rts-options-gc" />): enlarging the heap or the
+ allocation area size is a good start.</para>
+ </sect2>
+ </sect1>
<sect1 id="options-platform">
<title>Platform-specific Flags</title>
projects / ghc-hetmet.git / commitdiff