SAMRAI::tbox::TimerManager Class Reference

#include <tbox/TimerManager.h>

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)

Private Member Functions
bool	checkTimerExistsInArray (Pointer< Timer > &timer, const std::string &name, const Array< Pointer< Timer > > &timer_array, int array_size) const
void	printTable (const std::string &table_title, const Array< std::string > column_titles, const Array< std::string > timer_names, const int column_ids[], const double timer_values[][18], std::ostream &os)
void	printTable (const std::string &table_title, const Array< std::string > column_titles, const Array< std::string > timer_names, const int max_processor_id[][2], const int max_array_id, const int column_ids[], const double timer_values[][18], std::ostream &os)
void	printOverhead (const Array< std::string > timer_names, const double timer_values[][18], std::ostream &os)
void	printConcurrent (std::ostream &os)
void	buildTimerArrays (double timer_values[][18], int max_processor_id[][2], Array< std::string > timer_names)
void	buildOrderedList (const double timer_values[][18], const int column, int index[], const int array_size)
bool	checkTimerInNameLists (const std::string &name)
void	checkConsistencyAcrossProcessors ()
void	getFromInput (Pointer< Database > input_db)
void	addTimerToNameLists (const std::string &name)
void	computeOverheadConstants (void)
double	computeOverheadConstantActiveOrInactive (bool active)
void	clearArrays (void)
int	getMaximumNumberOfTimers ()
void	setMaximumNumberOfTimers (const int size)

Static Private Member Functions
static void	quicksort (const Array< double > &a, int index[], int lo, int hi)
static int	computePercentageInt (const double frac, const double tot)
static double	computePercentageDouble (const double frac, const double tot)

Private Attributes
double	d_timer_active_access_time
double	d_timer_inactive_access_time
Pointer< Timer >	d_main_timer
int	d_num_timers
Array< Pointer< Timer > >	d_timers
int	d_num_inactive_timers
Array< Pointer< Timer > >	d_inactive_timers
tbox::Array< bool >	d_running_timers
List< Timer * >	d_exclusive_timer_stack
List< std::string >	d_package_names
List< std::string >	d_class_names
List< std::string >	d_class_method_names
std::set< std::string >	d_all_active_timer_names
int	d_length_package_names
int	d_length_class_names
int	d_length_class_method_names
double	d_print_threshold
bool	d_print_exclusive
bool	d_print_total
bool	d_print_processor
bool	d_print_max
bool	d_print_summed
bool	d_print_user
bool	d_print_sys
bool	d_print_wall
bool	d_print_percentage
bool	d_print_concurrent
bool	d_print_timer_overhead

Static Private Attributes
static TimerManager *	s_timer_manager_instance
static bool	s_registered_callback
static int	s_main_timer_identifier
static int	s_inactive_timer_identifier
static const int	DEFAULT_NUMBER_OF_TIMERS_INCREMENT = 128

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

TimerManager()

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.

~TimerManager()

virtual SAMRAI::tbox::TimerManager::~TimerManager ( )

protectedvirtual

TimerManager is a Singleton class; its destructor is protected.

Member Function Documentation

createManager()

static 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.

getManager()

static 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").

freeManager()

static 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.

getTimer()

virtual 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.

checkTimerExists()

virtual 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.

checkTimerRunning()

virtual 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.

resetAllTimers()

virtual void SAMRAI::tbox::TimerManager::resetAllTimers ( )

virtual

Reset the times in all timers to zero.

print()

virtual void SAMRAI::tbox::TimerManager::print ( std::ostream &  os = plog )

virtual

Print the timing statistics to the specified output stream.

registerSingletonSubclassInstance()

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.

startTime()

virtual void SAMRAI::tbox::TimerManager::startTime ( Timer *  timer )

protectedvirtual

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.

stopTime()

virtual void SAMRAI::tbox::TimerManager::stopTime ( Timer *  timer )

protectedvirtual

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.

checkTimerExistsInArray()

bool SAMRAI::tbox::TimerManager::checkTimerExistsInArray ( Pointer< Timer > &  timer, const std::string &  name, const Array< Pointer< Timer > > &  timer_array, int  array_size  ) const

private

printTable() [1/2]

void SAMRAI::tbox::TimerManager::printTable ( const std::string &  table_title, const Array< std::string >  column_titles, const Array< std::string >  timer_names, const int  column_ids[], const double  timer_values[][18], std::ostream &  os  )

private

printTable() [2/2]

void SAMRAI::tbox::TimerManager::printTable ( const std::string &  table_title, const Array< std::string >  column_titles, const Array< std::string >  timer_names, const int  max_processor_id[][2], const int  max_array_id, const int  column_ids[], const double  timer_values[][18], std::ostream &  os  )

private

printOverhead()

void SAMRAI::tbox::TimerManager::printOverhead ( const Array< std::string >  timer_names, const double  timer_values[][18], std::ostream &  os  )

private

printConcurrent()

void SAMRAI::tbox::TimerManager::printConcurrent ( std::ostream &  os )

private

buildTimerArrays()

void SAMRAI::tbox::TimerManager::buildTimerArrays ( double  timer_values[][18], int  max_processor_id[][2], Array< std::string >  timer_names  )

private

buildOrderedList()

void SAMRAI::tbox::TimerManager::buildOrderedList ( const double  timer_values[][18], const int  column, int  index[], const int  array_size  )

private

checkTimerInNameLists()

bool SAMRAI::tbox::TimerManager::checkTimerInNameLists ( const std::string &  name )

private

checkConsistencyAcrossProcessors()

void SAMRAI::tbox::TimerManager::checkConsistencyAcrossProcessors ( )

private

getFromInput()

void SAMRAI::tbox::TimerManager::getFromInput ( Pointer< Database >  input_db )

private

addTimerToNameLists()

void SAMRAI::tbox::TimerManager::addTimerToNameLists ( const std::string &  name )

private

quicksort()

static void SAMRAI::tbox::TimerManager::quicksort ( const Array< double > &  a, int  index[], int  lo, int  hi  )

staticprivate

computePercentageInt()

static int SAMRAI::tbox::TimerManager::computePercentageInt ( const double  frac, const double  tot  )

staticprivate

computePercentageDouble()

static double SAMRAI::tbox::TimerManager::computePercentageDouble ( const double  frac, const double  tot  )

staticprivate

computeOverheadConstants()

void SAMRAI::tbox::TimerManager::computeOverheadConstants ( void  )

private

computeOverheadConstantActiveOrInactive()

double SAMRAI::tbox::TimerManager::computeOverheadConstantActiveOrInactive ( bool  active )

private

clearArrays()

void SAMRAI::tbox::TimerManager::clearArrays ( void  )

private

getMaximumNumberOfTimers()

int SAMRAI::tbox::TimerManager::getMaximumNumberOfTimers ( )

private

setMaximumNumberOfTimers()

void SAMRAI::tbox::TimerManager::setMaximumNumberOfTimers ( const int  size )

private

Friends And Related Function Documentation

Timer

friend class Timer

friend

Member Data Documentation

s_timer_manager_instance

TimerManager* SAMRAI::tbox::TimerManager::s_timer_manager_instance

staticprivate

s_registered_callback

bool SAMRAI::tbox::TimerManager::s_registered_callback

staticprivate

s_main_timer_identifier

int SAMRAI::tbox::TimerManager::s_main_timer_identifier

staticprivate

s_inactive_timer_identifier

int SAMRAI::tbox::TimerManager::s_inactive_timer_identifier

staticprivate

d_timer_active_access_time

double SAMRAI::tbox::TimerManager::d_timer_active_access_time

private

d_timer_inactive_access_time

double SAMRAI::tbox::TimerManager::d_timer_inactive_access_time

private

d_main_timer

Pointer<Timer> SAMRAI::tbox::TimerManager::d_main_timer

private

d_num_timers

int SAMRAI::tbox::TimerManager::d_num_timers

private

d_timers

Array< Pointer<Timer> > SAMRAI::tbox::TimerManager::d_timers

private

d_num_inactive_timers

int SAMRAI::tbox::TimerManager::d_num_inactive_timers

private

d_inactive_timers

Array< Pointer<Timer> > SAMRAI::tbox::TimerManager::d_inactive_timers

private

d_running_timers

tbox::Array<bool> SAMRAI::tbox::TimerManager::d_running_timers

private

d_exclusive_timer_stack

List< Timer* > SAMRAI::tbox::TimerManager::d_exclusive_timer_stack

private

d_package_names

List<std::string> SAMRAI::tbox::TimerManager::d_package_names

private

d_class_names

List<std::string> SAMRAI::tbox::TimerManager::d_class_names

private

d_class_method_names

List<std::string> SAMRAI::tbox::TimerManager::d_class_method_names

private

d_all_active_timer_names

std::set<std::string> SAMRAI::tbox::TimerManager::d_all_active_timer_names

private

Set of all enabled timers. Used to quickly determine whether or not a timer has already been enabled.

d_length_package_names

int SAMRAI::tbox::TimerManager::d_length_package_names

private

d_length_class_names

int SAMRAI::tbox::TimerManager::d_length_class_names

private

d_length_class_method_names

int SAMRAI::tbox::TimerManager::d_length_class_method_names

private

d_print_threshold

double SAMRAI::tbox::TimerManager::d_print_threshold

private

d_print_exclusive

bool SAMRAI::tbox::TimerManager::d_print_exclusive

private

d_print_total

bool SAMRAI::tbox::TimerManager::d_print_total

private

d_print_processor

bool SAMRAI::tbox::TimerManager::d_print_processor

private

d_print_max

bool SAMRAI::tbox::TimerManager::d_print_max

private

d_print_summed

bool SAMRAI::tbox::TimerManager::d_print_summed

private

d_print_user

bool SAMRAI::tbox::TimerManager::d_print_user

private

d_print_sys

bool SAMRAI::tbox::TimerManager::d_print_sys

private

d_print_wall

bool SAMRAI::tbox::TimerManager::d_print_wall

private

d_print_percentage

bool SAMRAI::tbox::TimerManager::d_print_percentage

private

d_print_concurrent

bool SAMRAI::tbox::TimerManager::d_print_concurrent

private

d_print_timer_overhead

bool SAMRAI::tbox::TimerManager::d_print_timer_overhead

private

DEFAULT_NUMBER_OF_TIMERS_INCREMENT

const int SAMRAI::tbox::TimerManager::DEFAULT_NUMBER_OF_TIMERS_INCREMENT = 128

staticprivate

---

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

• /samrai/include/tbox/TimerManager.h