will contain something like this:</para>
<screen>
- Tue Apr 18 12:52 2000 Time and Allocation Profiling Report (Final)
+ Fri May 12 14:06 2000 Time and Allocation Profiling Report (Final)
Main +RTS -p -RTS
nfib Main 100.0 100.0
-COST CENTRE MODULE scc %time %alloc inner cafs
+ individual inherited
+COST CENTRE MODULE scc %time %alloc %time %alloc
-MAIN MAIN 0 0.0 0.0 0 1
- main Main 0 0.0 0.0 0 1
- CAF PrelHandle 3 0.0 0.0 0 3
- CAF PrelAddr 1 0.0 0.0 0 0
- CAF Main 6 0.0 0.0 1 0
- main Main 1 0.0 0.0 1 1
- nfib Main 242785 100.0 100.0 242784 4
+MAIN MAIN 0 0.0 0.0 100.0 100.0
+ main Main 0 0.0 0.0 0.0 0.0
+ CAF PrelHandle 3 0.0 0.0 0.0 0.0
+ CAF PrelAddr 1 0.0 0.0 0.0 0.0
+ CAF Main 6 0.0 0.0 100.0 100.0
+ main Main 1 0.0 0.0 100.0 100.0
+ nfib Main 242785 100.0 100.0 100.0 100.0
</screen>
the costly call to <function>nfib</function> came from
<function>main</function>.</para>
+ <para>The time and allocation incurred by a given part of the
+ program is displayed in two ways: “individual”, which
+ are the costs incurred by the code covered by this cost centre
+ stack alone, and “inherited”, which includes the costs
+ incurred by all the children of this node.</para>
+
<para>The usefulness of cost-centre stacks is better demonstrated
by modifying the example slightly:</para>
the new profiling results:</para>
<screen>
-COST CENTRE MODULE scc %time %alloc inner cafs
-
-MAIN MAIN 0 0.0 0.0 0 1
- main Main 0 0.0 0.0 0 1
- CAF PrelHandle 3 0.0 0.0 0 3
- CAF PrelAddr 1 0.0 0.0 0 0
- CAF Main 9 0.0 0.0 1 1
- main Main 1 0.0 0.0 2 2
- g Main 1 0.0 0.0 1 3
- nfib Main 465 0.0 0.2 464 0
- f Main 1 0.0 0.0 1 1
- nfib Main 242785 100.0 99.8 242784 1
+COST CENTRE MODULE scc %time %alloc %time %alloc
+
+MAIN MAIN 0 0.0 0.0 100.0 100.0
+ main Main 0 0.0 0.0 0.0 0.0
+ CAF PrelHandle 3 0.0 0.0 0.0 0.0
+ CAF PrelAddr 1 0.0 0.0 0.0 0.0
+ CAF Main 9 0.0 0.0 100.0 100.0
+ main Main 1 0.0 0.0 100.0 100.0
+ g Main 1 0.0 0.0 0.0 0.2
+ nfib Main 465 0.0 0.2 0.0 0.2
+ f Main 1 0.0 0.0 100.0 99.8
+ nfib Main 242785 100.0 99.8 100.0 99.8
</screen>
<para>Now although we had two calls to <function>nfib</function>
<variablelist>
<varlistentry>
- <term>scc</term>
+ <term>entries</term>
<listitem>
<para>The number of times this particular point in the call
graph was entered.</para>
</varlistentry>
<varlistentry>
- <term>%time</term>
+ <term>individual %time</term>
<listitem>
<para>The percentage of the total run time of the program
spent at this point in the call graph.</para>
</varlistentry>
<varlistentry>
- <term>%alloc</term>
+ <term>individual %alloc</term>
<listitem>
<para>The percentage of the total memory allocations
(excluding profiling overheads) of the program made by this
</varlistentry>
<varlistentry>
- <term>inner</term>
+ <term>inherited %time</term>
<listitem>
- <para>The number of times an inner call-graph context was
- entered from here (including recursive calls).</para>
+ <para>The percentage of the total run time of the program
+ spent below this point in the call graph.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>cafs</term>
+ <term>inherited %alloc</term>
<listitem>
- <para>The number of times a CAF context was entered from
- here. CAFs are described in <xref
- linkend="prof-rules">.</para>
+ <para>The percentage of the total memory allocations
+ (excluding profiling overheads) of the program made by this
+ call and all of its sub-calls.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The syntax of a cost centre annotation is</para>
<programlisting>
- _scc_ "name" <expression>
+ {-# SCC "name" #-} <expression>
</programlisting>
<para>where <literal>"name"</literal> is an aribrary string,
that will become the name of your cost centre as it appears
in the profiling output, and
<literal><expression></literal> is any Haskell
- expression. An <literal>_scc_</literal> annotation extends as
+ expression. An <literal>SCC</literal> annotation extends as
far to the right as possible when parsing.</para>
</sect2>
<para>If the expression is part of the
<firstterm>one-off</firstterm> costs of evaluating the
enclosing top-level definition, then costs are attributed to
- the stack of lexically enclosing <literal>_scc_</literal>
+ the stack of lexically enclosing <literal>SCC</literal>
annotations on top of the special <literal>CAF</literal>
cost-centre. </para>
</listitem>
<listitem>
<para>Otherwise, costs are attributed to the stack of
- lexically-enclosing <literal>_scc_</literal> annotations,
+ lexically-enclosing <literal>SCC</literal> annotations,
appended to the cost-centre stack in effect at the
<firstterm>call site</firstterm> of the current top-level
definition<footnote> <para>The call-site is just the place
<para>You can view the time and allocation profiling graph of your
program graphically, using <command>ghcprof</command>. This is a
- new tool with GHC 4.07, and will eventually be the de-facto
+ new tool with GHC 4.08, and will eventually be the de-facto
standard way of viewing GHC profiles.</para>
<para>To run <command>ghcprof</command>, you need
</varListEntry>
<varlistentry>
+ <term><Option>-h<filtering-options></Option>:</Term>
+ <indexterm><primary><option>-h<filtering-options>
+ </option></primary></indexterm>
+ <indexterm><primary>heap profile filtering options</primary></indexterm>
+ <listItem>
+ <Para>It's often useful to select just some subset of the
+ heap when profiling. To do this, the following filters are
+ available. You may use multiple filters, in which case a
+ closure has to satisfy all filters to appear in the final
+ profile. Filtering criterion are independent of what it is
+ you ask to see. So, for example, you can specify a profile
+ by closure description (<Literal>-hD</literal>) but ask to
+ filter closures by producer module (<Literal>-hm{...}</literal>).
+ </para>
+
+ <Para>Available filters are:</para>
+
+ <variableList>
+
+ <varListEntry>
+ <term><Option>-hc{cc1, cc2 .. ccN}</Option>:</Term>
+ <listItem>
+ <Para>Restrict to one of the specified cost centers.
+ Since GHC deals in cost center stacks, the specified
+ cost centers pertain to the top stack element. For
+ example, <Literal>-hc{Wurble,Burble}</literal> selects
+ all cost center stacks whose top element is
+ <Literal>Wurble</literal> or
+ <Literal>Burble</literal>.
+ </para>
+ </listItem>
+ </varListEntry>
+
+ <varListEntry>
+ <term><Option>-hm{module1, module2 .. moduleN}</Option>:</Term>
+ <listItem>
+ <Para>Restrict to closures produced by functions in
+ one of the specified modules.
+ </Para>
+ </listItem>
+ </varListEntry>
+
+ <varListEntry>
+ <term><Option>-hd{descr1, descr2 .. descrN}</Option>:</Term>
+ <listItem>
+ <Para>Restrict to closures whose description-string is
+ one of the specified descriptions. Description
+ strings are pretty arcane. An easy way to find
+ plausible strings to specify is to first do a
+ <Literal>-hD</literal> profile and then inspect the
+ description-strings which appear in the resulting profile.
+ </Para>
+ </listItem>
+ </varListEntry>
+
+ <varListEntry>
+ <term><Option>-hy{type1, type2 .. typeN}</Option>:</Term>
+ <listItem>
+ <Para>Restrict to closures having one of the specified
+ types.
+ </Para>
+ </listItem>
+ </varListEntry>
+ </variableList>
+
+ </listItem>
+ </varListEntry>
+
+ <varlistentry>
<term><option>-hx</option>:</term>
<indexterm><primary><option>-hx</option></primary></indexterm>
<listitem>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>-xc</option></term>
+ <indexterm><primary><option>-xc</option></primary><secondary>RTS
+ option</secondary></indexterm>
+ <listitem>
+ <para>This option makes use of the extra information
+ maintained by the cost-centre-stack profiler to provide
+ useful information about the location of runtime errors.
+ See <xref linkend="rts-options-debugging">.</para>
+ </listitem>
+ </varlistentry>
+
</variableList>
</sect1>
projects / ghc-hetmet.git / blobdiff