Object for managing calls to the C-standard function gettimeofday(), calculating deltas and categorizing time spent according to a developer's wishes. Calls to gettimeofday() are precise to microseconds, and take considerably less time than that. With the option to lookup a section by numerical index, the timing can have no impact whatsoever on any serious computation, and even lookup by section name is relatively fast thanks to the findStringInVector() function. The relative time can be computed in a number of ways, so that the timer can be called less frequently but not accrue all of the time since it last sampled the computation. More...

#include <stopwatch.h>

Public Member Functions
	StopWatch (const std::string &title_in=std::string("Timer"))
	The basic constructor records the time at which initialization was called and creates a section called "Miscellaneous" to capture any times not assigned to a particular section.

	~StopWatch ()=default
	Default destructor.

double	getTimeAtStart () const
	Get the time at which this StopWatch was first started.

double	getTimeAtLastTest () const
	Get the time at which this StopWatch last recorded a test (this is not necessarily the last time this StopWatch fired off translateCurrentTime() which contains the actual call to the underlying gettimeofday(), as there are cases where one can simply query how long ago the StopWatch did anything).

double	getTimeSinceStart () const
	Get the time since this StopWatch was first started.

double	getTimeSinceLastTest () const
	Get the time since this StopWatch was last tested (see above for lengthier explanation).

std::string	getCategoryName (int query_index) const
	Get the name of a timing category based on its index in the program.

int	getCategoryIndex (const std::string &query, ExceptionResponse policy=ExceptionResponse::DIE) const
	Get the index of category based on its name. Returns -1 or an error if the named category is not present in the object.

double	getTotalDuration () const
	Report the total duration recorded by this stopwatch under all sections.

int	addCategory (const std::string &name)
	Add a section to the current StopWatch, if no such section already exists. Return the index of the section, whether newly added or not.

void	printResults (double precision=1.0e6)
	Print the timings for this StopWatch.


	StopWatch (const StopWatch &original)=default
	With no const members or points to repair, the default copy and move constructors, as well as copy and move assignment operators, will be applicable.

	StopWatch (StopWatch &&original)=default

StopWatch &	operator= (const StopWatch &original)=default

StopWatch &	operator= (StopWatch &&original)=default


double	getCategoryDuration (int query_index) const
	Get the duration recorded under any one category.

double	getCategoryDuration (const std::string &query_name) const


double	getCategoryAverageInterval (int query_index) const
	Get the average interval of time observed for any given category.

double	getCategoryAverageInterval (const std::string &query_name) const


double	getCategoryMinimumTime (int query_index) const
	Get the minimum stretch of time recorded under any one category.

double	getCategoryMinimumTime (const std::string &query_name) const


double	getCategoryMaximumTime (int query_index) const
	Get the maximum stretch of time recorded under any one category.

double	getCategoryMaximumTime (const std::string &query_name) const


int	getCategorySamples (int query_index) const
	Get the maximum stretch of time recorded under any one category.

int	getCategorySamples (const std::string &query_name) const


void	assignTime (int target, double reference_time)
	Assign an amount of time to this StopWatch.

void	assignTime (int target=0)

void	assignTime (const std::string &target)

void	assignTime (const std::string &target, double reference_time)


double2	timeDifferential (const std::string &catg_a, const std::string &catg_b, const std::string &referring_function=std::string("")) const
	Obtain the time taken as the difference of two categories, catg_a - catg_b. The result is returned as the mean differential, which is exact, and an estimate of the standard deviation of the differential (based on the standard deviations of each category individually).

double2	timeDifferential (int catg_a, int catg_b, const std::string &referring_function=std::string("")) const

Detailed Description

Object for managing calls to the C-standard function gettimeofday(), calculating deltas and categorizing time spent according to a developer's wishes. Calls to gettimeofday() are precise to microseconds, and take considerably less time than that. With the option to lookup a section by numerical index, the timing can have no impact whatsoever on any serious computation, and even lookup by section name is relatively fast thanks to the findStringInVector() function. The relative time can be computed in a number of ways, so that the timer can be called less frequently but not accrue all of the time since it last sampled the computation.

Constructor & Destructor Documentation

◆ StopWatch() [1/2]

stormm::testing::StopWatch::StopWatch ( const std::string & title_in = std::string("Timer") )

The basic constructor records the time at which initialization was called and creates a section called "Miscellaneous" to capture any times not assigned to a particular section.

Parameters

title_in Title to give this timing apparatus (default "Timer")

◆ StopWatch() [2/2]

stormm::testing::StopWatch::StopWatch ( const StopWatch & original )

default

With no const members or points to repair, the default copy and move constructors, as well as copy and move assignment operators, will be applicable.

Parameters

original	The original object to copy or move
other	Another object placed on the right hand side of the assignment statement

Member Function Documentation

◆ addCategory()

int stormm::testing::StopWatch::addCategory ( const std::string & name )

Add a section to the current StopWatch, if no such section already exists. Return the index of the section, whether newly added or not.

Parameters

name	Proposed name of the new section

◆ assignTime()

void stormm::testing::StopWatch::assignTime	(	int	target,
		double	reference_time )

Assign an amount of time to this StopWatch.

Overloaded:

Assign time to the "Miscellaneous" section (no arguments)
Assign time to a particular section, by index or by name, since the last time recorded by that section
Assign time to a particular section based on an arbitrary reference time (this could be an independent call to gettimeofday() stored earlier in some variable, or the last time recorded by some other section of this or even another StopWatch).

Parameters

target	The index or name of the section that will get time added
reference_time	Arbitrary reference time from some other source

◆ getCategoryAverageInterval()

double stormm::testing::StopWatch::getCategoryAverageInterval ( int query_index ) const

Get the average interval of time observed for any given category.

Overloaded:

Identify the category by name
Identify the category by the order in which it was assigned

Parameters

query_index	Index of the category (the first added category has index 1)
query_name	Name of the category

◆ getCategoryDuration()

double stormm::testing::StopWatch::getCategoryDuration ( int query_index ) const

Get the duration recorded under any one category.

Overloaded:

Identify the category by name
Identify the category by the order in which it was assigned

Parameters

query_index	Index of the category (the first added category has index 1)
query_name	Name of the category

◆ getCategoryIndex()

int stormm::testing::StopWatch::getCategoryIndex	(	const std::string &	query,
		ExceptionResponse	policy = ExceptionResponse::DIE ) const

Get the index of category based on its name. Returns -1 or an error if the named category is not present in the object.

Parameters

query	Name of the timings category to seek out
policy	Course of action if the named category is not found

◆ getCategoryMaximumTime()

double stormm::testing::StopWatch::getCategoryMaximumTime ( int query_index ) const

Get the maximum stretch of time recorded under any one category.

Overloaded:

Identify the category by name
Identify the category by the order in which it was assigned

Parameters

query_index	Index of the category (the first added category has index 1)
query_name	Name of the category

◆ getCategoryMinimumTime()

double stormm::testing::StopWatch::getCategoryMinimumTime ( int query_index ) const

Get the minimum stretch of time recorded under any one category.

Overloaded:

Identify the category by name
Identify the category by the order in which it was assigned

Parameters

query_index	Index of the category (the first added category has index 1)
query_name	Name of the category

◆ getCategoryName()

std::string stormm::testing::StopWatch::getCategoryName ( int query_index ) const

Get the name of a timing category based on its index in the program.

Parameters

query_index Index of the category (the first added category has index 1)

◆ getCategorySamples()

int stormm::testing::StopWatch::getCategorySamples ( int query_index ) const

Get the maximum stretch of time recorded under any one category.

Overloaded:

Identify the category by name
Identify the category by the order in which it was assigned

Parameters

query_index	Index of the category (the first added category has index 1)
query_name	Name of the category

◆ printResults()

void stormm::testing::StopWatch::printResults ( double precision = 1.0e6 )

Print the timings for this StopWatch.

Parameters

precision Results will be reported such that the largest printed interval can be known to within one part in at least this amount. However, the maximum number of decimals that will be printed is 4, one 10,000th of a second.

◆ timeDifferential()

double2 stormm::testing::StopWatch::timeDifferential	(	const std::string &	catg_a,
		const std::string &	catg_b,
		const std::string &	referring_function = std::string("") ) const

Obtain the time taken as the difference of two categories, catg_a - catg_b. The result is returned as the mean differential, which is exact, and an estimate of the standard deviation of the differential (based on the standard deviations of each category individually).

Overloaded:

Provide the categories by their string identifiers
Provide the categories by their integer identifiers

Parameters

catg_a	The first category, likely the longer of two categories or a category which comprises some or all of the activity in the second category
catg_b	The second category, likely to be composed of a subset of the activities in the first category
referring_function	The function calling for a differential (for error tracing)

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

src/UnitTesting/stopwatch.h
src/UnitTesting/stopwatch.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ StopWatch() [1/2]

◆ StopWatch() [2/2]

Member Function Documentation

◆ addCategory()

◆ assignTime()

◆ getCategoryAverageInterval()

◆ getCategoryDuration()

◆ getCategoryIndex()

◆ getCategoryMaximumTime()

◆ getCategoryMinimumTime()

◆ getCategoryName()

◆ getCategorySamples()

◆ printResults()

◆ timeDifferential()