Profiling (cslprof)

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

Compiling for profiling

Before profiling an execution, the program must be compiled in profiling mode, using the cslcp front-end to the cslc compiler (see chapter ). When compiling modules separately, cslcp must be used when compiling the modules (production of .cmo files), and can also be used (though this is not strictly necessary) when linking them together.

The amount of profiling information can be controlled through the -p option to cslcp, followed by one or several letters 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 cslcp -pfilm profiles function calls, if... then... else..., loops and pattern matching.

Calling cslcp without the -p option defaults to -p fm, meaning that only function calls and pattern matching are profiled.

Profiling an execution

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

The cslprof.dump file is written only if the program terminates normally (by calling exit or by falling through). It is not written if the program terminates with an uncaught exception.

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 cslprof command produces a source listing of the program modules where execution counts have been inserted as comments. For instance,

        cslprof foo.ml

prints the source code for the foo 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.

The following options are recognized by cslprof:

-f dumpfile: Specifies an alternate dump file of profiling information
-F string: Specifies an additional string to be output with profiling information. By default, cslprof will annotate programs with comments of the form (* n *) where n is the counter value for a profiling point. With option -F s, the annotation will be (* s n *).

Time profiling

Profiling with cslprof 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 cslc. On native-code programs generated by cslopt, the standard Unix profiler prof can be used; just add the -ccopt -p option when linking the program:

        cslopt -o myprog -ccopt -p other-options files
        ./myprog
        prof myprog

Function names in the output of prof have the following format:

        Module-name_function-name_unique-number