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

#include <Teuchos_PerformanceMonitorBase.hpp>

Inheritance diagram for Teuchos::PerformanceMonitorBase< T >:

Public Member Functions
	PerformanceMonitorBase (T &counter_in, bool reset=false)
	Construct with a counter. More...

	PerformanceMonitorBase ()=delete
	Default constructor is deleted, since it would be unsafe. More...

virtual	~PerformanceMonitorBase ()=default
	Destructor. More...

Static Public Member Functions
static RCP< T >	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< T >	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 void	clearCounter (const std::string &name)
	"Forget" about any counters with the given name. More...

Protected Member Functions
const T &	counter () const
	Constant access to the instance's counter reference. More...

T &	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
static std::map< std::string, RCP< T > > &	counters ()
	Array of all counters that were created with getNewCounter() on the calling (MPI) process. More...

Static Private Member Functions
static void	freeTableFormat ()
	Free the singleton returned by format(). More...

static void	freeCounters ()
	Free the singleton returned by counters(). More...

Private Attributes
T &	counter_
	Reference to the counter being wrapped. More...

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

Static Private Attributes
static TableFormat *	format_ = nullptr
	Singleton object returned by format(). More...

static std::map< std::string, RCP< T > > *	counters_ = nullptr
	Singleton object returned by counters(). More...

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 124 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 128 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T>

Teuchos::PerformanceMonitorBase< T >::PerformanceMonitorBase ( )

delete

Default constructor is deleted, since it would be unsafe.

template<class T>

virtual Teuchos::PerformanceMonitorBase< T >::~PerformanceMonitorBase ( )

virtualdefault

Destructor.

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

Member Function Documentation

template<class T >

RCP< T > Teuchos::PerformanceMonitorBase< T >::getNewCounter ( const std::string & name )

static

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

If the counter already exists, just return the existing counter. If the counter doesn't already exist, create a new counter with that name and return it.

New counters should usually be created in this way rather than through a direct constructor call. This lets PerformanceMonitorBase keep track of them, so that methods like summarize() and report() know about them. Timers created in other ways are not included in the reports printed by these methods.

Definition at line 303 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T>

static void Teuchos::PerformanceMonitorBase< T >::freeTableFormat ( )

inlinestaticprivate

Free the singleton returned by format().

Warning: Only for use as atexit() handler.; This method is not reentrant. In particular, if multiple threads call this method at the same time, they might manage to double-delete format_. This could only happen if the format() method below is called twice by different threads.

Definition at line 170 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T>

static void Teuchos::PerformanceMonitorBase< T >::freeCounters ( )

inlinestaticprivate

Free the singleton returned by counters().

Warning: Only for use as atexit() handler.; This method is not reentrant. In particular, if multiple threads call this method at the same time, they might manage to double-delete counters_. This could only happen if the counters() method below is called twice by different threads.

Definition at line 186 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T>

static TableFormat& Teuchos::PerformanceMonitorBase< T >::format ( )

inlinestatic

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

Warning: This method is not reentrant. In particular, if multiple threads call this method at the same time, they might manage to double-register the atexit() handler for format_. This could only happen if this method is called twice by different threads.

Definition at line 202 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.

Definition at line 353 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 set of counters (as would be returned by counters()).

Definition at line 376 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 369 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T>

const T& Teuchos::PerformanceMonitorBase< T >::counter ( ) const

inlineprotected

Constant access to the instance's counter reference.

Definition at line 245 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T>

T& Teuchos::PerformanceMonitorBase< T >::counter ( )

inlineprotected

Nonconstant access to the instance's counter reference.

Definition at line 248 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T>

bool Teuchos::PerformanceMonitorBase< T >::isRecursiveCall ( ) const

inlineprotected

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 256 of file Teuchos_PerformanceMonitorBase.hpp.

template<class T>

static std::map<std::string, RCP<T> >& Teuchos::PerformanceMonitorBase< T >::counters ( )

inlinestaticprotected

Array of all counters that were created with getNewCounter() on the calling (MPI) process.