DISCLAIMER : Not a Boost library
by Christopher Diggins
licensed under the Boost Software License version 1.0
The most recent code can be found at:
The Boost Profiler library is a simple policy-based RAII profiler class for measuring execution times of blocks of code. The profiler library depends on the implementation of the timer class, which defaults to Boost.Timer and as a result cannot be depended upon to be accurate or robust, and should not be used if that is of any concern.
Testing code frequently requires us to find performance bottlenecks. This library was designed to help facilitate profiling of source code, in order to evaluate places for optimization, and to compare implementation techniques. This is designed to be "good enough" to be useful for a significant number of tasks.
The most common usage of the profiler is to simply declare a variable at the beginning of a scope, for instance:
{
boost::prof::profiler p;
// ... some code
// upon destruction of p, elapsed time is logged to cerr
}
Upon destruction of a profiler variable, some action is taken as defined by the policy. The default action is to output the time it took to the standard output stream, along with whether an underflow or overflow occured with regards to the resolution of the current timer.
A profiler also supports the following methods:
The profiler class is a specialization of basic_profiler as follows:
typedef basic_profiler
<
default_logging_policy,
default_stats_policy,
high_resolution_timer
>
profiler;
The logging policy is repsonsible for logging profiling events. It is given a chance to respond to every single change in a profiler's status. The logging policy models the following concept:
struct empty_logging_policy
{
static void on_start(char const* name) { };
static void on_resume(char const* name) { };
static void on_pause(char const* name, double sec) { };
static void on_stop(char const* name, double sec, bool underflow, bool overflow) { };
};
The stats policy is responsible for collecting and reporting statistics for the various profiles. The stats policy models the following concept:
struct empty_stats_policy
{
static void on_stop(char const* name, double sec, bool underflow, bool overflow) { }
static void on_report() { }
};
The timer parameter is any class which matches the concept of boost::timer by Beman Dawes. This class concept should be modeled when the user have platform-specific timers available with preferable performance characteristics.
struct timer_concept {
timer(); // postcondition: elapsed()==0
double elapsed() const; // return elapsed time in seconds
double elapsed_min() const; // return minimum value for elapsed()
double elapsed_max() const; // return estimated maximum value for elapsed()
};
The profiler class can be used to manage multiple named profiles. This can be useful for computing and reporting statistics on reentrant code, such as the number of entries into a code block, as weall as the sum and average time spent in various blocks.
typedef boost::prof::basic_profiler
<
boost::prof::empty_logging_policy, // don't log events
boost::prof::default_stats_policy,
boost::prof::high_resolution_timer
>
my_profiler;
void MyFxn()
{
my_profiler p("MyFxn");
// ... some code
}
void Test()
{
for (int i=0; i<10; i++) {
MyFxn();
}
my_profiler::generate_report();
}
Underflow and overflow occur when a timed period is less than than minimum time measurable by the timer, or greater than the maximum time measurable by the timer. Underflow can occur even between restart and pause.
Hartmut Kaiser has generously provided the high_resolution_timer class which models the timer concept. The high_resolution_timer is a high-resolution timer only on Windows platforms, otherwise it defaults to boost::timer.
Turning profiling off can be done by defining the macro BOOST_PROFILING_OFF. This causes all profiling code, to evaluate to empty statements.
The macro, BOOST_PROFILE(xxx), which can be used to profile a single expression, or function call. It is defined as:
#ifndef BOOST_PROFILING_OFF
#define BOOST_PROFILE(TKN) { boost::prof::profiler p_(#TKN); TKN; }
#else
#define BOOST_PROFILE(TKN) TKN;
#endif
high_resolution_timer
written by Hartmut Kaiser, which has a very fine-grained resolution on Windows platforms,
otherwise it defaults to boost::timer by Beman Dawes, which has a variable grain depending
on your platform's implementation of std::clock.
typedef profiled< MyClass, MyInterface, profiler > MyProfiledClass;
This would cause every member function of MyClass that is a member of the BIL interface MyInterface
would be profiled using the profiler type.