From 8051f46061c7cd03f0fc327f047eb2526d00c924 Mon Sep 17 00:00:00 2001
From: Simon Marlow <marlowsd@gmail.com>
Date: Thu, 19 Jun 2008 12:12:27 +0000
Subject: [PATCH] document some RTS options I added a while ago: -qm, -qw

---
 docs/users_guide/using.xml |   59 +++++++++++++++++++++++++++++++++++++-------
 1 file changed, 50 insertions(+), 9 deletions(-)

diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index 60b8f3e..d805097 100644
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -1738,7 +1738,7 @@ f "2"    = 2
     parallelism.</para>
     
     <sect2 id="parallel-options">
-      <title>Options to enable SMP parallelism</title>
+      <title>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
@@ -1752,19 +1752,60 @@ f "2"    = 2
 	    <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
+	      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>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>
+            <para>Setting <option>-N</option> also has the effect of
+	      setting <option>-g</option> (the number of OS threads to
+	      use for garbage collection) to the same value.</para>
+
+            <para>There is no means (currently) by which this value
+	      may vary after the program has started.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
+
+      <para>The following options affect the way the runtime schedules
+      threads on CPUs:</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term><option>-qm</option></term>
+          <indexterm><primary><option>-qm</option></primary><secondary>RTS
+          option</secondary></indexterm>
+	  <listitem>
+            <para>Disable automatic migration for load balancing.
+            Normally the runtime will automatically try to schedule
+            threads across the available CPUs to make use of idle
+            CPUs; this option disables that behaviour.  It is probably
+            only of use if you are explicitly scheduling threads onto
+            CPUs with <literal>GHC.Conc.forkOnIO</literal>.</para>
+          </listitem>
+        </varlistentry>
+	<varlistentry>
+	  <term><option>-qw</option></term>
+          <indexterm><primary><option>-qw</option></primary><secondary>RTS
+          option</secondary></indexterm>
+	  <listitem>
+            <para>Migrate a thread to the current CPU when it is woken
+            up.  Normally when a thread is woken up after being
+            blocked it will be scheduled on the CPU it was running on
+            last; this option allows the thread to immediately migrate
+            to the CPU that unblocked it.</para> 
+ 
+            <para>The rationale for allowing this eager migration is
+            that it tends to move threads that are communicating with
+            each other onto the same CPU; however there are
+            pathalogical situations where it turns out to be a poor
+            strategy.  Depending on the communication pattern in your
+            program, it may or may not be a good idea.</para>
+          </listitem>
+        </varlistentry>
+       </variablelist>
     </sect2>
       
     <sect2>
-- 
1.7.10.4