SAMRAI::tbox::TimerManager Class Reference

#include <source/toolbox/timers/TimerManager.h>

List of all members.

Public Member Functions
virtual Pointer< Timer >	getTimer (const std::string &name, bool ignore_timer_input=false)
virtual bool	checkTimerExists (Pointer< Timer > &timer, const std::string &name) const
virtual bool	checkTimerRunning (const std::string &name) const
virtual void	resetAllTimers ()
virtual void	print (std::ostream &os=plog)
Static Public Member Functions
static void	createManager (Pointer< Database > input_db)
static TimerManager *	getManager ()
static void	freeManager ()
Protected Member Functions
	TimerManager (Pointer< Database > input_db)
virtual	~TimerManager ()
void	registerSingletonSubclassInstance (TimerManager *subclass_instance)
virtual void	startTime (Timer *timer)
virtual void	stopTime (Timer *timer)
Friends
class	Timer

---

Detailed Description

Class TimerManager is a Singleton class that manages a list of timer objects to do performance analysis in SAMRAI library modules and application codes built with SAMRAI.

Typically, entries in the input file guide timer invocation and output generation. Within the source code, timer objects are retrieved as follows:

Pointer<Timer> name_timer = TimerManager::getManager->getTimer("name");

Here `name' is the name string identifier for the timer.

The input data is summarized as follows.

Required input keys: NONE

Optional input keys and defaults:

• print_exclusive (bool) Specifying whether to track and print exclusive times. Exclusive times are convenient for identifying time spent inside nested routines. Exclusive time is measured by turning off the parent timer when the timer in the nested routine is started. It then turns on the parent timer again once the nested timer is stopped. This option should be used with some discretion because the extra overhead to manage the nested list of timers is between four and seven times more expensive than doing simple start/stop operations (as is done with the print_total option). For this reason, we leave it off by default. [FALSE]

• print_total (bool) Specifies whether to print total (i.e. non-nested) time. This is the least expensive way to time parts of the code. The overhead associated with each start/stop sequence is about one-half a millionth of a second. [TRUE]

• print_wall (bool) Print wallclock time. [TRUE]

• print_user (bool) Print user time (measured by system clock). [FALSE]

• print_sys (bool) Print system time (measured by system clock). [FALSE]

• print_processor (bool) Print times measured on individual processors. [TRUE]

• print_summed (bool) Print time summed across all processors. [FALSE]

• print_max (bool) Print maximum time spent on any processor, and the processor ID that incurred the time. [FALSE]

• print_concurrent (bool) Prints the concurrent timer tree, as determined during exclusive timing. That is, for each timer, it prints the list of names of the timers in nested routines it calls. [FALSE]

• print_percentage (bool) Prints the percentage of total time with each timer. [TRUE]

• print_timer_overhead (bool) Prints some overhead stats associated with the timers. Information like the number of times a start/stop sequence was called for the timer, and the predicted overhead time associated with the timer. This is a convenient option to occasionally check to make sure the timers themselves are not affecting the performance of your calculation. [FALSE]

• print_threshold (double) Timers that use up less than (print_threshold) percent of the overall run time are not printed. This can be a convenient option to limit output if you have many timers invoked. [0.25]

• timer_list (string array) List of timers to be invoked. The timers can be listed individually in package::class::method format or the entries may contain wildcards to turn on a set of timers in a given package or class:

   *          timer_list = "pkg1::*::*", "pkg2::class2::*", ...
   *       

A sample input file entry might look like:

 *
 *    print_exclusive      = TRUE
 *    print_timer_overhead = TRUE
 *    timer_list = "algs::HyperbolicLevelIntegrator::advanceLevel()",
 *                 "mesh::GriddingAlgorithm::*",
 *                 "xfer::*::*"
 *
 * 

TimerManager expects timer names to be in a certain format to preserve the wildcard naming capability (i.e. to turn on entire package or class of timers). See the PDF document in /SAMRAI/docs/userdocs/timing.pdf for a discussion of how to add timers that maintain this format as well as a catalog of available timers currently implemented in the library.

Timing recursive function calls will yeild erroneous results and may lead to memory problems. We recommend {not to use timers to time recursive function calls}.

See also:

tbox::Timer

---

Constructor & Destructor Documentation

SAMRAI::tbox::TimerManager::TimerManager

(

Pointer< Database >

input_db

)

[protected]

The constructor for TimerManager is protected. Consistent with the definition of a Singleton class, only a timer manager object can have access to the constructor for the class.

SAMRAI::tbox::TimerManager::~TimerManager

(

)

[protected, virtual]

TimerManager is a Singleton class; its destructor is protected.

---

Member Function Documentation

void SAMRAI::tbox::TimerManager::createManager

(

Pointer< Database >

input_db

)

[static]

Create the singleton instance of the timer manager. If the input database pointer is null, no information will be read from the input file.

Generally, this routine should only be called once during program execution. If the timer manager has been previously created (e.g., by an earlier call to this routine) this routine will do nothing.

TimerManager * SAMRAI::tbox::TimerManager::getManager

(

)

[static]

Return a pointer to the singleton instance of the timer manager. All access to the TimerManager object is through the getManager() function. For example, to add a timer with the name "my_timer" to the timer manager, use the following call: TimerManager::getManager()->addTimer("my_timer").

void SAMRAI::tbox::TimerManager::freeManager

(

)

[static]

Deallocate the TimerManager instance. Note that it is not necessary to call freeManager() at program termination, since it is automatically called by the ShutdownRegistry class.

Pointer< Timer > SAMRAI::tbox::TimerManager::getTimer	(	const std::string &	name,
		bool	ignore_timer_input = false
	)			[virtual]

Return pointer to timer object with the given name string. If a timer with the given name already appears in the database of timers, the timer with that name will be returned. Otherwise, a new timer will be created with that name. Typically, only a timer specified (to be turned on) in the input file will be active. Timer names are parsed according to the input data parsing criteria (described at the top of this class header). One may override this functionality by adding the timer with a `true' argument. This argument allows one to override the input file criteria and turn the timer on anyway.

When assertion checking is active, an assertion will result if the string is empty.

bool SAMRAI::tbox::TimerManager::checkTimerExists	(	Pointer< Timer > &	timer,
		const std::string &	name
	)			const [virtual]

Return true if a timer whose name matches the argument string exists in the database of timers controlled by the manager. If a match is found, the timer pointer in the argument list is set to that timer. Otherwise, return false and return a null pointer. If the name string is empty, a null pointer is returned.

bool SAMRAI::tbox::TimerManager::checkTimerRunning

(

const std::string &

name

)

const [virtual]

Return true if a timer whose name matches the argument string exists in the database of timers and is currently running. Otherwise, return false.

void SAMRAI::tbox::TimerManager::resetAllTimers

(

)

[virtual]

Reset the times in all timers to zero.

void SAMRAI::tbox::TimerManager::print

(

std::ostream &

os = plog

)

[virtual]

Print the timing statistics to the specified output stream.

void SAMRAI::tbox::TimerManager::registerSingletonSubclassInstance

(

TimerManager *

subclass_instance

)

[protected]

Initialize Singleton instance with instance of subclass. This function is used to make the singleton object unique when inheriting from this base class.

void SAMRAI::tbox::TimerManager::startTime

(

Timer *

timer

)

[protected, virtual]

Mark given timer as running in timer database. If exclusive time option is set, start exclusive time for given timer. Also stop exclusive time for timer on top of exclusive timer stack and push given timer on to that stack.

When assertion checking is active, the timer pointer must be non-null.

void SAMRAI::tbox::TimerManager::stopTime

(

Timer *

timer

)

[protected, virtual]

Mark given timer as not running in timer database. If exclusive time option is set, stop exclusive time for given timer. Also, pop timer off top of exclusive timer stack and start exclusive timer for new top of stack timer.

When assertion checking is active, the timer pointer must be non-null.

---

Friends And Related Function Documentation

friend class Timer [friend]

---

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

• source/toolbox/timers/TimerManager.h
• source/toolbox/timers/TimerManager.C

---