Teuchos - Trilinos Tools Package Version of the Day
Teuchos::TimeMonitor Class Reference

A scope-safe timer wrapper class. More...

#include <Teuchos_TimeMonitor.hpp>

Inheritance diagram for Teuchos::TimeMonitor:
Teuchos::PerformanceMonitorBase< Time >

List of all members.

Public Member Functions

 TimeMonitor (Time &timer, bool reset=false)
 Constructor starts the timer.
 ~TimeMonitor ()
 Destructor causes timer to stop.

Static Public Member Functions

Static functions
static Teuchos::RCP< TimegetNewTimer (const std::string &name)
 Return a new timer with the given name.
static void zeroOutTimers ()
 Reset all global timers to zero.
static void summarize (std::ostream &out=std::cout, const bool alwaysWriteLocal=false, const bool writeGlobalStats=true, const bool writeZeroTimers=true, const ECounterSetOp setOp=Intersection)
 Print summary statistics for all timers.

Detailed Description

A scope-safe timer wrapper class.

TimeMonitor objects start the timer when constructed, and stop the timer when the destructor is called. Termination upon destruction lets this timer behave correctly even if scope is exited because of an exception. TimeMonitor also keeps track of the set of all timers, and has a method (summarize()) for printing out global statistics (min, mean, and max over all MPI processes, in an MPI build).

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!
Teuchos::TimeMonitor uses the Teuchos::Time class internally.


Definition at line 140 of file Teuchos_TimeMonitor.hpp.

Constructor & Destructor Documentation

Teuchos::TimeMonitor::TimeMonitor ( Time timer,
bool  reset = false 

Constructor starts the timer.

timer[in/out] Reference to the timer to be wrapped.
reset[in] If true, reset the timer before starting it. Default behavior is not to reset the timer.

Definition at line 53 of file Teuchos_TimeMonitor.cpp.

Teuchos::TimeMonitor::~TimeMonitor ( )

Destructor causes timer to stop.

Definition at line 59 of file Teuchos_TimeMonitor.cpp.

Member Function Documentation

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

Return a new timer with the given name.

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


Definition at line 166 of file Teuchos_TimeMonitor.hpp.

void Teuchos::TimeMonitor::zeroOutTimers ( ) [static]

Reset all global timers to zero.

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


  • None of the timers must currently be running.

Definition at line 64 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 
) [static]

Print summary statistics for all timers.

The typical use case for timers is that all MPI processes create the same set of timers, and then want to report summary statistics. This method's default behavior (writeGlobalStats=true) is to report the mininum, arithmetic mean, and maximum for each timer. Duplicate timers get merged additively.

Note that different MPI processes may have different sets of timers. If writeGlobalStats is true, we have to reconcile the different sets of timers somehow. This method gives you two options: if setOp is Intersection, it computes the intersection (the common subset) of timers on all MPI processes, otherwise if setOp is Union, it computes the union of timers on all MPI processes. Intersection is the default, since it expresses a common case of timing global solvers.

Suppose there are $P$ MPI processes, $N$ unique timers in the global union, and $n$ unique timers in the global intersection. 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 MPI process").

out[out] Output stream to which to write. This will only be used on MPI Rank 0.
alwaysWriteLocal[in] If true, MPI Proc 0 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 min, average (arithmetic mean), and max of all timings over all processors (in MPI_COMM_WORLD). If there is only one MPI process or if this is a non-MPI build of Trilinos, we only 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.
setOp[in] If Intersection, compute and display the intersection of all created timers over all processors. If Union, compute and display the union of all created timers over all processors.
If writeGlobalStats is true, this method must be called by all processors. This method will only perform communication if writeGlobalStats is true.

Definition at line 163 of file Teuchos_TimeMonitor.cpp.

The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines