From 8c58d23464c76f52c6aad7e6653908eb99e64743 Mon Sep 17 00:00:00 2001
From: simonmar <unknown>
Date: Mon, 11 Nov 2002 15:49:58 +0000
Subject: [PATCH] [project @ 2002-11-11 15:49:58 by simonmar] - embelish the
 documentation for +RTS -xc a bit

- add some more question/answer pairs to the FAQ
---
 ghc/docs/users_guide/faq.sgml             |   75 +++++++++++++++++++++++++++++
 ghc/docs/users_guide/profiling.sgml       |    2 +-
 ghc/docs/users_guide/runtime_control.sgml |   17 +++++++
 3 files changed, 93 insertions(+), 1 deletion(-)

diff --git a/ghc/docs/users_guide/faq.sgml b/ghc/docs/users_guide/faq.sgml
index dd7225b..8055d15 100644
--- a/ghc/docs/users_guide/faq.sgml
+++ b/ghc/docs/users_guide/faq.sgml
@@ -202,6 +202,81 @@
         with g++ and gcc 3.0.</para>
       </listitem>
     </varlistentry>
+
+    <varlistentry>
+      <term>My program is failing with <literal>head []</literal>, or
+      an array bounds error, or some other random error, and I have no
+      idea how to find the bug.  Can you help?</term>
+
+      <listitem>
+	<para>Compile your program with <literal>-prof
+-auto-all</literal> (make sure you have the profiling libraries
+installed), and run it with <literal>+RTS -xc -RTS</literal> to get a
+&ldquo;stack trace&rdquo; at the point at which the exception was
+raised.  See <xref linkend="rts-options-debugging"> for more
+details.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>How do I increase the heap size permanently for a given
+      binary?</term>
+      <listitem>
+	<para>See <xref linkend="rts-hooks">.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>I'm trying to compile my program for parallel execution
+      with the <option>-parallel</option>, and GHC complains with an
+      error like &ldquo;failed to load interface file for
+      Prelude&rdquo;.</term>
+      <listitem>
+	<para>GHC doesn't ship with support for parallel execution,
+	that support is provided separately by the <ulink
+							  url="http://www.macs.hw.ac.uk/~dsg/gph/">GPH</ulink> project.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>When is it safe to use
+      <literal>unsafePerformIO</literal>?</term>
+      <listitem>
+	<para>We'll give two answers to this question, each of which
+	may be helpful.  These criteria are not rigorous in any real
+	sense (you'd need a formal semantics for Haskell in order to
+	give a proper answer to this question), but should give you a
+	feel for the kind of things you can and cannot do with
+	<literal>unsafePerformIO</literal>.</para>
+	
+	<itemizedlist>
+	  <listitem>
+	    <para>It is safe to implement a function or API using
+	    <literal>unsafePerformIO</literal> if you could imagine
+	    also implementing the same function or API in Haskell
+	    without using <literal>unsafePerformIO</literal> (forget
+	    about efficiency, just consider the semantics).</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>In pure Haskell, the value of a function depends
+	    only on the values of its arguments (and free variables,
+	    if it has any).  If you can implement the function using
+	    <literal>unsafePerformIO</literal> and still retain this
+	    invariant, then you're probably using
+	    <literal>unsafePerformIO</literal> in a safe way.  Note
+	    that you need only consider the
+	    <emphasis>observable</emphasis> values of the arguments
+	    and result.</para>
+	  </listitem>
+	</itemizedlist>
+	
+	<para>For more information, see <ulink
+	url="http://www.haskell.org/pipermail/glasgow-haskell-users/2002-July/003681.html">this
+	thread</ulink>.</para>
+      </listitem>
+    </varlistentry>
+
   </variablelist>
 </chapter>
 
diff --git a/ghc/docs/users_guide/profiling.sgml b/ghc/docs/users_guide/profiling.sgml
index 6621645..b89cf65 100644
--- a/ghc/docs/users_guide/profiling.sgml
+++ b/ghc/docs/users_guide/profiling.sgml
@@ -45,7 +45,7 @@
     
   </orderedlist>
   
-  <sect1>
+  <sect1 id="cost-centres">
     <title>Cost centres and cost-centre stacks</title>
     
     <para>GHC's profiling system assigns <firstterm>costs</firstterm>
diff --git a/ghc/docs/users_guide/runtime_control.sgml b/ghc/docs/users_guide/runtime_control.sgml
index f8e43d9..8e2e13e 100644
--- a/ghc/docs/users_guide/runtime_control.sgml
+++ b/ghc/docs/users_guide/runtime_control.sgml
@@ -430,6 +430,23 @@
 	  -auto-all</literal> and running with <literal>+RTS -xc
 	  -RTS</literal> will tell you exactly the call stack at the
 	  point the error was raised.</para>
+
+	  <para>The output contains one line for each exception raised
+	  in the program (the program might raise and catch several
+	  exceptions during its execution), where each line is of the
+	  form:</para>
+
+<screen>
+&lt; cc<subscript>1</subscript>, ..., cc<subscript>n</subscript> &gt;
+</screen>
+	  <para>each <literal>cc</literal><subscript>i</subscript> is
+	  a cost centre in the program (see <xref
+	  linkend="cost-centres">), and the sequence represents the
+	  &ldquo;call stack&rdquo; at the point the exception was
+	  raised.  The leftmost item is the innermost function in the
+	  call stack, and the rightmost item is the outermost
+	  function.</para>
+
 	</listitem>
       </varlistentry>
 
-- 
1.7.10.4