[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

diff --git a/ghc/docs/users_guide/faq.sgml b/ghc/docs/users_guide/faq.sgml
index dd7225b..8055d15 100644 (file)
--- 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 (file)
--- 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 (file)
--- 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>