<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.06-7 of 2001-11-14">
<TITLE>
Profiling (ocamlprof)
</TITLE>
</HEAD>
<BODY TEXT=black BGCOLOR=white>
<A HREF="manual030.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<A HREF="manual032.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#2de52d"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc191"><B><FONT SIZE=6>Chapter 17</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=6>Profiling (ocamlprof)</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE> <A NAME="c:profiler"></A>
<BR>
This chapter describes how the execution of Objective Caml
programs can be profiled, by recording how many times functions are
called, branches of conditionals are taken, ...<BR>
<BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#66ff66"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc192"><B><FONT SIZE=5>17.1</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=5>Compiling for profiling</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><BR>
Before profiling an execution, the program must be compiled in
profiling mode, using the <TT>ocamlcp</TT> front-end to the <TT>ocamlc</TT> compiler
(see chapter <A HREF="manual022.html#c:camlc">8</A>). When compiling modules separately,
<TT>ocamlcp</TT> must be used when compiling the modules (production
of <TT>.cmo</TT> files), and can also be used (though this is not strictly
necessary) when linking them together.<BR>
<BR>
<H5>Note</H5> If a module (<TT>.ml</TT> file) doesn't have a corresponding
interface (<TT>.mli</TT> file), then compiling it with <TT>ocamlcp</TT> will produce
object files (<TT>.cmi</TT> and <TT>.cmo</TT>) that are not compatible with the ones
produced by <TT>ocamlc</TT>, which may lead to problems (if the <TT>.cmi</TT> or
<TT>.cmo</TT> is still around) when switching between profiling and
non-profiling compilations. To avoid this problem, you should always
have a <TT>.mli</TT> file for each <TT>.ml</TT> file.<BR>
<BR>
<H5>Note</H5> To make sure your programs can be compiled in
profiling mode, avoid using any identifier that begins with
<TT>__ocaml_prof</TT>.<BR>
<BR>
The amount of profiling information can be controlled through the <TT>-p</TT>
option to <TT>ocamlcp</TT>, followed by one or several letters indicating which
parts of the program should be profiled:
<DL COMPACT=compact><DT>
<B><TT>a</TT></B><DD> all options
<DT><B><TT>f</TT></B><DD> function calls : a count point is set at the beginning of
function bodies
<DT><B><TT>i</TT></B><DD> <B>if ...then ...else ...</B> : count points are set in
both <B>then</B> branch and <B>else</B> branch
<DT><B><TT>l</TT></B><DD> <B>while, for</B> loops: a count point is set at the beginning of
the loop body
<DT><B><TT>m</TT></B><DD> <B>match</B> branches: a count point is set at the beginning of the
body of each branch
<DT><B><TT>t</TT></B><DD> <B>try ...with ...</B> branches: a count point is set at the
beginning of the body of each branch
</DL>
For instance, compiling with <TT>ocamlcp -p film</TT> profiles function calls,
if...then...else..., loops and pattern matching.<BR>
<BR>
Calling <TT>ocamlcp</TT> without the <TT>-p</TT> option defaults to <TT>-p fm</TT>, meaning
that only function calls and pattern matching are profiled.<BR>
<BR>
<B>Note:</B> Due to the implementation of streams and stream patterns as
syntactic sugar, it is hard to predict what parts of stream expressions
and patterns will be profiled by a given flag. To profile a program with
streams, we recommend using <TT>ocamlcp -p a</TT>.<BR>
<BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#66ff66"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc193"><B><FONT SIZE=5>17.2</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=5>Profiling an execution</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><BR>
Running a bytecode executable file that has been compiled with <TT>ocamlcp</TT>
records the execution counts for the specified parts of the program
and saves them in a file called <TT>ocamlprof.dump</TT> in the current directory.<BR>
<BR>
The <TT>ocamlprof.dump</TT> file is written only if the program terminates
normally (by calling <TT>exit</TT> or by falling through). It is not written
if the program terminates with an <TT>uncaught exception</TT>.<BR>
<BR>
If a compatible dump file already exists in the current directory, then the
profiling information is accumulated in this dump file. This allows, for
instance, the profiling of several executions of a program on
different inputs.<BR>
<BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#66ff66"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc194"><B><FONT SIZE=5>17.3</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=5>Printing profiling information</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><BR>
The <TT>ocamlprof</TT> command produces a source listing of the program modules
where execution counts have been inserted as comments. For instance,
<PRE>
ocamlprof foo.ml
</PRE>prints the source code for the <TT>foo</TT> module, with comments indicating
how many times the functions in this module have been called. Naturally,
this information is accurate only if the source file has not been modified
since the profiling execution took place.<BR>
<BR>
The following options are recognized by <TT>ocamlprof</TT>:
<DL COMPACT=compact><DT>
<B><TT>-f</TT> <I>dumpfile</I></B><DD>
Specifies an alternate dump file of profiling information
<DT><B><TT>-F</TT> <I>string</I></B><DD>
Specifies an additional string to be output with profiling information.
By default, <TT>ocamlprof</TT> will annotate programs with comments of the form
<TT>(* <I>n</I></TT><TT> *)</TT> where <I>n</I> is the counter value for a profiling
point. With option <TT>-F <I>s</I></TT>, the annotation will be
<TT>(* <I>s</I></TT><TT><I>n</I></TT><TT> *)</TT>.
</DL>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#66ff66"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc195"><B><FONT SIZE=5>17.4</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=5>Time profiling</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><BR>
Profiling with <TT>ocamlprof</TT> only records execution counts, not the actual
time spent into each function. There is currently no way to perform
time profiling on bytecode programs generated by <TT>ocamlc</TT>.<BR>
<BR>
Native-code programs generated by <TT>ocamlopt</TT> can be profiled for time
and execution counts using the <TT>-p</TT> option and the standard Unix
profiler <TT>gprof</TT>. Just add the <TT>-p</TT> option when compiling and linking
the program:
<PRE>
ocamlopt -o myprog -p <I>other-options</I> <I>files</I>
./myprog
gprof myprog
</PRE>
Caml function names in the output of <TT>gprof</TT> have the following format:
<PRE>
<I>Module-name</I>_<I>function-name</I>_<I>unique-number</I>
</PRE>
Other functions shown are either parts of the Caml run-time system or
external C functions linked with the program.<BR>
<BR>
The output of <TT>gprof</TT> is described in the Unix manual page for
<TT>gprof(1)</TT>. It generally consists of two parts: a ``flat'' profile
showing the time spent in each function and the number of invocation
of each function, and a ``hierarchical'' profile based on the call
graph. Currently, only the Intel x86/Linux and Alpha/Digital Unix
ports of <TT>ocamlopt</TT> support the two profiles. On other platforms,
<TT>gprof</TT> will report only the ``flat'' profile with just time
information. When reading the output of <TT>gprof</TT>, keep in mind that
the accumulated times computed by <TT>gprof</TT> are based on heuristics and
may not be exact.
<BR>
<BR>
<HR>
<A HREF="manual030.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<A HREF="manual032.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
