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, ...
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:
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.
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.
The camlpro command produces a source listing of the program modules where execution counts have been inserted as comments. For instance,
camlpro foo.mlprints 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 camlpro:
An additional argument specifies the output file. For instance
camlpro -f ../test/camlpro.dump foo.ml foo_profiled.mlwill save the annotated program in file foo_profiled.ml. Otherwise, the annotated program is written on the standard output.
let a = 1;; x__a ;;will break the profiler. More precisely, one should avoid to refer to symbols of the current module with the qualified symbol syntax.