Profiling (camlpro)

This chapter describes how the execution of Caml Light programs can be profiled, by recording how many times functions are called, branches of conditionals are taken, ...

Mac:

This command is not available.

PC:

This command is not available.

Compiling for profiling

Before profiling an execution, the program must be compiled in profiling mode, using the -p option to the batch compiler camlc (see chapter 5). When compiling modules separately, the -p option must be given both when compiling the modules (production of .zo files) and when linking them together.

The amount of profiling information can be controlled by adding one or several letters after the -p option, indicating which parts of the program should be profiled:

a

all options

f

function calls : a count point is set at the beginning of function bodies

i

if ... then ... else ... : count points are set in both then branch and else branch

l

while, for loops: a count point is set at the beginning of the loop body

m

match branches: a count point is set at the beginning of the body of each branch

t

try ... with ... branches: a count point is set at the beginning of the body of each branch

For instance, compiling with -pfilm profiles function calls, if... then ... else..., loops and pattern matching.

The -p option without additional letters defaults to -pfm, meaning that only function calls and pattern matching are profiled.

Profiling an execution

Running a bytecode executable file that has been compiled and linked with -p records the execution counts for the specified parts of the program and saves them in a file called camlpro.dump in the current directory.

More precisely, the dump file camlpro.dump is written when the io__exit function is called. The linker, called with the -p option, adds io__exit 0 as the last phrase of the bytecode executable, in case the original program never calls io__exit. However, if the program terminates with an uncaught exception, the dump file will not be produced.

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.

Printing profiling information

The camlpro command produces a source listing of the program modules where execution counts have been inserted as comments. For instance,

        camlpro foo.ml

The following options are recognized by camlpro:

compiler options -stdlib, -I, -include, -O, -open, -i, -lang

See chapter 5 for the detailed usage.

-f dumpfile

Specifies an alternate dump file of profiling information

-F string

Specifies an additional string to be output with profiling information. By default, { camlpro} will annotate progams with comments of the form (* n *) where n is the counter value for a profiling point. With option -F s, the annotation will be (* sn *).

An additional argument specifies the output file. For instance

	camlpro -f ../test/camlpro.dump foo.ml foo_profiled.ml

Known bugs

let a = 1;;
x__a ;;