diff options
Diffstat (limited to 'docs/users_guide/runtime_control.xml')
| -rw-r--r-- | docs/users_guide/runtime_control.xml | 56 |
1 files changed, 38 insertions, 18 deletions
diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml index 2af87bcc41..20aca07cd3 100644 --- a/docs/users_guide/runtime_control.xml +++ b/docs/users_guide/runtime_control.xml @@ -1068,7 +1068,7 @@ char *ghc_rts_opts = "-H128m -K1m"; option</secondary></indexterm> </term> <listitem> - <para>Generates a basic heap profile, in the + <para>(can be shortened to <option>-h</option>.) Generates a basic heap profile, in the file <literal><replaceable>prog</replaceable>.hp</literal>. To produce the heap profile graph, use <command>hp2ps</command> (see <xref linkend="hp2ps" @@ -1101,7 +1101,7 @@ char *ghc_rts_opts = "-H128m -K1m"; <para> In binary format to a file for later analysis by a variety of tools. One such tool - is <ulink url="http://hackage.haskell.org/package/ThreadScope">ThreadScope</ulink><indexterm><primary>ThreadScope</primary></indexterm>, + is <ulink url="http://www.haskell.org/haskellwiki/ThreadScope">ThreadScope</ulink><indexterm><primary>ThreadScope</primary></indexterm>, which interprets the event log to produce a visual parallel execution profile of the program. </para> @@ -1314,33 +1314,53 @@ char *ghc_rts_opts = "-H128m -K1m"; <para>(Only available when the program is compiled for profiling.) When an exception is raised in the program, this option causes the current cost-centre-stack to be - dumped to <literal>stderr</literal>.</para> + dumped to <literal>stderr</literal>.</para> <para>This can be particularly useful for debugging: if your program is complaining about a <literal>head []</literal> error and you haven't got a clue which bit of code is causing it, compiling with <literal>-prof - -auto-all</literal> and running with <literal>+RTS -xc + -fprof-auto</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> + <para>The output contains one report for each exception + raised in the program (the program might raise and catch + several exceptions during its execution), where each report + looks something like this: + </para> <screen> -< cc<subscript>1</subscript>, ..., cc<subscript>n</subscript> > +*** Exception raised (reporting due to +RTS -xc), stack trace: + GHC.List.CAF + --> evaluated by: Main.polynomial.table_search, + called from Main.polynomial.theta_index, + called from Main.polynomial, + called from Main.zonal_pressure, + called from Main.make_pressure.p, + called from Main.make_pressure, + called from Main.compute_initial_state.p, + called from Main.compute_initial_state, + called from Main.CAF + ... </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 - “call stack” 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> + <para>The stack trace may often begin with something + uninformative like <literal>GHC.List.CAF</literal>; this is + an artifact of GHC's optimiser, which lifts out exceptions + to the top-level where the profiling system assigns them to + the cost centre "CAF". However, <literal>+RTS -xc</literal> + doesn't just print the current stack, it looks deeper and + reports the stack at the time the CAF was evaluated, and it + may report further stacks until a non-CAF stack is found. In + the example above, the next stack (after <literal>--> + evaluated by</literal>) contains plenty of information about + what the program was doing when it evaluated <literal>head + []</literal>.</para> + + <para>Implementation details aside, the function names in + the stack should hopefully give you enough clues to track + down the bug.</para> + </listitem> </varlistentry> <varlistentry> |