<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>
<para>which gives this heap profile when run:</para>
- <imagedata fileref="prof_scc.png"/>
+ <!-- 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>
<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>
<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>
</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>
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>
<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, use a <option>-r</option> RTS
- option<indexterm><primary>-r RTS option</primary></indexterm>.
- See <xref linkend="runtime-control"/>.</para>
+ <para>
+ To get your compiled program to spit out the ticky-ticky
+ numbers:
- <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>
+ <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
+ profilng.
+ </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>
+ 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: ***
-->