Using Celero

Celero employes macros to build benchmarks.

Each user defined benchmark is defined with two parameters. The first parameter is the benchmark group. This is used to related individual benchmarks together and to associate a test with a baseline. The second parameter is the unique name within the given group for the test. This is used to identify the test at run time.

Each user defined baseline has only a single parameter: the Group name. Celero will execute the baseline code to create a custom time unit for all tests within the group. In this way, individual tests can be measured with respect to a baseline vs. time. This is especially usefull in judging the "goodness" of an algorithim against an established base case and also helps to translate results across machines and architectures.

Within a .cpp file, include the Celero header.

#include <celero/Celero.h>

Optionally, you can then include the automatic main(). Do not do this if your program already has a main(), but it can be usefull when building test suites.

CELERO_MAIN;

Next, it is good practice to create the baseline test for your benchmark group. The BASELINE macro takes three parameters. The first is the group name. The second is the number of times you want to run the test. The third is the number of times to loop over the test during one measurement period.

// Run an automatic baseline.  
// Celero will help make sure enough samples are taken to get a reasonable measurement
BASELINE(CeleroBenchTest, 0, 7100000)
{
    celero::DoNotOptimizeAway(static_cast<float>(sin(3.14159265)));
}

In this example, a baseline test called "CeleroBenchTest" is created. The second parameter being set to zero indicates that Celero should do at least 30 runs of the test or run the test for at least one second worth of tests, whichever is satisfied first. This is called "Auto" mode. The third parameter says to measure the time it takes to run the code specified 7100000 times. Using a larger number here is helpful for very fast operations that are difficult to measure.

When completed, this test output looks like the following:

[ RUN      ] CeleroBenchTest.Baseline -- Auto Run, 7100000 ops per run.
[   AUTO   ] CeleroBenchTest.Baseline -- 30 runs, 7100000 ops per run.
[     DONE ] CeleroBenchTest.Baseline  (0.202416 sec) [7100000 ops in 202416 usec] [0.028509 us/op] [35076278.555055 op/sec]

The summary here shows that the total test took 0.202416 seconds to execute. During this time, the time it took the test code to execute 7100000 times was measured and 30 such samples were taken. It was found that 7100000 operations could occur in 202416 microseconds. This equates to 0.028509 us/op or 35076278.555055 op/sec.