[commit: ghc] ghc-7.10: Improve documentation for -N and -qa (#9890) (bb56695)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : ghc-7.10
Link       : http://ghc.haskell.org/trac/ghc/changeset/bb56695b98b20d0e28a30b360265e2b147cc2f24/ghc

>---------------------------------------------------------------

commit bb56695b98b20d0e28a30b360265e2b147cc2f24
Author: Simon Marlow <marlowsd at gmail.com>
Date:   Tue Dec 16 11:42:42 2014 +0000

    Improve documentation for -N and -qa (#9890)
    
    (cherry picked from commit 2a103c7d763c22dc9b0562dac1184ffb950da5ce)


>---------------------------------------------------------------

bb56695b98b20d0e28a30b360265e2b147cc2f24
 docs/users_guide/using.xml | 54 ++++++++++++++++++++++++++++++++++------------
 1 file changed, 40 insertions(+), 14 deletions(-)

diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index 3059cff..83c69ce 100644
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -3261,13 +3261,29 @@ data D = D !C
           <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<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>
+              running the program.</para>
+
+              <para>The runtime manages a set of virtual processors,
+              which we call <emphasis>capabilities</emphasis>, the
+              number of which is determined by the <option>-N</option>
+              option.  Each capability can run one Haskell thread at a
+              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>,
               i.e. <literal>+RTS -N -RTS</literal>, lets the runtime
@@ -3284,10 +3300,11 @@ data D = D !C
               <xref linkend="rts-options-gc" />).</para>
 
             <para>The current value of the <option>-N</option> option
-              is available to the Haskell program
-              via <literal>Control.Concurrent.getNumCapabilities</literal>, and
-              it may be changed while the program is running by
-              calling <literal>Control.Concurrent.setNumCapabilities</literal>.</para>
+            is available to the Haskell program via
+            <literal>Control.Concurrent.getNumCapabilities</literal>,
+            and it may be changed while the program is running by
+            calling
+            <literal>Control.Concurrent.setNumCapabilities</literal>.</para>
           </listitem>
         </varlistentry>
       </variablelist>
@@ -3302,9 +3319,18 @@ data D = D !C
           option</secondary></indexterm>
           <listitem>
             <para>Use the OS's affinity facilities to try to pin OS
-              threads to CPU cores.  This is an experimental feature,
-              and may or may not be useful.  Please let us know
-              whether it helps for you!</para>
+            threads to CPU cores.</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>
         </varlistentry>
         <varlistentry>