callgrind

Callgrind is a tracing profiler to record the function call history of a target program. It is part of the valgrind tool suite.

Profiling data is collected by instrumentation rather than sampling of the target program.

Callgrind does not capture the actual time spent in a function but computes the cost of a function based on the instructions fetched (Ir = Instruction read). Therefore effects like slow IO are not reflected, which should be kept in mind when analyzing callgrind results.

By default the profiler data is dumped when the target process is terminating, but callgrind_control allows for interactive control of callgrind.

# Run a program under callgrind.
valgrind --tool=callgrind -- <prog>

# Interactive control of callgrind.
callgrind_control [opts]
  opts:
    -b ............. show current backtrace
    -e ............. show current event counters
    -s ............. show current stats
    --dump[=file] .. dump current collection
    -i=on|off ...... turn instrumentation on|off

Results can be analyzed by using one of the following tools

The following is a collection of frequently used callgrind options.

valgrind --tool=callgrind [opts] -- <prog>
  opts:
    --callgrind-out-file=<file> .... output file, rather than callgrind.out.<pid>
    --dump-instr=<yes|no> .......... annotation on instrucion level,
                                     allows for asm annotations

    --instr-atstart=<yes|no> ....... control if instrumentation is enabled from 
                                     beginning of the program

    --separate-threads=<yes|no> .... create separate output files per thread,
                                     appends -<thread_id> to the output file

Profile specific part of the target

Programmatically enable/disable instrumentation using the macros defined in the callgrind header.

#include <valgrind/callgrind.h>

int main() {
    // init ..

    CALLGRIND_START_INSTRUMENTATION;
    compute();
    CALLGRIND_STOP_INSTRUMENTATION;

    // shutdown ..
}

In this case, callgrind should be launched with --instr-atstart=no.

Alternatively instrumentation can be controlled with callgrind_control -i on/off.

The files cg_example.cc and Makefile provide a full example.