diff options
| author | Simon Marlow <marlowsd@gmail.com> | 2009-01-15 09:39:22 +0000 |
|---|---|---|
| committer | Simon Marlow <marlowsd@gmail.com> | 2009-01-15 09:39:22 +0000 |
| commit | a078252410f284229e5f2440e7b8a9b32a6cfd33 (patch) | |
| tree | 8afdbb09fbccbb5d1e73ec1dc943297ec59b6c37 /docs | |
| parent | ee69a45c027e2a9fefd9a97bfd64e78b49d0ecbe (diff) | |
| download | haskell-a078252410f284229e5f2440e7b8a9b32a6cfd33.tar.gz | |
document -feager-blackholing
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/users_guide/flags.xml | 7 | ||||
| -rw-r--r-- | docs/users_guide/using.xml | 51 |
2 files changed, 54 insertions, 4 deletions
diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml index aa84b81cb9..05794dfb25 100644 --- a/docs/users_guide/flags.xml +++ b/docs/users_guide/flags.xml @@ -1429,6 +1429,13 @@ <entry>static</entry> <entry>-</entry> </row> + + <row> + <entry><option>-feager-blackholing</option></entry> + <entry>Turn on <link linkend="parallel-compile-options">eager blackholing</link></entry> + <entry>dynamic</entry> + <entry>-</entry> + </row> </tbody> </tgroup> </informaltable> diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml index ce7ef7680b..439fb58c90 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% 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> |