How to Use QuickProf

This page includes basic quick-start instructions, miscellaneous tips, and some examples. Everything here refers to the latest release version.

Basic Usage

In general, to use QuickProf you need to 1) include the header file, 2) initialize the profiler, 3) surround your blocks of code with begin/end calls, and 4) get timing results in some form. Below are the three most common ways to do this.

Tips

> To disable the profiler, simply comment out the call to init.

> Profiling blocks can overlap or be nested within other blocks.

> There are several options available for representing timing results: seconds, milliseconds, microseconds, and percent.

> Try not to run other applications while profiling your code. QuickProf simply measures the wall clock time elapsed in each block of code, so any background processes might skew the timing results.

> If the profiler is re-initialized, all profiler blocks and timing data are erased.

> Usually only one global profiler is used (via the PROFILER macro); however, if needed, multiple instances of the quickprof::Profiler class can be created.

Example 1: Simple Timing Summary

This example shows how to use QuickProf to get a simple overall timing summary at the end of execution.

#include <quickprof/quickprof.h>

// Initialize the profiler without any arguments.

PROFILER.init();

PROFILER.beginBlock("setup");

mySetupFunction();

PROFILER.beginBlock("setup");

while(!quit)

{

...

PROFILER.beginBlock("foo1");

foo1();

PROFILER.endBlock("foo1");

...

PROFILER.beginBlock("foo2");

foo2();

PROFILER.endBlock("foo2");

...

}

// This returns timing results for each block. It can format the

// data as percent or as the actual elapsed time.

std::cout << PROFILER.getSummary(quickprof::PERCENT) << std::endl;

Example 2: Data File Output

This example shows how to use QuickProf to save detailed timing data to an output file. This assumes that your code runs in a cyclic manner.

#include <quickprof/quickprof.h>

// Initialize the profiler with the smoothness value (used for moving

// averages), the output filename, the print period (print to the file

// on every nth cycle), and the time format.

PROFILER.init(10, "timing_results.dat", 8, quickprof::MILLISECONDS);

while(!quit)

{

...

PROFILER.beginBlock("foo1");

foo1();

PROFILER.endBlock("foo1");

...

PROFILER.beginBlock("foo2");

foo2();

PROFILER.endBlock("foo2");

...

// Defines the end of a cycle in the code. This is necessary

// for things like file output and for smooth averaging.

PROFILER.endCycle();

}

// This is always useful for a rough estimate at the end.

std::cout << PROFILER.getSummary() << std::endl;

Example 3: Real Time Display

This example shows how to use QuickProf to display timing data in real time as the application is running. This is great for things like interactive 3D applications. Again, this assumes that your code runs in a cyclic manner.

#include <quickprof/quickprof.h>

// Initialize the profiler with the smoothness value only. (The other

// parameters are only needed for file output.)

PROFILER.init(10);

while(!quit)

{

...

PROFILER.beginBlock("collision");

collisionDetection();

PROFILER.endBlock("collision");

PROFILER.beginBlock("physics");

physicsSimulation();

PROFILER.endBlock("physics");

PROFILER.beginBlock("graphics");

redrawGraphics();

PROFILER.endBlock("graphics");

// Defines the end of a cycle in the code. This is necessary

// for things like file output and for smooth averaging.

PROFILER.endCycle();

// Send the current timing data to some function that displays

// it in real time as the application is running.

double time = PROFILER.getAvgDuration("collision",

quickprof::PERCENT);

displayTimingData("collision", time);

time = PROFILER.getAvgDuration ("physics", quickprof::PERCENT);

displayTimingData("physics", time);

time = PROFILER.getAvgDuration ("graphics", quickprof::PERCENT);

displayTimingData("graphics", time);

}

// This is always useful for a rough estimate at the end.

std::cout << PROFILER.getSummary() << std::endl;