The HighPerformanceBenchmark object allows to benchmark algorithms with individual categories. More...

Inheritance diagram for Ocean::HighPerformanceBenchmark:

Data Structures
class	Category
	This class defines a hierarchical category This class is used to group categories based on their names into a hierarchy. More...

class	ScopedCategory
	This class implements a scoped benchmark category. More...

Public Types
typedef std::vector< double >	MeasurementsSeconds
	Definition of a vector holding measurements in seconds. More...

typedef std::unordered_map< std::string, MeasurementsSeconds >	MeasurementMap
	Definition of a map mapping category names to measurements. More...

typedef std::vector< Category >	Categories
	Typedef for a vector of categories. More...

Public Member Functions
bool	start ()
	Starts benchmarking. More...

bool	stop ()
	Stops benchmarking. More...

void	reset ()
	Rests all benchmark categories and measurements. More...

bool	isRunning () const
	Returns whether benchmarking is currently active; False by default. More...

MeasurementMap	measurementMap () const
	Returns the map with category names and measurement objects. More...

std::vector< std::string >	report (const std::string &referenceCategory=std::string()) const
	Creates a performance report as a readable string. More...

bool	reportWithHierarchies (std::vector< std::string > &report, const std::string &referenceCategory=std::string(), const std::string &categoryNameDelimiter="::") const
	Creates a performance report for a hierarchy of categories as a human-readable string. More...

size_t	measurements (const std::string &category)
	Returns the number of measurements of a specific category. More...

Static Public Member Functions
static Categories	createCategoryHierarchy (const MeasurementMap &measurementMap, const std::string &categoryNameDelimiter)
	Creates a hierarchy of categories based on their names from a map of measurements. More...

static bool	createTokenMatrixFromCategoryHierarchy (const Categories &categories, const std::string referenceCategory, const std::string &categoryNameDelimiter, const bool valuesAsStrings, std::vector< std::vector< Value >> &tokenMatrix)
	Given a hierarchy of categories with measurements, create a matrix with the performance information The output of this function is a matrix where each cell contains the information that the final report will contain. More...

Static Public Member Functions inherited from Ocean::Singleton< HighPerformanceBenchmark >
static HighPerformanceBenchmark &	get ()
	Returns a reference to the unique object. More...

Protected Member Functions
void	addMeasurement (const std::string &name, const double measurement)
	Adds a benchmark measurement for a specified category. More...

	HighPerformanceBenchmark ()
	Default constructor. More...

	~HighPerformanceBenchmark ()
	Destructs an object. More...

Protected Member Functions inherited from Ocean::Singleton< HighPerformanceBenchmark >
	Singleton ()=default
	Default constructor. More...

Protected Attributes
MeasurementMap	measurementMap_
	The map mapping category names to their measurement objects. More...

bool	isRunning_
	True, if benchmarking is running, false by default. More...

Lock	lock_
	The lock object. More...

Friends
class	Singleton< HighPerformanceBenchmark >

Detailed Description

The HighPerformanceBenchmark object allows to benchmark algorithms with individual categories.

Benchmarking needs to be started before it can be used.
The class is thread-safe. This class creates flat and/or hierarchical reports. In the case of the former, the categories are sorted by their CPU time. For hierarchical reports, the category names can be expanded using a delimiter, for example Foo::Bar where Bar is a sub-category of Foo. In this report the top-level categories (like Foo) will be sorted by their total CPU time which is accumulated over all of their sub-categories (like Foo::Bar).

Usage Example:

void SomeClass::computeSomething(...)
{
    HighPerformanceBenchmark::ScopedCategory scopedBenchmark("AlgorithmName");
    function0();
    function1();
    ...
}

void SomeClass::function0(...)
{
    HighPerformanceBenchmark::ScopedCategory scopedBenchmark("AlgorithmName::Function0");
    ...
}

void SomeClass::function1(...)
{
    HighPerformanceBenchmark::ScopedCategory scopedBenchmark("AlgorithmName::Function1");
    utilityFunction0();
    ...
}

void Utility::utilityFunction0(...)
{
    HighPerformanceBenchmark::ScopedCategory scopedBenchmark("UtilityFunction0");
    ...
}

int main()
{
    HighPerformanceBenchmark::get().start();

    while (keepLooping)
    {
        SomeClass::computeSomething();
    }

    HighPerformanceBenchmark::get().stop();

    // Get the normal or hierarchical performance report
    const std::vector<std::string> report = HighPerformanceBenchmark::get().report();
    const std::vector<std::string> reportWithHierarchies = HighPerformanceBenchmark::get().reportWithHierarchies();
}

which will result in something similar to the following for the normal report:

Name                     | ...
AlgorithmName            | ...
UtilityFunction0         | ...
AlgorithmName::Function0 | ...
AlgorithmName::Function1 | ...

and for the hierarchical report the output will be similar to this (sub-categories will be appear indented):

Name             | ...
AlgorithmName    | ...
  Function0      | ...
  Function1      | ...
UtilityFunction0 | ...

Of course, the actual order of the categories depends on their proportional contribution to the overall measured CPU time

Member Typedef Documentation

◆ Categories

typedef std::vector<Category> Ocean::HighPerformanceBenchmark::Categories

Typedef for a vector of categories.

◆ MeasurementMap

typedef std::unordered_map<std::string, MeasurementsSeconds> Ocean::HighPerformanceBenchmark::MeasurementMap

Definition of a map mapping category names to measurements.

◆ MeasurementsSeconds

typedef std::vector<double> Ocean::HighPerformanceBenchmark::MeasurementsSeconds

Definition of a vector holding measurements in seconds.

Constructor & Destructor Documentation

◆ HighPerformanceBenchmark()

Ocean::HighPerformanceBenchmark::HighPerformanceBenchmark ( )

inlineprotected

Default constructor.

◆ ~HighPerformanceBenchmark()

Ocean::HighPerformanceBenchmark::~HighPerformanceBenchmark ( )

inlineprotected

Destructs an object.

Member Function Documentation

◆ addMeasurement()

void Ocean::HighPerformanceBenchmark::addMeasurement	(	const std::string &	name,
		const double	measurement
	)

protected

Adds a benchmark measurement for a specified category.

Parameters

name	The name of the category
measurement	The benchmark measurement in seconds, with range [0, infinity)

◆ createCategoryHierarchy()

static Categories Ocean::HighPerformanceBenchmark::createCategoryHierarchy	(	const MeasurementMap &	measurementMap,
		const std::string &	categoryNameDelimiter
	)

static

Creates a hierarchy of categories based on their names from a map of measurements.

Parameters

measurementMap	The map of measurements (category -> measurements) for which a hierarchy of categories will be created
categoryNameDelimiter	The delimiter that is used to separate levels of categories in a hierarchy

Returns: The hierarchy

◆ createTokenMatrixFromCategoryHierarchy()

static bool Ocean::HighPerformanceBenchmark::createTokenMatrixFromCategoryHierarchy	(	const Categories &	categories,
		const std::string	referenceCategory,
		const std::string &	categoryNameDelimiter,
		const bool	valuesAsStrings,
		std::vector< std::vector< Value >> &	tokenMatrix
	)

static

Given a hierarchy of categories with measurements, create a matrix with the performance information The output of this function is a matrix where each cell contains the information that the final report will contain.

This intermediate container makes it easy to print the report with aligned columns.

Parameters

categories	The hierarchy of categories for which a token matrix will created, must be valid and not empty.
referenceCategory	The optional reference category for to add relative performance values to the report
categoryNameDelimiter	The optional delimiter that is used to separate levels of categories in a hierarchy
valuesAsStrings	True, all cells will be of type string; False, column descriptions and category names will be reported as string and all other values as double or integer.
tokenMatrix	The resulting token matrix for all categories.

Returns: True, if the generation of the token matrix was successful, otherwise false.

◆ isRunning()

bool Ocean::HighPerformanceBenchmark::isRunning ( ) const

Returns whether benchmarking is currently active; False by default.

Returns: True, if so

◆ measurementMap()

MeasurementMap Ocean::HighPerformanceBenchmark::measurementMap ( ) const

Returns the map with category names and measurement objects.

Returns: The measurement map

◆ measurements()

size_t Ocean::HighPerformanceBenchmark::measurements ( const std::string & category )

Returns the number of measurements of a specific category.

Parameters

category The category for which the number of measurements will be returned

Returns: The number of measurements, with range [0, infinity)

◆ report()

std::vector<std::string> Ocean::HighPerformanceBenchmark::report ( const std::string & referenceCategory = std::string() ) const

Creates a performance report as a readable string.

Parameters

referenceCategory Optional reference category for to add relative performance values to the report

Returns: The report as readable string, one string for each line in the report

◆ reportWithHierarchies()

bool Ocean::HighPerformanceBenchmark::reportWithHierarchies	(	std::vector< std::string > &	report,
		const std::string &	referenceCategory = `std::string()`,
		const std::string &	categoryNameDelimiter = `"::"`
	)		const

Creates a performance report for a hierarchy of categories as a human-readable string.

A hierarchy of categories is created by appending the name of a sub-category to the name of category, using a delimiter between both names, for example "Foo::Bar" is a sub-category of "Foo". This process can be repeated recursively ("Foo::Bar::Baz"). Categories without a delimiter in their name - or which cannot be matched otherwise - will be considered top-level categories ("Foo").

The final report will list either 1) all top-level categories with their subsumed sub-categories (which will be indented) or 2) a specific top-level category. All categories and sub-categories will be sorted by their total CPU-time in descending order.

Parameters

report	The resulting report as a readable string, one string for each line in the report
referenceCategory	The optional reference category for to add relative performance values to the report
categoryNameDelimiter	The optional delimiter that is used to separate levels of categories in a hierarchy

Returns: True, if the generation of the report was successful, otherwise false

◆ reset()

void Ocean::HighPerformanceBenchmark::reset ( )

Rests all benchmark categories and measurements.

◆ start()

bool Ocean::HighPerformanceBenchmark::start ( )

Starts benchmarking.

Returns: True, if succeeded

See also: stop(), isRunning().

◆ stop()

bool Ocean::HighPerformanceBenchmark::stop ( )

Stops benchmarking.

Returns: True, if succeeded

See also: start(), isRunning().

Friends And Related Function Documentation

◆ Singleton< HighPerformanceBenchmark >

friend class Singleton< HighPerformanceBenchmark >

friend

Field Documentation

◆ isRunning_

bool Ocean::HighPerformanceBenchmark::isRunning_

protected

True, if benchmarking is running, false by default.

◆ lock_

Lock Ocean::HighPerformanceBenchmark::lock_

mutableprotected

The lock object.

◆ measurementMap_

MeasurementMap Ocean::HighPerformanceBenchmark::measurementMap_

protected

The map mapping category names to their measurement objects.

The documentation for this class was generated from the following file:

HighPerformanceTimer.h

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ Categories

◆ MeasurementMap

◆ MeasurementsSeconds

Constructor & Destructor Documentation

◆ HighPerformanceBenchmark()

◆ ~HighPerformanceBenchmark()

Member Function Documentation

◆ addMeasurement()

◆ createCategoryHierarchy()

◆ createTokenMatrixFromCategoryHierarchy()

◆ isRunning()

◆ measurementMap()

◆ measurements()

◆ report()

◆ reportWithHierarchies()

◆ reset()

◆ start()

◆ stop()

Friends And Related Function Documentation

◆ Singleton< HighPerformanceBenchmark >

Field Documentation

◆ isRunning_

◆ lock_

◆ measurementMap_