Teuchos - Trilinos Tools Package Version of the Day
Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions
Teuchos::PerformanceMonitorBase< T > Class Template Reference

Common capabilities for collecting and reporting performance data across processors. More...

#include <Teuchos_PerformanceMonitorBase.hpp>

List of all members.

Public Member Functions

 PerformanceMonitorBase (T &counter_in, bool reset=false)
 Construct with a counter.
virtual ~PerformanceMonitorBase ()
 Destructor.

Static Public Member Functions

static RCP< T > getNewCounter (const std::string &name)
 Create a new counter with the specified name and append it to a global list of counters of this type.
static TableFormatformat ()
 Table format that will be used to print a summary of timer results.
static RCP< T > lookupCounter (const std::string &name)
 Return the first counter with the given name, or null if none.
static void clearCounters ()
 "Forget" about all counters created with getNewCounter().
static TEUCHOS_DEPRECATED void clearTimers ()
 "Forget" about all counters created with getNewCounter().
static void clearCounter (const std::string &name)
 "Forget" about any counters with the given name.
static TEUCHOS_DEPRECATED void clearTimer (const std::string &name)
 "Forget" about any counters with the given name.

Protected Member Functions

const T & counter () const
 Constant access to the counter reference.
T & counter ()
 Nonconstant access to the counter reference.
bool isRecursiveCall () const
 Whether we are currently in a recursive call of the counter.

Static Protected Member Functions

static Array< RCP< T > > & counters ()
 The array of all counters created using getNewCounter().

Detailed Description

template<class T>
class Teuchos::PerformanceMonitorBase< T >

Common capabilities for collecting and reporting performance data across processors.

PerformanceMonitorBase is templated on a counter type T (which might be a timer or a flop counter). The common capability of the counter type is a counter for the number of calls. Derived counter types may supply additional features.

PerformanceMonitorBase's constructor increments its counter's call count. Subclasses of PerformanceMonitorBase may do more upon construction or destruction; for example, TimeMonitor starts its timer on construction and stops it on destruction.

This class keeps a static list of all counters created using the getNewCounter() method during the course of a run. Counts from this list can then be printed out at the end of the run. Subclasses of PerformanceMonitorBase, such as TimeMonitor, may use this list to do things like compute global timer statistics over all the MPI processes.

PerformanceMonitorBase requires that the counter type T provide at least the following interface:

 // Constructor taking an std::string argument (the counter name).
 T (const std::string&);

 // Return the name of the counter.
 const std::string& name () const;
 
 // Add one to the number of calls (the number of times the counter
 // was started).
 void incrementNumCalls ();

 // Return the number of calls (see incrementNumCalls () above).
 int numCalls () const;

 // Indicate whether the counter is already running.
 bool isRunning () const;

Definition at line 141 of file Teuchos_PerformanceMonitorBase.hpp.


Constructor & Destructor Documentation

template<class T>
Teuchos::PerformanceMonitorBase< T >::PerformanceMonitorBase ( T &  counter_in,
bool  reset = false 
) [inline]

Construct with a counter.

Definition at line 145 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T>
virtual Teuchos::PerformanceMonitorBase< T >::~PerformanceMonitorBase ( ) [inline, virtual]

Destructor.

The destructor for the base class does nothing. We provide a virtual destructor for memory safety of derived classes.

Definition at line 156 of file Teuchos_PerformanceMonitorBase.hpp.


Member Function Documentation

template<class T>
static RCP<T> Teuchos::PerformanceMonitorBase< T >::getNewCounter ( const std::string &  name) [inline, static]

Create a new counter with the specified name and append it to a global list of counters of this type.

New counters should usually be created in this way rather than through a direct constructor call. This lets PerformanceMonitorBase keep track of them, for example, so that you can access the list of timers by calling counters(). Timers created in other ways are not included in the list returned by counters().

Definition at line 168 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T>
static TableFormat& Teuchos::PerformanceMonitorBase< T >::format ( ) [inline, static]

Table format that will be used to print a summary of timer results.

Definition at line 176 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T >
RCP< T > Teuchos::PerformanceMonitorBase< T >::lookupCounter ( const std::string &  name) [static]

Return the first counter with the given name, or null if none.

It is currently possible to create multiple counters with the same name using getNewCounter(). If multiple counters with the given name exist, this method simply returns the first in the list. Do not rely on the ability to create multiple counters with the same name; this may go away in the future.

If you want to create a counter with a given name if it doesn't yet exist, do the following:

 RCP<T> counter = PerformanceMonitorBase<T>::lookupCounter (name);
 if (counter.is_null())
   counter = PerformanceMonitorBase<T>::getNewCounter (name);

We do not offer this functionality as a single class method ("lookupOrCreateCounter()"), because it is easy to misspell a timer name. If timers that don't exist yet are created silently, misspelled timer names can cause hard-to-find bugs. (Analogies: Fortran's "implicit none" or Perl's "use strict.")

Definition at line 284 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T >
void Teuchos::PerformanceMonitorBase< T >::clearCounters ( ) [static]

"Forget" about all counters created with getNewCounter().

This removes all counters from the current list of counters (as would be returned by counters()).

Definition at line 333 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T >
void Teuchos::PerformanceMonitorBase< T >::clearTimers ( ) [static]

"Forget" about all counters created with getNewCounter().

This removes all counters from the current list of counters (as would be returned by counters()).

Warning:
This method is DEPRECATED, because the name is inaccurate (the template parameter of PerformanceMonitorBase may be any kind of performance counter, not just a timer). Use clearCounters() instead.

Definition at line 326 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T >
void Teuchos::PerformanceMonitorBase< T >::clearCounter ( const std::string &  name) [static]

"Forget" about any counters with the given name.

If one or more counters with the given name was created using getNewCounter(), calling this method with that name will remove them from the global list of counters.

Definition at line 300 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T >
void Teuchos::PerformanceMonitorBase< T >::clearTimer ( const std::string &  name) [static]

"Forget" about any counters with the given name.

If one or more counters with the given name was created using getNewCounter(), calling this method with that name will remove them from the global list of counters.

Warning:
This method is DEPRECATED, because the name is inaccurate (the template parameter of PerformanceMonitorBase may be any kind of performance counter, not just a timer). Use clearCounter() instead.

Definition at line 319 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T>
const T& Teuchos::PerformanceMonitorBase< T >::counter ( ) const [inline, protected]

Constant access to the counter reference.

Definition at line 247 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T>
T& Teuchos::PerformanceMonitorBase< T >::counter ( ) [inline, protected]

Nonconstant access to the counter reference.

Definition at line 250 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T>
bool Teuchos::PerformanceMonitorBase< T >::isRecursiveCall ( ) const [inline, protected]

Whether we are currently in a recursive call of the counter.

Subclasses of PerformanceMonitorBase may use this information to control whether to start or stop the given counter. This matters in cases such as timing, where we don't want to start and stop timers multiple times within a single call stack.

Definition at line 258 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T>
static Array<RCP<T> >& Teuchos::PerformanceMonitorBase< T >::counters ( ) [inline, static, protected]

The array of all counters created using getNewCounter().

Definition at line 261 of file Teuchos_PerformanceMonitorBase.hpp.


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