Teuchos Package Browser (Single Doxygen Collection) Version of the Day
Teuchos::TimeMonitor Class Reference

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

#include <Teuchos_TimeMonitor.hpp>

Inheritance diagram for Teuchos::TimeMonitor:
Inheritance graph
[legend]

List of all members.

Constructor/Destructor

 TimeMonitor (Time &timer, bool reset=false)
 Constructor: starts the timer.
 ~TimeMonitor ()
 Destructor: stops the timer.

Static functions

static 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 computeGlobalTimerStatistics (stat_map_type &statData, std::vector< std::string > &statNames, Ptr< const Comm< int > > comm, const ECounterSetOp setOp=Intersection)
 Compute global timer statistics for all timers on the given communicator.
static void computeGlobalTimerStatistics (stat_map_type &statData, std::vector< std::string > &statNames, const ECounterSetOp setOp=Intersection)
 Compute global timer statistics for all timers on all (MPI) processes.
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)
 Print summary statistics for all timers on the given communicator.
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 on all (MPI) processes.

Detailed Description

A scope-safe timer wrapper class.

This class wraps a nonconst reference to a Teuchos::Time timer object. The 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.

This class also keeps track of the set of all timers as class (not instance) data, and has a class method (summarize()) for printing out global statistics (min, mean, and max over all MPI processes, in an MPI build). The summarize() method works correctly even if some MPI processes have different timers than other processes.

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

Definition at line 159 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 202 of file Teuchos_TimeMonitor.cpp.

Teuchos::TimeMonitor::~TimeMonitor ( )

Destructor: stops the timer.

Definition at line 208 of file Teuchos_TimeMonitor.cpp.


Member Function Documentation

static 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 187 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().

Preconditions:

  • None of the timers must currently be running.

Definition at line 213 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 
) [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.

Suppose there are $P$ processes in the communicator and $N$ unique timers in the global union. 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 "Min" and "Max" 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 "Mean" is an arithmetic mean of all timings. It is not cumulative over call counts; it reports an average timing for a single invocation over all calls on all processes, not weighting any one process more than the others. Thus, the mean is not comparable with the min or max. To make it comparable, multiply the mean timing by the mean call count, and divide by the number of processes in the communicator. This makes the mean cumulative.

The mean for each timer equals 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.) Along with the mean timing comes the aritmetic mean of the call counts. 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.

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

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 (e.g., "Min", "Mean", or "Max") 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.
Note:
This method must called as a collective by all processes in the communicator.

Definition at line 689 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::computeGlobalTimerStatistics ( stat_map_type statData,
std::vector< std::string > &  statNames,
const ECounterSetOp  setOp = Intersection 
) [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 886 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 
) [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 min, average (arithmetic mean), and max of all timings over all processes in the communicator. 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, 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.
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.

Definition at line 715 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 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 870 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