A scope-safe timer wrapper class, that can compute global timer statistics. More...

#include <Teuchos_TimeMonitor.hpp>

Inheritance diagram for Teuchos::TimeMonitor:

Public Member Functions
Constructor/Destructor
	TimeMonitor (Time &timer, bool reset=false)
	Constructor: starts the timer. More...

	~TimeMonitor ()
	Destructor: stops the timer. More...

Public Member Functions inherited from Teuchos::PerformanceMonitorBase< Time >
	PerformanceMonitorBase (Time &counter_in, bool reset=false)
	Construct with a counter. More...

virtual	~PerformanceMonitorBase ()
	Destructor. More...

Static Public Member Functions
static RCP< Time >	getNewTimer (const std::string &name)
	Return a new timer with the given name (class method). More...

static void	disableTimer (const std::string &name)
	Disable the timer with the given name. More...

static void	enableTimer (const std::string &name)
	Enable the timer with the given name. More...

static void	zeroOutTimers ()
	Reset all global timers to zero. More...

static void	computeGlobalTimerStatistics (stat_map_type &statData, std::vector< std::string > &statNames, Ptr< const Comm< int > > comm, const ECounterSetOp setOp=Intersection, const std::string &filter="")
	Compute global timer statistics for all timers on the given communicator. More...

static void	computeGlobalTimerStatistics (stat_map_type &statData, std::vector< std::string > &statNames, const ECounterSetOp setOp=Intersection, const std::string &filter="")
	Compute global timer statistics for all timers on all (MPI) processes. More...

static void	summarize (Ptr< const Comm< int > > comm, std::ostream &out=std::cout, const bool alwaysWriteLocal=false, const bool writeGlobalStats=true, const bool writeZeroTimers=true, const ECounterSetOp setOp=Intersection, const std::string &filter="", const bool ignoreZeroTimers=false)
	Print summary statistics for all timers on the given communicator. More...

static void	summarize (std::ostream &out=std::cout, const bool alwaysWriteLocal=false, const bool writeGlobalStats=true, const bool writeZeroTimers=true, const ECounterSetOp setOp=Intersection, const std::string &filter="", const bool ignoreZeroTimers=false)
	Print summary statistics for all timers on all (MPI) processes. More...

static void	report (Ptr< const Comm< int > > comm, std::ostream &out, const std::string &filter, const RCP< ParameterList > &params=null)
	Report timer statistics to the given output stream. More...

static void	report (Ptr< const Comm< int > > comm, std::ostream &out, const RCP< ParameterList > &params=null)
	Report timer statistics to the given output stream. More...

static void	report (std::ostream &out, const std::string &filter, const RCP< ParameterList > &params=null)
	Report timer statistics to the given output stream. More...

static void	report (std::ostream &out, const RCP< ParameterList > &params=null)
	Report timer statistics to the given output stream. More...

static RCP< const ParameterList >	getValidReportParameters ()
	Default parameters (with validators) for report(). More...

static void	setStackedTimer (const Teuchos::RCP< Teuchos::StackedTimer > &t)
	Sets the StackedTimer that the TimeMonitor will use to insert timings into. More...

static const Teuchos::RCP < Teuchos::StackedTimer > &	getStackedTimer ()
	Returns the StackedTimer used by the TimeMonitor. More...

Static Public Member Functions inherited from Teuchos::PerformanceMonitorBase< Time >
static RCP< Time >	getNewCounter (const std::string &name)
	Create a new counter with the specified name and add it to a global set of counters of this type. More...

static TableFormat &	format ()
	Table format that will be used to print a summary of timer results. More...

static RCP< Time >	lookupCounter (const std::string &name)
	Return the first counter with the given name, or null if none. More...

static void	clearCounters ()
	"Forget" about all counters created with getNewCounter(). More...

static TEUCHOS_DEPRECATED void	clearTimers ()
	"Forget" about all counters created with getNewCounter(). More...

static void	clearCounter (const std::string &name)
	"Forget" about any counters with the given name. More...

static TEUCHOS_DEPRECATED void	clearTimer (const std::string &name)
	"Forget" about any counters with the given name. More...

Additional Inherited Members
Protected Member Functions inherited from Teuchos::PerformanceMonitorBase< Time >
const Time &	counter () const
	Constant access to the instance's counter reference. More...

Time &	counter ()
	Nonconstant access to the instance's counter reference. More...

bool	isRecursiveCall () const
	Whether we are currently in a recursive call of the counter. More...

Static Protected Member Functions inherited from Teuchos::PerformanceMonitorBase< Time >
static std::map< std::string, RCP< Time > > &	counters ()
	Array of all counters that were created with getNewCounter() on the calling (MPI) process. More...

Detailed Description

A scope-safe timer wrapper class, that can compute global timer statistics.

An instance of the TimeMonitor class wraps a nonconst reference to a Time timer object. TimeMonitor's constructor starts the timer, and its destructor stops the timer. This ensures scope safety of timers, so that no matter how a scope is exited (whether the normal way or when an exception is thrown), a timer started in the scope is stopped when the scope is left.

TimeMonitor also has class methods that create or destroy timers and compute global timer statistics. If you create a timer using getNewCounter() (or the deprecated getNewTimer()), it will add that timer to the set of timers for which to compute global statistics. The summarize() and report() methods will print global statistics for these timers, like the minimum, mean, and maximum time over all processes in the communicator, for each timer. These methods work correctly even if some processes have different timers than other processes. You may also use computeGlobalTimerStatistics() to compute the same global statistics, if you wish to use them in your program or output them in a different format than that of these methods.

If Teuchos is configured with TPL_ENABLE_Valgrind=ON and Teuchos_TIME_MASSIF_SNAPSHOTS=ON Valgrind Massif snapshots are taken before and after each Time invocation. The resulting memory profile can be plotted using core/utils/plotMassifMemoryUsage.py

Warning: This class must only be used to time functions that are called only within the main program. It may not be used in pre-program setup or post-program teardown!

Examples:: TimeMonitor/cxx_main.cpp.

Definition at line 178 of file Teuchos_TimeMonitor.hpp.

Constructor & Destructor Documentation

Teuchos::TimeMonitor::TimeMonitor	(	Time &	timer,
		bool	reset = `false`
	)

Constructor: starts the timer.

Parameters

timer	[in/out] Reference to the timer to be wrapped. This constructor starts the timer, and the destructor stops the timer.
reset	[in] If true, reset the timer before starting it. Default behavior is not to reset the timer.

Definition at line 256 of file Teuchos_TimeMonitor.cpp.

Teuchos::TimeMonitor::~TimeMonitor ( )

Destructor: stops the timer.

Definition at line 268 of file Teuchos_TimeMonitor.cpp.

Member Function Documentation

static RCP<Time> Teuchos::TimeMonitor::getNewTimer ( const std::string & name )

inlinestatic

Return a new timer with the given name (class method).

Call getNewCounter() or this method if you want to create a new named timer, and you would like TimeMonitor to track the timer for later computation of global statistics over processes.

This method wraps getNewCounter() (inherited from the base class) for backwards compatibiity.

Definition at line 207 of file Teuchos_TimeMonitor.hpp.

void Teuchos::TimeMonitor::disableTimer ( const std::string & name )

static

Disable the timer with the given name.

"Disable" means that the timer (Time instance) will ignore all calls to start(), stop(), and incrementNumCalls(). The effect will be as if the TimeMonitor had never touched the timer.

If the timer with the given name does not exist (was never created using getNewCounter() or getNewTimer()), then this method throws std::invalid_argument. Otherwise, it disables the timer. This effect lasts until the timer is cleared or until the timer is enabled, either by calling enableTimer() (see below) or by calling the Time instance's enable() method.

Disabling a timer does not exclude it from the list of timers printed by summarize() or report().

Definition at line 301 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::enableTimer ( const std::string & name )

static

Enable the timer with the given name.

If the timer with the given name does not exist (was never created using getNewCounter() or getNewTimer()), then this method throws std::invalid_argument. Otherwise, it undoes the effect of disableTimer() on the timer with the given name. If the timer with the given name was not disabled, then this method does nothing.

Definition at line 311 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::zeroOutTimers ( )

static

Reset all global timers to zero.

This method only affects Time objects created by getNewCounter() or getNewTimer().

Precondition: None of the timers must currently be running.

Definition at line 321 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::computeGlobalTimerStatistics	(	stat_map_type &	statData,
		std::vector< std::string > &	statNames,
		Ptr< const Comm< int > >	comm,
		const ECounterSetOp	setOp = `Intersection`,
		const std::string &	filter = `""`
	)

static

Compute global timer statistics for all timers on the given communicator.

The typical use case for Time and TimeMonitor is that all processes in a communicator create the same set of timers, and then want to report summary statistics. This method supports that typical use case. For each timer in the set, this method computes a list of global statistics. "Global" means "for all processes in the communicator." "Statistic" means the result of a reduction over the timing and call count values. Thus, each statistic includes both a timing and a call count. The current list of computed statistics includes the minimum and maximum timing (and the corresponding call count for each) and the arithmetic mean (timing and call count). This list may expand in the future.

Different processes may have different sets of timers. This method gives you two options for reconciling the sets. If setOp is Intersection, it computes the intersection (the common subset) of timers on all processes in the communicator. Otherwise, if setOp is Union, this method computes the union of timers on all processes in the communicator. Intersection is the default, since it means that all reported timers exist on all participating processes. For setOp=Union, timers that do not exist on some processes will be given a zero timing and call count, so that statistics make sense.

Note: This method must called as a collective by all processes in the communicator.

All output arguments are returned redundantly on all processes in the communicator. That makes this method an all-reduce.

Statistics collected

The "MinOverProcs" and "MaxOverProcs" timings are cumulative: the reported timing is for all calls. Along with the min resp. max timing comes the call count of the process who had the min resp. max. (If more than one process had the min resp. max timing, then the call count on the process with the smallest rank is reported.)

The "MeanOverProcs" equals the sum of the processes' cumulative timings, divided by the number of processes. Thus, it is cumulative over all calls, and is comparable with the "MinOverProcs" and "MaxOverProcs" timings. This differs from the "MeanOverCallCounts" (see below). This does not weight the mean by call counts.

The "MeanOverCallCounts" is an arithmetic mean of all timings. It is not cumulative. It reports the mean timing for a single invocation over all calls on all processes, not weighting any one process more than the others. For each timer, this is the sum of the cumulative timing over all processes, divided by the sum of the call counts over all processes for that timing. (We compute it a bit differently to help prevent overflow.) The "MeanOverCallCounts" is not comparable with the min, max, or "MeanOverProcs".

We report with both versions of the mean timing the mean call count over processes. This may be fractional, which is one reason why we report call counts as double rather than int. It has no particular connection to the mean timing.

Performance

This operation requires interprocess communication. Suppose there are $P$ processes in the given communicator, and $N$ unique timers in the global union of all processes' timers. Then, this method requires $O(\log P)$ messages ( $O(1)$ "reductions" and exactly 1 "broadcast") and $O(N)$ per-processor storage (in the worst case) when computing either the intersection or the union of timers (the algorithm is similar in either case). The whole algorithm takes at worst $O(N (\log N) (\log P))$ time along the critical path (i.e., on the "slowest process" in the communicator). The $N \log N$ term comes from sorting the timers by label at each stage of the reduction in order to compute their union or intersection.

Parameters

statData	[out] On output: Global timer statistics, stored as a map with key timer name, and with value the ordered list of statistics for that timer. The `statNames` output has the same order as the ordered list of statistics for each timer. Each entry of the statistics list is a (timing, call count) pair, the meaning of which depends on the particular statistic (see above).
statNames	[out] On output: Each value in the statData map is a vector. That vector v has the same number of entries as statNames. statNames[k] is the name of the statistic (see above) stored as v[k]. Always refer to statNames for the number and names of statistics.
comm	[in] Communicator whose process(es) will participate in the gathering of timer statistics. This is a Ptr and not an RCP, because RCP would suggest that TimeMonitor were keeping the communicator around after return of this method. Ptr suggests instead that TimeMonitor will only reference the communicator during this method. If you have an RCP, you can turn it into a Ptr by calling its ptr() method: RCP<const Comm<int> > myComm = ...; TimeMonitor::computeGlobalTimerStatistics (statData, statNames, myComm.ptr());
setOp	[in] If `Intersection`, compute statistics for the intersection of all created timers over all processes in the communicator. If `Union`, compute statistics for the union of all created timers over all processes in the communicator.
filter	[in] Filter for timer labels. If filter is not empty, this method will only compute statistics for timers whose labels begin with this string.

Definition at line 896 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::computeGlobalTimerStatistics	(	stat_map_type &	statData,
		std::vector< std::string > &	statNames,
		const ECounterSetOp	setOp = `Intersection`,
		const std::string &	filter = `""`
	)

static

Compute global timer statistics for all timers on all (MPI) processes.

This is an overload of the above computeGlobalTimerStatistics() method for when the caller does not want to provide a communicator explicitly. This method "does the right thing" in that case. Specifically:

If Trilinos was not built with MPI support, this method assumes a serial "communicator" containing one process.
If Trilinos was built with MPI support and MPI has been initialized (via MPI_Init() or one of the wrappers in Epetra or Teuchos), this method uses MPI_COMM_WORLD as the communicator. This is the most common case.
If Trilinos was built with MPI support and MPI has not been initialized, this method will use a "serial" communicator (that does not actually use MPI). This may produce output on all the MPI processes if you are running with Trilinos as an MPI job with more than one process. Thus, if you intend to use this method in parallel, you should first initialize MPI. (We cannot initialize MPI for you, because we have no way to know whether you intend to run an MPI-enabled build serially.)

Warning: If you call this method when MPI is running, you must call it on all processes in MPI_COMM_WORLD. Otherwise, the method will never finish, since it will be waiting forever for the non-participating processes. If you want to use computeGlobalTimerStatistics() on a subcommunicator, please use the overloaded version above that takes a communicator as an input argument.

Definition at line 1103 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::summarize	(	Ptr< const Comm< int > >	comm,
		std::ostream &	out = `std::cout`,
		const bool	alwaysWriteLocal = `false`,
		const bool	writeGlobalStats = `true`,
		const bool	writeZeroTimers = `true`,
		const ECounterSetOp	setOp = `Intersection`,
		const std::string &	filter = `""`,
		const bool	ignoreZeroTimers = `false`
	)

static

Print summary statistics for all timers on the given communicator.

If writeGlobalStatus=true, this method computes the same statistics as computeGlobalTimerStatistics(), using the same collective algorithm. (writeGlobalStatus=false means that only the process with rank 0 in the communicator reports its timers' data.) It then reports the results to the given output stream on the process with rank 0 in the given communicator. Output follows a human-readable tabular form.

Parameters

comm	[in] Communicator whose process(es) will participate in the gathering of timer statistics. This is a Ptr and not an RCP, because RCP would suggest that TimeMonitor were keeping the communicator around after return of this method. Ptr suggests instead that TimeMonitor will only reference the communicator during this method. If you have an RCP, you can turn it into a Ptr by calling its ptr() method: RCP<const Comm<int> > myComm = ...; TimeMonitor::summarize (myComm.ptr());
out	[out] Output stream to which to write. This will only be used on the process with rank 0 in the communicator.
alwaysWriteLocal	[in] If true, the process with Rank 0 in the communicator will write its local timings to the given output stream. Defaults to false, since the global statistics are more meaningful. If the local set of timers differs from the global set of timers (either the union or the intersection, depending on `setOp`), Proc 0 will create corresponding local timer data (not corresponding timers) with zero elapsed times and call counts, just to pad the table of output.
writeGlobalStats	[in] If true (the default), compute and display the statistics that `computeGlobalTimerStatistics()` computes. If there is only one MPI process or if this is a non-MPI build of Trilinos, only compute and show the "global" timings, without the "statistics" that would be all the same anyway.
writeZeroTimers	[in] If false, do not display results for timers that have never been called (numCalls() == 0). If true, display results for all timers, regardless of their call count. Note that `setOp` and `writeGlobalStats` might reintroduce timers with zero call counts.
setOp	[in] If `Intersection`, compute and display the intersection of all created timers over all processes in the communicator. If `Union`, compute and display the union of all created timers over all processes in the communicator.
filter	[in] Filter for timer labels. If filter is not empty, this method will only print timers whose labels begin with this string.
ignoreZeroTimers	[in] Processes that either do not have a particular timer or have zero time for a timer are not used in calculating global statistics. This mode requires one additional all-reduce per invocation.

Note: If writeGlobalStats is true, this method must be called as a collective by all processes in the communicator. This method will only perform communication if writeGlobalStats is true.

Examples:: TimeMonitor/cxx_main.cpp.

Definition at line 925 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::summarize	(	std::ostream &	out = `std::cout`,
		const bool	alwaysWriteLocal = `false`,
		const bool	writeGlobalStats = `true`,
		const bool	writeZeroTimers = `true`,
		const ECounterSetOp	setOp = `Intersection`,
		const std::string &	filter = `""`,
		const bool	ignoreZeroTimers = `false`
	)

static

Print summary statistics for all timers on all (MPI) processes.

This is an overload of the above summarize() method for when the caller does not want to provide a communicator explicitly. This method "does the right thing" in that case. For an explanation of what that means, see the documentation of the overload of computeGlobalTimerStatistics() that does not require a communicator argument.

Warning: If you call this method when MPI is running, you must call it on all processes in MPI_COMM_WORLD. Otherwise, the method will never finish, since it will be waiting forever for the non-participating processes. If you want to use summarize() on a subcommunicator, please use the overloaded version above that takes a communicator as an input argument.

Definition at line 1085 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::report	(	Ptr< const Comm< int > >	comm,
		std::ostream &	out,
		const std::string &	filter,
		const RCP< ParameterList > &	params = `null`
	)

static

Report timer statistics to the given output stream.

This is like summarize(), but gives you more control over the output format. To get the default parameters, either call getValidReportParameters(), or call this method with params nonnull but empty (it will fill in default parameters).

Parameters

comm	[in] Communicator whose process(es) will participate in the gathering of timer statistics. This is a Ptr and not an RCP, because RCP would suggest that TimeMonitor were keeping the communicator around after return of this method. Ptr suggests instead that TimeMonitor will only reference the communicator during this method. If you have an RCP, you can turn it into a Ptr by calling its ptr() method: RCP<const Comm<int> > myComm = ...; TimeMonitor::report (myComm.ptr (), ...);
out	[out] Output stream to which to write. This will only be used on the process with rank 0 in the communicator.
filter	[in] Filter for timer labels. If filter is not empty, this method will only print timers whose labels begin with this string.
params	[in/out] Parameters to control output format and which statistics to generate. If null, we use default parameters if this method was not yet called with params nonnull, otherwise we use the previous set of parameters. If nonnull, we read the given parameters, filling in defaults, and use the resulting parameters for all subsequent calls to report() (until new parameters are set).

Supported parameters

Here is the current set of supported parameters:

"Report format": "Table" (default), "YAML"
"YAML style": "spacious" (default), "compact"
"How to merge timer sets": "Intersection" (default), "Union"
"alwaysWriteLocal": true, false (default)
"writeGlobalStats": true (default), false
"writeZeroTimers": true (default), false

This method currently supports two different output formats. "Table" format is the same tabular format which summarize() uses. It displays times and call counts in a table that is easy for humans to read, but hard to parse. "YAML" format uses a standard, structured, human-readable output format called YAML. YAML stands for YAML Ain't Markup Language.

"YAML style" refers to two variants of YAML output that report() can generate. The "compact" mode attempts to put as much data on each line as possible. It may be more readable when there are a small number of timers. The "spacious" mode prefers one line per datum whenever possible. Both modes have the same schema, that is, their output has the same hierarchical structure and thus the same parse tree.

(In technical terms: compact mode uses YAML's so-called "flow style" for sequences and mappings whenever possible, except at the outermost level where it would hinder readability. Spacious mode does not use "flow style" for lists or mappings. For an explanation of YAML's flow style, see Chapter 7 of the YAML 1.2 spec.)

"How to merge timer sets" refers to the set operation by which processors should combine their sets of timers in order to compute global timer statistics. This corresponds to the setOp argument of summarize().

The remaining Boolean parameters are the same as the eponymous arguments of summarize(), to whose documentation one should refer. There are some wrinkles: in particular, YAML output ignores the "alwaysWriteLocal" parameter and assumes "writeGlobalStats" is true.

Definition at line 1564 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::report	(	Ptr< const Comm< int > >	comm,
		std::ostream &	out,
		const RCP< ParameterList > &	params = `null`
	)

static

Report timer statistics to the given output stream.

This is like the 4-argument version of report(), but with a default filter.

Definition at line 1587 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::report	(	std::ostream &	out,
		const std::string &	filter,
		const RCP< ParameterList > &	params = `null`
	)

static

Report timer statistics to the given output stream.

This is like the 4-argument version of report(), but with a default communicator.

Definition at line 1595 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::report	(	std::ostream &	out,
		const RCP< ParameterList > &	params = `null`
	)

static

Report timer statistics to the given output stream.

This is like the 4-argument version of report(), but with a default communicator and a default filter.

Definition at line 1604 of file Teuchos_TimeMonitor.cpp.

RCP< const ParameterList > Teuchos::TimeMonitor::getValidReportParameters ( )

static

Default parameters (with validators) for report().

Definition at line 1498 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::setStackedTimer ( const Teuchos::RCP< Teuchos::StackedTimer > & t )

static

Sets the StackedTimer that the TimeMonitor will use to insert timings into.

Parameters

t	[in] StackedTimer object the TimeMonitor should insert timings into.

Definition at line 1486 of file Teuchos_TimeMonitor.cpp.

const Teuchos::RCP< Teuchos::StackedTimer > & Teuchos::TimeMonitor::getStackedTimer ( )

static

Returns the StackedTimer used by the TimeMonitor.

Definition at line 1492 of file Teuchos_TimeMonitor.cpp.

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

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Statistics collected

Performance

Supported parameters