This class allows one to push and pop timers on and off a stack. More...

#include <Teuchos_StackedTimer.hpp>

Classes
struct	AlignmentWidths
	Stores the column widths for output alignment. More...

class	LevelTimer
	Timer info at a given level and all the children. More...

struct	OutputOptions

Public Member Functions
	StackedTimer (const char *name, const bool start_base_timer=true)

void	startBaseTimer ()

void	stopBaseTimer ()

void	start (const std::string name, const bool push_kokkos_profiling_region=true)

void	stop (const std::string &name, const bool pop_kokkos_profiling_region=true)

void	incrementUpdates (const long long i=1)

double	accumulatedTime (const std::string &name="")

double	accumulatedTimePerUpdate (const std::string &name="")

double	accumulatedTimePerTimerCall (const std::string &name="")

const BaseTimer *	findBaseTimer (const std::string &name) const

BaseTimer::TimeInfo	findTimer (const std::string &name)

void	report (std::ostream &os, Teuchos::RCP< const Teuchos::Comm< int > > comm, OutputOptions options=OutputOptions())

void	reportXML (std::ostream &os, const std::string &datestamp, const std::string &timestamp, Teuchos::RCP< const Teuchos::Comm< int > > comm)

std::string	reportWatchrXML (const std::string &name, Teuchos::RCP< const Teuchos::Comm< int > > comm)

void	enableVerbose (const bool enable_verbose)
	If set to true, print timer start/stop to verbose ostream. More...

void	enableVerboseTimestamps (const unsigned levels)
	Enable timestamps in verbose mode for the number of levels specified. More...

void	setVerboseOstream (const Teuchos::RCP< std::ostream > &os)
	Set the ostream for verbose mode(defaults to std::cout). More...

void	disableTimers ()

void	enableTimers ()

void	aggregateMpiData (Teuchos::RCP< const Teuchos::Comm< int > > comm, OutputOptions options=OutputOptions())

double	getMpiAverageTime (const std::string &flat_timer_name)

double	getMpiAverageCount (const std::string &flat_timer_name)

bool	isTimer (const std::string &flat_timer_name)

Protected Member Functions
void	flatten ()

void	merge (Teuchos::RCP< const Teuchos::Comm< int > > comm)

void	collectRemoteData (Teuchos::RCP< const Teuchos::Comm< int > > comm, const OutputOptions &options)

int	getFlatNameIndex (const std::string &flat_timer_name)

double	computeColumnWidthsForAligment (std::string prefix, int print_level, std::vector< bool > &printed, double parent_time, const OutputOptions &options)

double	printLevel (std::string prefix, int level, std::ostream &os, std::vector< bool > &printed, double parent_time, const OutputOptions &options)

double	printLevelXML (std::string prefix, int level, std::ostream &os, std::vector< bool > &printed, double parent_time, const std::string &rootName="")

Protected Attributes
LevelTimer *	top_
	Current level running. More...

LevelTimer	timer_
	Base timer. More...

bool	enable_verbose_
	If set to true, prints to the debug ostream. At construction, default value is set from environment variable. More...

unsigned	verbose_timestamp_levels_
	If set to a value greater than 0, verbose mode will print that many levels of timers with timestamps. A value of zero disables timestamps. More...

Teuchos::RCP< std::ostream >	verbose_ostream_
	For debugging, this is the ostream used for printing. More...

bool	enable_timers_
	Used to disable timers for asynchronous work. More...

Detailed Description

This class allows one to push and pop timers on and off a stack.

To use this class one would do something like this

StackedTimer timer(); // construct top level timer timer.start("some comp"); do_work(); timer.start("sub comp"); more_work(); timer.stop(); // stopping sub comp timer.stop(); // stopping comp

timer.stop(); // stopping all timer stuff timer.report(std::cout); // dump to screen

Definition at line 191 of file Teuchos_StackedTimer.hpp.

Constructor & Destructor Documentation

Teuchos::StackedTimer::StackedTimer	(	const char *	name,
		const bool	start_base_timer = `true`
	)

inlineexplicit

Construct a stacked timer

Parameters

[in]	name	Top level name of the timer
[in]	start_top_timer	Automatically start the top level timer. If set to false, the user will have to start it manually.

Definition at line 437 of file Teuchos_StackedTimer.hpp.

Member Function Documentation

void Teuchos::StackedTimer::startBaseTimer ( )

inline

Start the base level timer only

Definition at line 462 of file Teuchos_StackedTimer.hpp.

void Teuchos::StackedTimer::stopBaseTimer ( )

inline

Stop the base level timer only

Definition at line 472 of file Teuchos_StackedTimer.hpp.

void Teuchos::StackedTimer::start	(	const std::string	name,
		const bool	push_kokkos_profiling_region = `true`
	)

inline

Start a sublevel timer

Parameters

[in]	name	Name of the timer you wish to start
[in]	push_kokkos_profiling_region	Optional parameter that if set to true, will pushRegion() in kokkos profiling for this timer. The TimeMonitor will always set this to false since it does its own pushRegion() in the Timer object (this prevents double registering with kokkos).

Definition at line 484 of file Teuchos_StackedTimer.hpp.

void Teuchos::StackedTimer::stop	(	const std::string &	name,
		const bool	pop_kokkos_profiling_region = `true`
	)

inline

Stop the current top running timer, should be called for the root timer prior to final output

Parameters

[in]	name	Name of the timer you wish to stop
[in]	pop_kokkos_profiling_region	Optional parameter that if set to true, will popRegion() in kokkos profiling for this timer. The TimeMonitor will always set this to false since it does its own pushRegion() in the Timer object (this prevents double registering with kokkos).

Definition at line 523 of file Teuchos_StackedTimer.hpp.

void Teuchos::StackedTimer::incrementUpdates ( const long long i = 1 )

inline

Increment the iteration count for the running timer

Parameters

[in] i amount to increment the count

Definition at line 562 of file Teuchos_StackedTimer.hpp.

double Teuchos::StackedTimer::accumulatedTime ( const std::string & name = "" )

inline

Return the accumulated time the named timer has, if name is blank top level timer

Parameters

[in] name Name of the timer to output

Returns: amount of time in seconds

Definition at line 571 of file Teuchos_StackedTimer.hpp.

double Teuchos::StackedTimer::accumulatedTimePerUpdate ( const std::string & name = "" )

inline

Return the time spent per update at a given level

Parameters

[in] name name of subtimer, if blank return current level time

Returns: time in seconds per update at provided level

Definition at line 583 of file Teuchos_StackedTimer.hpp.

double Teuchos::StackedTimer::accumulatedTimePerTimerCall ( const std::string & name = "" )

inline

Return the time spent per timer start/stop at a given level

Parameters

[in] name name of subtimer, if blank return current level time

Returns: time in seconds per start/stop call at provided level

Definition at line 594 of file Teuchos_StackedTimer.hpp.

const BaseTimer* Teuchos::StackedTimer::findBaseTimer ( const std::string & name ) const

inline

Return pointer to the BaseTimer corresponding to a given string (full string name)

Parameters

name	input string to search for

Returns: BaseTimer

Definition at line 606 of file Teuchos_StackedTimer.hpp.

BaseTimer::TimeInfo Teuchos::StackedTimer::findTimer ( const std::string & name )

inline

Return the time info for a given string (full string name)

Parameters

name	input string to search for

Returns: Time data

Definition at line 618 of file Teuchos_StackedTimer.hpp.

void Teuchos::StackedTimer::report	(	std::ostream &	os,
		Teuchos::RCP< const Teuchos::Comm< int > >	comm,
		OutputOptions	options = `OutputOptions()`
	)

Dump all the data from all the MPI ranks to an ostream

Parameters

[in,out]	os	- Output stream
[in]	comm	- Teuchos comm pointer
[in]	options	- Options on what data to output and how to format the data

Definition at line 679 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::reportXML	(	std::ostream &	os,
		const std::string &	datestamp,
		const std::string &	timestamp,
		Teuchos::RCP< const Teuchos::Comm< int > >	comm
	)

Dump all the data from all the MPI ranks to the given output stream, in Watchr XML format. reportWatchrXML() is a wrapper for this function that creates os as a std::ofstream.

Parameters

[in,out]	os	- stream where XML will be written
[in]	datestamp	- UTC datestamp in the format YYYY_MM_DD
[in]	timestamp	- UTC timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SS (HH in 24-hour time, and T is just the character 'T')
[in]	comm	- Teuchos comm pointer

Returns: The complete filename, or empty string if no output was produced.

Definition at line 711 of file Teuchos_StackedTimer.cpp.

std::string Teuchos::StackedTimer::reportWatchrXML	(	const std::string &	name,
		Teuchos::RCP< const Teuchos::Comm< int > >	comm
	)

Dump all the data from all the MPI ranks to an XML file. This function calls reportXML and is intended to be used directly by performance tests.

In the XML report, the top-level timer name (representing the total) will be replaced with name (the name of the test). This becomes the top-level chart name in Watchr.

The output filename is controlled by two environment variables: $WATCHR_PERF_DIR (required for output) and $WATCHR_BUILD_NAME (optional). $WATCHR_PERF_DIR is the directory where the output file will be created. If it is not set or is empty, no output will be produced and the function returns an empty string on all ranks.

If $WATCHR_BUILD_NAME is set, the filename is $WATCHR_BUILD_NAME-name_$DATESTAMP.xml. Additionally, the build name is prepended (verbatim) to the the top-level chart name, so that Watchr knows it is a different data series than runs of the same test from other builds.

If $WATCHR_BUILD_NAME is not set or is empty, the filename is just name_$DATESTAMP.xml . DATESTAMP is normally calculated from the current UTC time, in the format YYYY_MM_DD. DATESTAMP can be overridden by setting $WATCHR_BUILD_DATE to a date (also in YYYY_MM_DD format).

Optionally, the environment variable $TRILINOS_GIT_SHA can be set to the Git revision hash. This is added to the performance report as metadata, and will appear in Watchr when mousing over a data point. Only the first 10 characters are output.

In the filename, all spaces in will be replaced by underscores.

Parameters

[in]	name	- Name of performance test
[in]	comm	- Teuchos comm pointer

Returns: If on rank 0 and output was produced, the complete output filename. Otherwise the empty string.

Definition at line 725 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::enableVerbose ( const bool enable_verbose )

If set to true, print timer start/stop to verbose ostream.

Definition at line 818 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::enableVerboseTimestamps ( const unsigned levels )

Enable timestamps in verbose mode for the number of levels specified.

Definition at line 821 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::setVerboseOstream ( const Teuchos::RCP< std::ostream > & os )

Set the ostream for verbose mode(defaults to std::cout).

Definition at line 824 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::disableTimers ( )

Once called, the start and stop calls are no-ops. Used to stop timers during asynchronous execution.

Definition at line 827 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::enableTimers ( )

Once called, the start and stop calls are reenabled. Used to restart timers after a call to disableTimers().

Definition at line 830 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::aggregateMpiData	(	Teuchos::RCP< const Teuchos::Comm< int > >	comm,
		OutputOptions	options = `OutputOptions()`
	)

Aggregate timer data from all MPI processes to rank 0 of the comm.

Parameters

[in]	comm	- Teuchos comm pointer.
[in]	options	- Determines what data the user wants aggregated.

Definition at line 833 of file Teuchos_StackedTimer.cpp.

double Teuchos::StackedTimer::getMpiAverageTime ( const std::string & flat_timer_name )

Returns the total time for the timer averaged across all MPI processes (inlcudes only the MPI processes where the timer exists).

Parameters

[in] flat_timer_name Timer name that is flattened to include parent names in the string.

Returns: Total timer averaged across all MPI processes.

Definition at line 841 of file Teuchos_StackedTimer.cpp.

double Teuchos::StackedTimer::getMpiAverageCount ( const std::string & flat_timer_name )

Returns the number of times this timer was started, averaged across all MPI processes (inlcudes only the MPI processes where the timer exists).

Parameters

[in] flat_timer_name Timer name that is flattened to include parent names in the string.

Returns: Total number of times the timer was started, averaged across all MPI processes.

Definition at line 847 of file Teuchos_StackedTimer.cpp.

bool Teuchos::StackedTimer::isTimer ( const std::string & flat_timer_name )

Returns true if the timer name exists in the stacked timer. This can only be called after aggregateMpiData() is called so that the flattened names are generated.

Parameters

[in] flat_timer_name Timer name that is flattened to include parent names in the string.

Returns: true if the timer exists.

Definition at line 868 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::flatten ( )

protected

Flatten the timers into a single array

Definition at line 89 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::merge ( Teuchos::RCP< const Teuchos::Comm< int > > comm )

protected

Merge all the timers together into a single structure

Parameters

[in] comm - Communicator to use

Definition at line 97 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::collectRemoteData	(	Teuchos::RCP< const Teuchos::Comm< int > >	comm,
		const OutputOptions &	options
	)

protected

Migrate all the timer data to rank=0 if parallel

Definition at line 104 of file Teuchos_StackedTimer.cpp.

int Teuchos::StackedTimer::getFlatNameIndex ( const std::string & flat_timer_name )

protected

Returns the index into the mpi aggregated timers for a timer name

Definition at line 853 of file Teuchos_StackedTimer.cpp.

double Teuchos::StackedTimer::computeColumnWidthsForAligment	(	std::string	prefix,
		int	print_level,
		std::vector< bool > &	printed,
		double	parent_time,
		const OutputOptions &	options
	)

protected

Compute the column widths to align the output from report() in columns.

Returns: total time for this level

Definition at line 234 of file Teuchos_StackedTimer.cpp.

double Teuchos::StackedTimer::printLevel	(	std::string	prefix,
		int	level,
		std::ostream &	os,
		std::vector< bool > &	printed,
		double	parent_time,
		const OutputOptions &	options
	)

protected

Recursive call to print a level of timer data.

Definition at line 373 of file Teuchos_StackedTimer.cpp.

double Teuchos::StackedTimer::printLevelXML	(	std::string	prefix,
		int	level,
		std::ostream &	os,
		std::vector< bool > &	printed,
		double	parent_time,
		const std::string &	rootName = `""`
	)

protected

Recursive call to print a level of timer data, in Watchr XML format. If non-empty, rootName will replace the root level's timer name in the output. If empty or level > 0, it has no effect.

Definition at line 622 of file Teuchos_StackedTimer.cpp.

Member Data Documentation

LevelTimer* Teuchos::StackedTimer::top_

protected

Current level running.

Definition at line 769 of file Teuchos_StackedTimer.hpp.

LevelTimer Teuchos::StackedTimer::timer_

protected

Base timer.

Definition at line 771 of file Teuchos_StackedTimer.hpp.

bool Teuchos::StackedTimer::enable_verbose_

protected

If set to true, prints to the debug ostream. At construction, default value is set from environment variable.

Definition at line 814 of file Teuchos_StackedTimer.hpp.

unsigned Teuchos::StackedTimer::verbose_timestamp_levels_

protected

If set to a value greater than 0, verbose mode will print that many levels of timers with timestamps. A value of zero disables timestamps.

Definition at line 817 of file Teuchos_StackedTimer.hpp.

Teuchos::RCP<std::ostream> Teuchos::StackedTimer::verbose_ostream_

protected

For debugging, this is the ostream used for printing.

Definition at line 820 of file Teuchos_StackedTimer.hpp.

bool Teuchos::StackedTimer::enable_timers_

protected

Used to disable timers for asynchronous work.

Definition at line 823 of file Teuchos_StackedTimer.hpp.

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

Classes

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation