RWBench Class Reference

Abstract base class to facilitate automatic benchmarking of some piece of code. More...

#include <rw/bench.h>

Public Member Functions
	RWBench (double duration=5, unsigned long ILO=1000, const char *machine=0)
virtual void	doLoop (unsigned long n)=0
double	duration () const
virtual void	go ()
virtual void	idleLoop (unsigned long n)
unsigned long	innerLoops () const
const char *	machine () const
double	ops () const
double	opsRate () const
unsigned long	outerLoops () const
void	parse (const char *args)
virtual void	parse (int argc, char *argv[])
virtual void	parse (int argc, const char *argv[])
virtual void	report (std::ostream &) const
double	setDuration (double t)
unsigned long	setInnerLoops (unsigned long N)
double	time () const
virtual void	what (std::ostream &) const
void	where (std::ostream &) const

Detailed Description

This is an abstract class that can automate the process of benchmarking a piece of code. To use it, derive a class from RWBench, including a definition for the virtual function doLoop(unsigned long N). This function should perform N operations of the type that you are trying to benchmark. RWBench will call doLoop() over and over again until a preset amount of time has elapsed. It will then sum the total number of operations performed.

To run, construct an instance of your derived class and then call go(). Then call report() to get a standard summary. For many compilers, this summary will automatically include the compiler type and memory model. You can call ops(), outerLoops(), etc. for more detail.

If you wish to correct for overhead, then provide an idleLoop() function which should do all non-benchmark-related calculations.

Synopsis

#include <rw/bench.h>
(Abstract base class)

Persistence

None

Example

This example compares container append operations by benchmarking RWTValOrderedVector<T,A>::append() versus RWTValDlist<T,A>::append().

#include <cstdlib>
#include <iostream>

#include <rw/bench.h>    //Benchmark software
#include <rw/tvdlist.h>  //RWTValDlist
#include <rw/tvordvec.h> //RWTValOrderedVector

template <typename C>
class TimeAppend : public RWBench
{
public:
    TimeAppend(const RWCString& name) : name_(name) { }

    virtual void doLoop(unsigned long);

    virtual void idleLoop(unsigned long);

    virtual void what(std::ostream& s) const {
        s << name_ << "::append() test: \n";
    }

private:
    RWCString name_;
};

template <typename C>
void TimeAppend<C>::doLoop(unsigned long n)
{
    C container;
    for (unsigned long i = 0; i < n; ++i) {
        container.append(i);
    }
}

template <typename C>
void TimeAppend<C>::idleLoop(unsigned long n)
{
    C container;
    for (unsigned long i = 0; i < n; ++i) {
    }
}

int main(int argc, char** argv)
{
    std::cout << "Testing container append...\n";

    TimeAppend<RWTValOrderedVector<unsigned long> > vec("RWTValOrderedVector<unsigned long>");
    vec.parse(argc, argv);
    vec.go();
    vec.report(std::cout);

    TimeAppend<RWTValDlist<unsigned long> > list("RWTValDlist<unsigned long>");
    list.parse(argc, argv);
    list.go();
    list.report(std::cout);

    return 0;
}

Program Output:

Testing container append...
Microsoft C/C++

RWTValOrderedVector<unsigned long>::append() test:

Iterations:                 4071
Inner loop operations:      1000
Total operations:           4.071e+006
Elapsed (user) time:        5.00763
Kilo-operations per second: 812.959

Microsoft C/C++

RWTValDlist<unsigned long>::append() test:

Iterations:                 4066
Inner loop operations:      1000
Total operations:           4.066e+006
Elapsed (user) time:        5.00763
Kilo-operations per second: 811.961

Constructor & Destructor Documentation

RWBench::RWBench	(	double	duration = 5,
		unsigned long	ILO = 1000,
		const char *	machine = 0
	)

The parameter duration is the nominal amount of time that the benchmark should take in seconds. The virtual function doLoop(unsigned long) is called over and over again until at least this amount of time has elapsed. The parameter ILO is the number of inner loop operations that should be performed. This parameter is passed in as parameter N to doLoop(N). Parameter machine is an optional null terminated string that should describe the test environment (perhaps the hardware the benchmark is being run on).

Member Function Documentation

virtual void RWBench::doLoop ( unsigned long  n )

pure virtual

A pure virtual function whose actual definition should be supplied by the specializing class. This function is repeatedly called until a time duration has elapsed. It should perform the operation to be benchmarked N times. See the example.

double RWBench::duration ( ) const

inline

Return the current setting for the benchmark test duration. This should not be confused with the function time(), which returns the actual test time.

virtual void RWBench::go ( )

virtual

Call this function to run the benchmark.

virtual void RWBench::idleLoop ( unsigned long  n )

virtual

This function can help to correct the benchmark for overhead. The default definition merely executes a "for()" loop n times. See the example.

unsigned long RWBench::innerLoops ( ) const

inline

Returns the current setting for the number of inner loop operations that will be passed into function doLoop(unsigned long N) as parameter N.

const char* RWBench::machine ( ) const

inline

This function accesses the name of the machine which is passed into the benchmark object through parse().

double RWBench::ops

(

)

const

Returns the total number of inner loop operations that were performed (the product of the number of times outerLoops() was called times the number of inner loop operations performed per call).

double RWBench::opsRate

(

)

const

Returns the number of inner loop operations per second.

unsigned long RWBench::outerLoops

(

)

const

Returns the number of times the function doLoop() was called.

void RWBench::parse

(

const char *

args

)

This is a non-virtual function that provides the same service as parse(int argc, char * argv[]), but is designed for Windows users. It extracts tokens from the null-terminated command argument provided by Windows, then calls the virtual parse() for ANSI C command arguments.

virtual void RWBench::parse ( int  argc, char *  argv[]  )

virtual

This function allows an easy way to change the test duration, number of inner loops and machine description from the command line.

Argument	Type	Description
argv[1]	double	Duration (sec.)
argv[2]	unsigned long	No. of inner loops
argv[3]	const char*	Machine

virtual void RWBench::parse ( int  argc, const char *  argv[]  )

virtual

This function allows an easy way to change the test duration, number of inner loops and machine description from the command line.

Argument	Type	Description
argv[1]	double	Duration (sec.)
argv[2]	unsigned long	No. of inner loops
argv[3]	const char*	Machine

virtual void RWBench::report ( std::ostream &  ) const

virtual

Calling this function provides an easy and convenient way of getting an overall summary of the results of a benchmark.

double RWBench::setDuration

(

double

t

)

Change the test duration to time t.

unsigned long RWBench::setInnerLoops

(

unsigned long

N

)

Change the number of inner loop operations to N.

double RWBench::time

(

)

const

Returns the amount of time the benchmark took, corrected for overhead.

virtual void RWBench::what ( std::ostream &  ) const

virtual

You can supply a specializing version of this virtual function that provides some detail of what is being benchmarked. It is called by report() when generating a standard report.

void RWBench::where

(

std::ostream &

)

const

This function prints information to the stream about the compiler and memory model that the code was compiled under.