Commit 837c6e35 authored by Simon Marlow's avatar Simon Marlow

Update docs on ticky-ticky profiling

parent ad923917
......@@ -1556,7 +1556,7 @@ phase <replaceable>n</replaceable></entry>
</row>
<row>
<entry><option>-ticky</option></entry>
<entry>Turn on ticky-ticky profiling</entry>
<entry><link linkend="ticky-ticky">Turn on ticky-ticky profiling</link></entry>
<entry>static</entry>
<entry>-</entry>
</row>
......
......@@ -1596,13 +1596,13 @@ 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 &ldquo;ticky-ticky&rdquo;
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>
......@@ -1610,25 +1610,52 @@ Options:
it is quite separate from the main &ldquo;cost-centre&rdquo;
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
......
......@@ -973,20 +973,13 @@
</term>
<listitem>
<para>Produce &ldquo;ticky-ticky&rdquo; statistics at the
end of the program run. The <replaceable>file</replaceable>
business works just like on the <option>-S</option> RTS
option (above).</para>
<para>&ldquo;Ticky-ticky&rdquo; statistics are counts of
various program actions (updates, enters, etc.) The program
must have been compiled using
<option>-ticky</option><indexterm><primary><option>-ticky</option></primary></indexterm>
(a.k.a. &ldquo;ticky-ticky profiling&rdquo;), and, for it to
be really useful, linked with suitable system libraries.
Not a trivial undertaking: consult the installation guide on
how to set things up for easy &ldquo;ticky-ticky&rdquo;
profiling. For more information, see <xref
linkend="ticky-ticky"/>.</para>
end of the program run (only available if the program was
linked with <option>-debug</option>).
The <replaceable>file</replaceable> business works just like
on the <option>-S</option> RTS option, above.</para>
<para>For more information on ticky-ticky profiling, see
<xref linkend="ticky-ticky"/>.</para>
</listitem>
</varlistentry>
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment