<para> Glasgow Haskell comes with a time and space profiling
system. Its purpose is to help you improve your understanding of
your program's execution behaviour, so you can improve it.</para>
-
+
<para> Any comments, suggestions and/or improvements you have are
welcome. Recommended “profiling tricks” would be
especially cool! </para>
<listitem>
<para> Run your program with one of the profiling options, eg.
<literal>+RTS -p -RTS</literal>. This generates a file of
- profiling information.</para>
+ profiling information. Note that multi-processor execution
+ (e.g. <literal>+RTS -N2</literal>) is not supported while
+ profiling.</para>
<indexterm><primary><option>-p</option></primary><secondary>RTS
option</secondary></indexterm>
</listitem>
-
+
<listitem>
<para> Examine the generated profiling information, using one of
GHC's profiling tools. The tool to use will depend on the kind
of profiling information generated.</para>
</listitem>
-
+
</orderedlist>
-
+
<sect1 id="cost-centres">
<title>Cost centres and cost-centre stacks</title>
-
+
<para>GHC's profiling system assigns <firstterm>costs</firstterm>
to <firstterm>cost centres</firstterm>. A cost is simply the time
or space required to evaluate an expression. Cost centres are
<para>Cost centres are just program annotations. When you say
<option>-auto-all</option> to the compiler, it automatically
inserts a cost centre annotation around every top-level function
- in your program, but you are entirely free to add the cost
- centre annotations yourself.</para>
+ not marked INLINE in your program, but you are entirely free to
+ add the cost centre annotations yourself.</para>
<para>The syntax of a cost centre annotation is</para>
in the profiling output, and
<literal><expression></literal> is any Haskell
expression. An <literal>SCC</literal> annotation extends as
- far to the right as possible when parsing.</para>
+ far to the right as possible when parsing. (SCC stands for "Set
+ Cost Centre").</para>
+
+ <para>Here is an example of a program with a couple of SCCs:</para>
+
+<programlisting>
+main :: IO ()
+main = do let xs = {-# SCC "X" #-} [1..1000000]
+ let ys = {-# SCC "Y" #-} [1..2000000]
+ print $ last xs
+ print $ last $ init xs
+ print $ last ys
+ print $ last $ init ys
+</programlisting>
+
+ <para>which gives this heap profile when run:</para>
+
+ <!-- contentwidth/contentheight don't appear to have any effect
+ other than making the PS file generation work, rather than
+ falling over. The result seems to be broken PS on the page
+ with the image. -->
+ <imagedata fileref="prof_scc" contentwidth="645px"
+ contentdepth="428px"/>
</sect2>
</listitem>
</varlistentry>
</variablelist>
-
+
<para>There are a few other profiling-related compilation options.
Use them <emphasis>in addition to</emphasis>
<option>-prof</option>. These do not have to be used consistently
<listitem>
<para> GHC will automatically add
<function>_scc_</function> constructs for all
- top-level, exported functions.</para>
+ top-level, exported functions not marked INLINE. If you
+ want a cost centre on an INLINE function, you have to add
+ it manually.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<option>-auto-all</option>:
<indexterm><primary><option>-auto-all</option></primary></indexterm>
</term>
<listitem>
- <para> <emphasis>All</emphasis> top-level functions,
- exported or not, will be automatically
- <function>_scc_</function>'d.</para>
+ <para> <emphasis>All</emphasis> top-level functions
+ not marked INLINE, exported or not, will be automatically
+ <function>_scc_</function>'d.
+ The functions marked INLINE must be given a cost centre
+ manually.</para>
</listitem>
</varlistentry>
<variablelist>
<varlistentry>
<term>
- <option>-p</option> or <option>-P</option>:
+ <option>-p</option> or <option>-P</option> or <option>-pa</option>:
<indexterm><primary><option>-p</option></primary></indexterm>
<indexterm><primary><option>-P</option></primary></indexterm>
+ <indexterm><primary><option>-pa</option></primary></indexterm>
<indexterm><primary>time profile</primary></indexterm>
</term>
<listitem>
<para>The <option>-P</option> option produces a more
detailed report containing the actual time and allocation
data as well. (Not used much.)</para>
+
+ <para>The <option>-pa</option> option produces the most detailed
+ report containing all cost centres in addition to the actual time
+ and allocation data.</para>
</listitem>
</varlistentry>
+ <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, which is
+ also the sampling interval of the time and allocation profile.
+ The default is 0.02 second.</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>
<option>-xc</option>
</varlistentry>
</variablelist>
-
+
</sect1>
<sect1 id="prof-heap">
file,
<filename><replaceable>prog</replaceable>.ps</filename>. The
<command>hp2ps</command> utility is described in detail in
- <xref linkend="hp2ps"/>.</para>
+ <xref linkend="hp2ps"/>.</para>
</listitem>
<listitem>
<para>Display the heap profile using a postscript viewer such
</listitem>
</orderedlist>
+ <para>You might also want to take a look
+ at <ulink url="http://www.haskell.org/haskellwiki/Hp2any">hp2any</ulink>,
+ a more advanced suite of tools (not distributed with GHC) for
+ displaying heap profiles.</para>
+
<sect2 id="rts-options-heap-prof">
<title>RTS options for heap profiling</title>
represent an approximation to the actual type.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<option>-hr</option>
to display a profile by type but only for data produced by a
certain module, or a profile by retainer for a certain type of
data. Restrictions are specified as follows:</para>
-
+
<variablelist>
<varlistentry>
<term>
types.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<option>-hr</option><replaceable>cc</replaceable>,...
0.1 second). Fractions are allowed: for example
<option>-i0.2</option> will get 5 samples per second.
This only affects heap profiling; time profiles are always
- sampled on a 1/50 second frequency.</para>
+ sampled with the frequency of the RTS clock. See
+ <xref linkend="prof-time-options"/> for changing that.</para>
</listitem>
</varlistentry>
state in addition to the space allocated for its stack
(stacks normally start small and then grow as
necessary).</para>
-
+
<para>This includes the main thread, so using
<option>-xt</option> is a good way to see how much stack
space the program is using.</para>
</variablelist>
</sect2>
-
+
<sect2 id="retainer-prof">
<title>Retainer Profiling</title>
set <literal>MANY</literal>. The maximum set size defaults to 8
and can be altered with the <option>-R</option> RTS
option:</para>
-
+
<variablelist>
<varlistentry>
<term><option>-R</option><replaceable>size</replaceable></term>
<screen>
<replaceable>prog</replaceable> +RTS -hr -hcB
</screen>
-
+
<para>This trick isn't foolproof, because there might be other
B closures in the heap which aren't the retainers we are
interested in, but we've found this to be a useful technique
<indexterm><primary>heap profiles</primary></indexterm>
<indexterm><primary>postscript, from heap profiles</primary></indexterm>
<indexterm><primary><option>-h<break-down></option></primary></indexterm>
-
+
<para>Usage:</para>
-
+
<screen>
hp2ps [flags] [<file>[.hp]]
</screen>
<para>The flags are:</para>
<variablelist>
-
+
<varlistentry>
<term><option>-d</option></term>
<listitem>
<para>Use a small box for the title.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term><option>-t<float></option></term>
<listitem>
<para>Generate colour output.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term><option>-y</option></term>
<listitem>
<para>Ignore marks.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term><option>-?</option></term>
<listitem>
<sect2 id="manipulating-hp">
<title>Manipulating the hp file</title>
-<para>(Notes kindly offered by Jan-Willhem Maessen.)</para>
+<para>(Notes kindly offered by Jan-Willem Maessen.)</para>
<para>
The <filename>FOO.hp</filename> file produced when you ask for the
heap profile as described in the previous section. Run <command>gv</command> on your
profile:
<screen>
- gv -watch -seascape FOO.ps
+ gv -watch -seascape FOO.ps
</screen>
If you forget the <literal>-watch</literal> flag you can still select
"Watch file" from the "State" menu. Now each time you generate a new
head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \
| hp2ps > FOO.ps
kill -HUP $gvpsnum
- done
+ done
</screen>
</para>
</sect2>
<indexterm><primary>hpc</primary></indexterm>
<para>
- Code coverage tools allow a programer to determine what parts of
+ Code coverage tools allow a programmer to determine what parts of
their code have been actually executed, and which parts have
never actually been invoked. GHC has an option for generating
instrumented code that records code coverage as part of the
a yellow background indicates a part of the program that was
never evaluated; a green background indicates an always-True
expression and a red background indicates an always-False one.
- </para>
+ </para>
<sect2><title>A small example: Reciprocation</title>
</para>
<screen>
-$ ghc -fhpc Recip.hs --make
+$ ghc -fhpc Recip.hs --make
</screen>
- <para>HPC index (.mix) files are placed placed in .hpc subdirectory. These can be considered like
- the .hi files for HPC.
+ <para>HPC index (.mix) files are placed in .hpc subdirectory. These can be considered like
+ the .hi files for HPC.
</para>
<screen>
$ ./Recip
$ hpc report Recip
80% expressions used (81/101)
12% boolean coverage (1/8)
- 14% guards (1/7), 3 always True,
- 1 always False,
+ 14% guards (1/7), 3 always True,
+ 1 always False,
2 unevaluated
0% 'if' conditions (0/1), 1 always False
100% qualifiers (0/0)
hpc_index.html, hpc_index_alt.html, hpc_index_exp.html,
hpc_index_fun.html.
</para>
- </sect2>
+ </sect2>
<sect2><title>Options for instrumenting code for coverage</title>
<para>
- Turning on code coverage is easy, use the -fhpc flag.
+ Turning on code coverage is easy, use the -fhpc flag.
Instrumented and non-instrumented can be freely mixed.
When compiling the Main module GHC automatically detects when there
is an hpc compiled file, and adds the correct initialization code.
<para>
The hpc toolkit uses a cvs/svn/darcs-like interface, where a
- single binary contains many function units.</para>
+ single binary contains many function units.</para>
<screen>
-$ hpc
+$ hpc
Usage: hpc COMMAND ...
Commands:
report Output textual report about program coverage
markup Markup Haskell source with program coverage
Processing Coverage files:
- combine Combine multiple .tix files in a single .tix files
+ sum Sum multiple .tix files in a single .tix file
+ combine Combine two .tix files in a single .tix file
+ map Map a function over a single .tix file
Coverage Overlays:
overlay Generate a .tix file from an overlay file
draft Generate draft overlay that provides 100% coverage
<para>In general, these options act on .tix file after an
instrumented binary has generated it, which hpc acting as a
conduit between the raw .tix file, and the more detailed reports
- produced.
+ produced.
</para>
-
+
<para>
The hpc tool assumes you are in the top-level directory of
the location where you built your application, and the .tix
--srcdir multiple times to analyse programs compiled from
difference locations, as is typical for packages.
</para>
-
+
<para>
We now explain in more details the major modes of hpc.
</para>
all modules and packages are considered in generating report,
unless include or exclude are used. The report is a summary
unless the --per-module flag is used. The --xml-output option
- allows for tools to use hpc to glean coverage.
- </para>
+ allows for tools to use hpc to glean coverage.
+ </para>
<screen>
$ hpc help report
Usage: hpc report [OPTION] .. <TIX_FILE> [<MODULE> [<MODULE> ..]]
<para>hpc markup marks up source files into colored html.
</para>
<screen>
-% hpc help markup
+$ hpc help markup
Usage: hpc markup [OPTION] .. <TIX_FILE> [<MODULE> [<MODULE> ..]]
Options:
</screen>
</sect3>
+ <sect3><title>hpc sum</title>
+ <para>hpc sum adds together any number of .tix files into a single
+ .tix file. hpc sum does not change the original .tix file; it generates a new .tix file.
+ </para>
+<screen>
+$ hpc help sum
+Usage: hpc sum [OPTION] .. <TIX_FILE> [<TIX_FILE> [<TIX_FILE> ..]]
+Sum multiple .tix files in a single .tix file
+
+Options:
+
+ --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE
+ --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE
+ --output=FILE output FILE
+ --union use the union of the module namespace (default is intersection)
+</screen>
+ </sect3>
<sect3><title>hpc combine</title>
- <para>hpc combine is the swiss army knife of hpc. Typically, combine is used
- to add .tix files together to get the combined total coverage. However, it can
- also be used to take the difference between .tix files, to subtract one
- .tix file from another, and to zero the .tix files. hpc combine does not
- change the original .tix file; it generates a new .tix file.
+ <para>hpc combine is the swiss army knife of hpc. It can be
+ used to take the difference between .tix files, to subtract one
+ .tix file from another, or to add two .tix files. hpc combine does not
+ change the original .tix file; it generates a new .tix file.
+ </para>
+<screen>
+$ hpc help combine
+Usage: hpc combine [OPTION] .. <TIX_FILE> <TIX_FILE>
+Combine two .tix files in a single .tix file
+
+Options:
+
+ --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE
+ --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE
+ --output=FILE output FILE
+ --function=FUNCTION combine .tix files with join function, default = ADD
+ FUNCTION = ADD | DIFF | SUB
+ --union use the union of the module namespace (default is intersection)
+</screen>
+ </sect3>
+ <sect3><title>hpc map</title>
+ <para>hpc map inverts or zeros a .tix file. hpc map does not
+ change the original .tix file; it generates a new .tix file.
</para>
<screen>
-hpc help combine
-Usage: hpc combine [OPTION] .. <TIX_FILE> [<TIX_FILE> [<TIX_FILE> ..]]
+$ hpc help map
+Usage: hpc map [OPTION] .. <TIX_FILE>
+Map a function over a single .tix file
Options:
--exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE
--include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE
--output=FILE output FILE
- --combine=FUNCTION combine .tix files with join function, default = ADD
- FUNCTION = ADD | DIFF | SUB | ZERO
- --post-invert invert output; ticked becomes unticked, unticked becomes ticked
+ --function=FUNCTION apply function to .tix files, default = ID
+ FUNCTION = ID | INV | ZERO
+ --union use the union of the module namespace (default is intersection)
</screen>
</sect3>
<sect3><title>hpc overlay and hpc draft</title>
--hpcdir=DIR sub-directory that contains .mix files
default .hpc [rarely used]
--output=FILE output FILE
-% hpc help draft
+% hpc help draft
Usage: hpc draft [OPTION] .. <TIX_FILE>
Options:
<para>(ToDo: document properly.)</para>
- <para>It is possible to compile Glasgow Haskell programs so that
+ <para>It is possible to compile Haskell programs so that
they will count lots and lots of interesting things, e.g., number
of updates, number of data constructors entered, etc., etc. We
call this “ticky-ticky”
profiling,<indexterm><primary>ticky-ticky
profiling</primary></indexterm> <indexterm><primary>profiling,
- ticky-ticky</primary></indexterm> because that's the sound a Sun4
+ ticky-ticky</primary></indexterm> because that's the sound a CPU
makes when it is running up all those counters
(<emphasis>slowly</emphasis>).</para>
it is quite separate from the main “cost-centre”
profiling system, intended for all users everywhere.</para>
- <para>To be able to use ticky-ticky profiling, you will need to
- have built the ticky RTS. (This should be described in
- the building guide, but amounts to building the RTS with way
- "t" enabled.)</para>
+ <para>
+ You don't need to build GHC, the libraries, or the RTS a special
+ way in order to use ticky-ticky profiling. You can decide on a
+ module-by-module basis which parts of a program have the
+ counters compiled in, using the
+ compile-time <option>-ticky</option> option. Those modules that
+ were not compiled with <option>-ticky</option> won't contribute
+ to the ticky-ticky profiling results, and that will normally
+ include all the pre-compiled packages that your program links
+ with.
+ </para>
+
+ <para>
+ To get your compiled program to spit out the ticky-ticky
+ numbers:
- <para>To get your compiled program to spit out the ticky-ticky
- numbers, use a <option>-r</option> RTS
- option<indexterm><primary>-r RTS option</primary></indexterm>.
- See <xref linkend="runtime-control"/>.</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Link the program with <option>-debug</option>
+ (<option>-ticky</option> is a synonym
+ for <option>-debug</option> at link-time). This links in
+ the debug version of the RTS, which includes the code for
+ aggregating and reporting the results of ticky-ticky
+ profiling.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Run the program with the <option>-r</option> RTS
+ option<indexterm><primary>-r RTS option</primary></indexterm>.
+ See <xref linkend="runtime-control"/>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
- <para>Compiling your program with the <option>-ticky</option>
- switch yields an executable that performs these counts. Here is a
- sample ticky-ticky statistics file, generated by the invocation
- <command>foo +RTS -rfoo.ticky</command>.</para>
+ <para>
+ Here is a sample ticky-ticky statistics file, generated by
+ the invocation
+ <command>foo +RTS -rfoo.ticky</command>.
+ </para>
<screen>
foo +RTS -rfoo.ticky
-
ALLOCATIONS: 3964631 (11330900 words total: 3999476 admin, 6098829 goods, 1232595 slop)
total words: 2 3 4 5 6+
69647 ( 1.8%) function values 50.0 50.0 0.0 0.0 0.0
<!-- Emacs stuff:
;;; Local Variables: ***
- ;;; mode: xml ***
;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
;;; End: ***
-->
projects / ghc-hetmet.git / blobdiff