Document +RTS --info, and make it a Read'able Haskell value

[ghc-hetmet.git] / docs / users_guide / runtime_control.xml

diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml
index 995e263..776b65f 100644 (file)
--- a/docs/users_guide/runtime_control.xml
+++ b/docs/users_guide/runtime_control.xml
@@ -85,6 +85,54 @@
 
   </sect2>
 
+  <sect2 id="rts-options-misc">
+    <title>Miscellaneous RTS options</title>
+
+    <variablelist>
+     <varlistentry>
+       <term><option>-V<replaceable>secs</replaceable></option>
+       <indexterm><primary><option>-V</option></primary><secondary>RTS
+       option</secondary></indexterm></term>
+       <listitem>
+         <para>Sets the interval that the RTS clock ticks at.  The
+         runtime uses a single timer signal to count ticks; this timer
+         signal is used to control the context switch timer (<xref
+         linkend="using-concurrent" />) and the heap profiling
+         timer <xref linkend="rts-options-heap-prof" />.  Also, the
+         time profiler uses the RTS timer signal directly to record
+         time profiling samples.</para>
+
+         <para>Normally, setting the <option>-V</option> option
+         directly is not necessary: the resolution of the RTS timer is
+         adjusted automatically if a short interval is requested with
+         the <option>-C</option> or <option>-i</option> options.
+         However, setting <option>-V</option> is required in order to
+         increase the resolution of the time profiler.</para>
+
+         <para>Using a value of zero disables the RTS clock
+         completetly, and has the effect of disabling timers that
+         depend on it: the context switch timer and the heap profiling
+         timer.  Context switches will still happen, but
+         deterministically and at a rate much faster than normal.
+         Disabling the interval timer is useful for debugging, because
+         it eliminates a source of non-determinism at runtime.</para>
+       </listitem>
+     </varlistentry>
+
+     <varlistentry>
+       <term><option>--install-signal-handlers=<replaceable>yes|no</replaceable></option>
+       <indexterm><primary><option>--install-signal-handlers</option></primary><secondary>RTS
+       option</secondary></indexterm></term>
+       <listitem>
+         <para>If yes (the default), the RTS installs signal handlers to catch
+         things like ctrl-C. This option is primarily useful for when
+         you are using the Haskell code as a DLL, and want to set your
+         own signal handlers.</para>
+       </listitem>
+     </varlistentry>
+    </variablelist>
+  </sect2>
+
   <sect2 id="rts-options-gc">
     <title>RTS options to control the garbage collector</title>
 
@@ -398,11 +446,12 @@
   </sect2>
 
   <sect2>
-    <title>RTS options for profiling and Concurrent/Parallel Haskell</title>
+    <title>RTS options for profiling and parallelism</title>
 
     <para>The RTS options related to profiling are described in <xref
-    linkend="rts-options-heap-prof"/>; and those for concurrent/parallel
-    stuff, in <xref linkend="parallel-rts-opts"/>.</para>
+    linkend="rts-options-heap-prof"/>, those for concurrency in
+      <xref linkend="using-concurrent" />, and those for parallelism in
+      <xref linkend="parallel-options"/>.</para>
   </sect2>
 
   <sect2 id="rts-options-debugging">
@@ -612,6 +661,29 @@ char *ghc_rts_opts = "-H128m -K1m";
     <filename>ghc/compiler/parser/hschooks.c</filename> in a GHC
     source tree.</para>
   </sect2>
+
+  <sect2>
+    <title>Getting information about the RTS</title>
+
+    <indexterm><primary>RTS</primary></indexterm>
+
+    <para>It is possible to ask the RTS to give some information about
+    itself. To do this, use the <option>--info</option> flag, e.g.</para>
+<screen>
+$ ./a.out +RTS --info
+ [("GHC RTS", "Yes")
+ ,("GHC version", "6.7")
+ ,("RTS way", "rts_p")
+ ,("Host platform", "x86_64-unknown-linux")
+ ,("Build platform", "x86_64-unknown-linux")
+ ,("Target platform", "x86_64-unknown-linux")
+ ,("Compiler unregisterised", "NO")
+ ,("Tables next to code", "YES")
+ ]
+</screen>
+    <para>The information is formatted such that it can be read as a
+    of type <literal>[(String, String)]</literal>.</para>
+  </sect2>
 </sect1>
 
 <!-- Emacs stuff: