Commit 2a103c7d authored by Simon Marlow's avatar Simon Marlow

Improve documentation for -N and -qa (#9890)

parent 36df0988
...@@ -3308,13 +3308,29 @@ data D = D !C ...@@ -3308,13 +3308,29 @@ data D = D !C
<listitem> <listitem>
<para><indexterm><primary><option>-N<replaceable>x</replaceable></option></primary><secondary>RTS option</secondary></indexterm> <para><indexterm><primary><option>-N<replaceable>x</replaceable></option></primary><secondary>RTS option</secondary></indexterm>
Use <replaceable>x</replaceable> simultaneous threads when Use <replaceable>x</replaceable> simultaneous threads when
running the program. Normally <replaceable>x</replaceable> running the program.</para>
should be chosen to match the number of CPU cores on the
machine<footnote><para>Whether hyperthreading cores should be counted or not is an <para>The runtime manages a set of virtual processors,
open question; please feel free to experiment and let us know what which we call <emphasis>capabilities</emphasis>, the
results you find.</para></footnote>. For example, number of which is determined by the <option>-N</option>
on a dual-core machine we would probably use option. Each capability can run one Haskell thread at a
<literal>+RTS -N2 -RTS</literal>.</para> time, so the number of capabilities is equal to the
number of Haskell threads that can run physically in
parallel. A capability is animated by one or more OS
threads; the runtime manages a pool of OS threads for
each capability, so that if a Haskell thread makes a
foreign call (see <xref linkend="ffi-threads" />)
another OS thread can take over that capability.
</para>
<para>Normally <replaceable>x</replaceable> should be
chosen to match the number of CPU cores on the
machine<footnote><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></footnote>. For example, on a dual-core
machine we would probably use <literal>+RTS -N2
-RTS</literal>.</para>
<para>Omitting <replaceable>x</replaceable>, <para>Omitting <replaceable>x</replaceable>,
i.e. <literal>+RTS -N -RTS</literal>, lets the runtime i.e. <literal>+RTS -N -RTS</literal>, lets the runtime
...@@ -3331,10 +3347,11 @@ data D = D !C ...@@ -3331,10 +3347,11 @@ data D = D !C
<xref linkend="rts-options-gc" />).</para> <xref linkend="rts-options-gc" />).</para>
<para>The current value of the <option>-N</option> option <para>The current value of the <option>-N</option> option
is available to the Haskell program is available to the Haskell program via
via <literal>Control.Concurrent.getNumCapabilities</literal>, and <literal>Control.Concurrent.getNumCapabilities</literal>,
it may be changed while the program is running by and it may be changed while the program is running by
calling <literal>Control.Concurrent.setNumCapabilities</literal>.</para> calling
<literal>Control.Concurrent.setNumCapabilities</literal>.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
...@@ -3349,9 +3366,18 @@ data D = D !C ...@@ -3349,9 +3366,18 @@ data D = D !C
option</secondary></indexterm> option</secondary></indexterm>
<listitem> <listitem>
<para>Use the OS's affinity facilities to try to pin OS <para>Use the OS's affinity facilities to try to pin OS
threads to CPU cores. This is an experimental feature, threads to CPU cores.</para>
and may or may not be useful. Please let us know
whether it helps for you!</para> <para>When this option is enabled, the OS threads for a
capability <emphasis>i</emphasis> are bound to the CPU
core <emphasis>i</emphasis> using the API provided by the
OS for setting thread affinity. e.g. on Linux
GHC uses <literal>sched_setaffinity()</literal>.</para>
<para>Depending on your workload and the other activity on
the machine, this may or may not result in a performance
improvement. We recommend trying it out and measuring the
difference.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment