Teuchos Package Browser (Single Doxygen Collection)  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Classes | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
Teuchos::StackedTimer Class Reference

This class allows one to push and pop timers on and off a stack. More...

#include <Teuchos_StackedTimer.hpp>

Classes

struct  AlignmentWidths
 Stores the column widths for output alignment. More...
 
class  LevelTimer
 Timer info at a given level and all the children. More...
 
struct  OutputOptions
 

Public Member Functions

 StackedTimer (const char *name, const bool start_base_timer=true)
 
void startBaseTimer ()
 
void stopBaseTimer ()
 
void start (const std::string name, const bool push_kokkos_profiling_region=true)
 
void stop (const std::string &name, const bool pop_kokkos_profiling_region=true)
 
void incrementUpdates (const long long i=1)
 
double accumulatedTime (const std::string &name="")
 
double accumulatedTimePerUpdate (const std::string &name="")
 
double accumulatedTimePerTimerCall (const std::string &name="")
 
const BaseTimerfindBaseTimer (const std::string &name) const
 
BaseTimer::TimeInfo findTimer (const std::string &name)
 
void report (std::ostream &os)
 
void report (std::ostream &os, Teuchos::RCP< const Teuchos::Comm< int > > comm, OutputOptions options=OutputOptions())
 
void reportXML (std::ostream &os, const std::string &datestamp, const std::string &timestamp, Teuchos::RCP< const Teuchos::Comm< int > > comm)
 
std::string reportWatchrXML (const std::string &name, Teuchos::RCP< const Teuchos::Comm< int > > comm)
 
void enableVerbose (const bool enable_verbose)
 If set to true, print timer start/stop to verbose ostream. More...
 
void enableVerboseTimestamps (const unsigned levels)
 Enable timestamps in verbose mode for the number of levels specified. More...
 
void setVerboseOstream (const Teuchos::RCP< std::ostream > &os)
 Set the ostream for verbose mode(defaults to std::cout). More...
 
void disableTimers ()
 
void enableTimers ()
 

Protected Member Functions

void flatten ()
 
void merge (Teuchos::RCP< const Teuchos::Comm< int > > comm)
 
void collectRemoteData (Teuchos::RCP< const Teuchos::Comm< int > > comm, const OutputOptions &options)
 
double computeColumnWidthsForAligment (std::string prefix, int print_level, std::vector< bool > &printed, double parent_time, const OutputOptions &options)
 
double printLevel (std::string prefix, int level, std::ostream &os, std::vector< bool > &printed, double parent_time, const OutputOptions &options)
 
double printLevelXML (std::string prefix, int level, std::ostream &os, std::vector< bool > &printed, double parent_time, const std::string &rootName="")
 

Protected Attributes

LevelTimertop_
 Current level running. More...
 
LevelTimer timer_
 Base timer. More...
 
Array< std::string > flat_names_
 
Array< double > min_
 
Array< double > max_
 
Array< int > procmin_
 
Array< int > procmax_
 
Array< double > sum_
 
Array< double > sum_sq_
 
Array< Array< int > > hist_
 
Array< unsigned long > count_
 
Array< unsigned long long > updates_
 
Array< int > active_
 
struct
Teuchos::StackedTimer::AlignmentWidths 
alignments_
 
bool enable_verbose_
 If set to true, prints to the debug ostream. At construction, default value is set from environment variable. More...
 
unsigned verbose_timestamp_levels_
 If set to a value greater than 0, verbose mode will print that many levels of timers with timestamps. A value of zero disables timestamps. More...
 
Teuchos::RCP< std::ostream > verbose_ostream_
 For debugging, this is the ostream used for printing. More...
 
bool enable_timers_
 Used to disable timers for asynchronous work. More...
 

Detailed Description

This class allows one to push and pop timers on and off a stack.

To use this class one would do something like this

StackedTimer timer(); // construct top level timer timer.start("some comp"); do_work(); timer.start("sub comp"); more_work(); timer.stop(); // stopping sub comp timer.stop(); // stopping comp

timer.stop(); // stopping all timer stuff timer.report(std::cout); // dump to screen

Definition at line 221 of file Teuchos_StackedTimer.hpp.

Constructor & Destructor Documentation

Teuchos::StackedTimer::StackedTimer ( const char *  name,
const bool  start_base_timer = true 
)
inlineexplicit

Construct a stacked timer

Parameters
[in]nameTop level name of the timer
[in]start_top_timerAutomatically start the top level timer. If set to false, the user will have to start it manually.

Definition at line 472 of file Teuchos_StackedTimer.hpp.

Member Function Documentation

void Teuchos::StackedTimer::startBaseTimer ( )
inline

Start the base level timer only

Definition at line 496 of file Teuchos_StackedTimer.hpp.

void Teuchos::StackedTimer::stopBaseTimer ( )
inline

Stop the base level timer only

Definition at line 506 of file Teuchos_StackedTimer.hpp.

void Teuchos::StackedTimer::start ( const std::string  name,
const bool  push_kokkos_profiling_region = true 
)
inline

Start a sublevel timer

Parameters
[in]nameName of the timer you wish to start
[in]push_kokkos_profiling_regionOptional parameter that if set to true, will pushRegion() in kokkos profiling for this timer. The TimeMonitor will always set this to false since it does its own pushRegion() in the Timer object (this prevents double registering with kokkos).

Definition at line 518 of file Teuchos_StackedTimer.hpp.

void Teuchos::StackedTimer::stop ( const std::string &  name,
const bool  pop_kokkos_profiling_region = true 
)
inline

Stop the current top running timer, should be called for the root timer prior to final output

Parameters
[in]nameName of the timer you wish to stop
[in]pop_kokkos_profiling_regionOptional parameter that if set to true, will popRegion() in kokkos profiling for this timer. The TimeMonitor will always set this to false since it does its own pushRegion() in the Timer object (this prevents double registering with kokkos).

Definition at line 557 of file Teuchos_StackedTimer.hpp.

void Teuchos::StackedTimer::incrementUpdates ( const long long  i = 1)
inline

Increment the iteration count for the running timer

Parameters
[in]iamount to increment the count

Definition at line 596 of file Teuchos_StackedTimer.hpp.

double Teuchos::StackedTimer::accumulatedTime ( const std::string &  name = "")
inline

Return the accumulated time the named timer has, if name is blank top level timer

Parameters
[in]nameName of the timer to output
Returns
amount of time in seconds

Definition at line 605 of file Teuchos_StackedTimer.hpp.

double Teuchos::StackedTimer::accumulatedTimePerUpdate ( const std::string &  name = "")
inline

Return the time spent per update at a given level

Parameters
[in]namename of subtimer, if blank return current level time
Returns
time in seconds per update at provided level

Definition at line 617 of file Teuchos_StackedTimer.hpp.

double Teuchos::StackedTimer::accumulatedTimePerTimerCall ( const std::string &  name = "")
inline

Return the time spent per timer start/stop at a given level

Parameters
[in]namename of subtimer, if blank return current level time
Returns
time in seconds per start/stop call at provided level

Definition at line 628 of file Teuchos_StackedTimer.hpp.

const BaseTimer* Teuchos::StackedTimer::findBaseTimer ( const std::string &  name) const
inline

Return pointer to the BaseTimer corresponding to a given string (full string name)

Parameters
nameinput string to search for
Returns
BaseTimer

Definition at line 640 of file Teuchos_StackedTimer.hpp.

BaseTimer::TimeInfo Teuchos::StackedTimer::findTimer ( const std::string &  name)
inline

Return the time info for a given string (full string name)

Parameters
nameinput string to search for
Returns
Time data

Definition at line 652 of file Teuchos_StackedTimer.hpp.

void Teuchos::StackedTimer::report ( std::ostream &  os)
inline

Definition at line 660 of file Teuchos_StackedTimer.hpp.

void Teuchos::StackedTimer::report ( std::ostream &  os,
Teuchos::RCP< const Teuchos::Comm< int > >  comm,
OutputOptions  options = OutputOptions() 
)

Dump all the data from all the MPI ranks to an ostream

Parameters
[in,out]os- Output stream
[in]comm- Teuchos comm pointer

Definition at line 694 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::reportXML ( std::ostream &  os,
const std::string &  datestamp,
const std::string &  timestamp,
Teuchos::RCP< const Teuchos::Comm< int > >  comm 
)

Dump all the data from all the MPI ranks to the given output stream, in Watchr XML format. reportWatchrXML() is a wrapper for this function that creates os as a std::ofstream.

Parameters
[in,out]os- stream where XML will be written
[in]datestamp- UTC datestamp in the format YYYY_MM_DD
[in]timestamp- UTC timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SS (HH in 24-hour time, and T is just the character 'T')
[in]comm- Teuchos comm pointer
Returns
The complete filename, or empty string if no output was produced.

Definition at line 728 of file Teuchos_StackedTimer.cpp.

std::string Teuchos::StackedTimer::reportWatchrXML ( const std::string &  name,
Teuchos::RCP< const Teuchos::Comm< int > >  comm 
)

Dump all the data from all the MPI ranks to an XML file. This function calls reportXML and is intended to be used directly by performance tests.

In the XML report, the top-level timer name (representing the total) will be replaced with name (the name of the test). This becomes the top-level chart name in Watchr.

The output filename is controlled by two environment variables: $WATCHR_PERF_DIR (required for output) and $WATCHR_BUILD_NAME (optional). $WATCHR_PERF_DIR is the directory where the output file will be created. If it is not set or is empty, no output will be produced and the function returns an empty string on all ranks.

If $WATCHR_BUILD_NAME is set, the filename is $WATCHR_BUILD_NAME-name_$DATESTAMP.xml. Additionally, the build name is prepended (verbatim) to the the top-level chart name, so that Watchr knows it is a different data series than runs of the same test from other builds.

If $WATCHR_BUILD_NAME is not set or is empty, the filename is just name_$DATESTAMP.xml . DATESTAMP is calculated from the current UTC time, in the format YYYY_MM_DD.

In the filename, all spaces in will be replaced by underscores.

Parameters
[in]name- Name of performance test
[in]comm- Teuchos comm pointer
Returns
If on rank 0 and output was produced, the complete output filename. Otherwise the empty string.

Definition at line 744 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::enableVerbose ( const bool  enable_verbose)

If set to true, print timer start/stop to verbose ostream.

Definition at line 816 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::enableVerboseTimestamps ( const unsigned  levels)

Enable timestamps in verbose mode for the number of levels specified.

Definition at line 819 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::setVerboseOstream ( const Teuchos::RCP< std::ostream > &  os)

Set the ostream for verbose mode(defaults to std::cout).

Definition at line 822 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::disableTimers ( )

Once called, the start and stop calls are no-ops. Used to stop timers during asynchronous execution.

Definition at line 825 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::enableTimers ( )

Once called, the start and stop calls are reenabled. Used to restart timers after a call to disableTimers().

Definition at line 828 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::flatten ( )
protected

Flatten the timers into a single array

Definition at line 118 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::merge ( Teuchos::RCP< const Teuchos::Comm< int > >  comm)
protected

Merge all the timers together into a single structure

Parameters
[in]comm- Communicator to use

Definition at line 126 of file Teuchos_StackedTimer.cpp.

void Teuchos::StackedTimer::collectRemoteData ( Teuchos::RCP< const Teuchos::Comm< int > >  comm,
const OutputOptions options 
)
protected

Migrate all the timer data to rank=0 if parallel

Definition at line 133 of file Teuchos_StackedTimer.cpp.

double Teuchos::StackedTimer::computeColumnWidthsForAligment ( std::string  prefix,
int  print_level,
std::vector< bool > &  printed,
double  parent_time,
const OutputOptions options 
)
protected

Compute the column widths to align the output from report() in columns.

Returns
total time for this level

Definition at line 257 of file Teuchos_StackedTimer.cpp.

double Teuchos::StackedTimer::printLevel ( std::string  prefix,
int  level,
std::ostream &  os,
std::vector< bool > &  printed,
double  parent_time,
const OutputOptions options 
)
protected

Recursive call to print a level of timer data.

Definition at line 396 of file Teuchos_StackedTimer.cpp.

double Teuchos::StackedTimer::printLevelXML ( std::string  prefix,
int  level,
std::ostream &  os,
std::vector< bool > &  printed,
double  parent_time,
const std::string &  rootName = "" 
)
protected

Recursive call to print a level of timer data, in Watchr XML format. If non-empty, rootName will replace the root level's timer name in the output. If empty or level > 0, it has no effect.

Definition at line 637 of file Teuchos_StackedTimer.cpp.

Member Data Documentation

LevelTimer* Teuchos::StackedTimer::top_
protected

Current level running.

Definition at line 760 of file Teuchos_StackedTimer.hpp.

LevelTimer Teuchos::StackedTimer::timer_
protected

Base timer.

Definition at line 762 of file Teuchos_StackedTimer.hpp.

Array<std::string> Teuchos::StackedTimer::flat_names_
protected

Definition at line 764 of file Teuchos_StackedTimer.hpp.

Array<double> Teuchos::StackedTimer::min_
protected

Definition at line 765 of file Teuchos_StackedTimer.hpp.

Array<double> Teuchos::StackedTimer::max_
protected

Definition at line 766 of file Teuchos_StackedTimer.hpp.

Array<int> Teuchos::StackedTimer::procmin_
protected

Definition at line 767 of file Teuchos_StackedTimer.hpp.

Array<int> Teuchos::StackedTimer::procmax_
protected

Definition at line 768 of file Teuchos_StackedTimer.hpp.

Array<double> Teuchos::StackedTimer::sum_
protected

Definition at line 769 of file Teuchos_StackedTimer.hpp.

Array<double> Teuchos::StackedTimer::sum_sq_
protected

Definition at line 770 of file Teuchos_StackedTimer.hpp.

Array<Array<int> > Teuchos::StackedTimer::hist_
protected

Definition at line 771 of file Teuchos_StackedTimer.hpp.

Array<unsigned long> Teuchos::StackedTimer::count_
protected

Definition at line 772 of file Teuchos_StackedTimer.hpp.

Array<unsigned long long> Teuchos::StackedTimer::updates_
protected

Definition at line 773 of file Teuchos_StackedTimer.hpp.

Array<int> Teuchos::StackedTimer::active_
protected

Definition at line 774 of file Teuchos_StackedTimer.hpp.

struct Teuchos::StackedTimer::AlignmentWidths Teuchos::StackedTimer::alignments_
protected
bool Teuchos::StackedTimer::enable_verbose_
protected

If set to true, prints to the debug ostream. At construction, default value is set from environment variable.

Definition at line 803 of file Teuchos_StackedTimer.hpp.

unsigned Teuchos::StackedTimer::verbose_timestamp_levels_
protected

If set to a value greater than 0, verbose mode will print that many levels of timers with timestamps. A value of zero disables timestamps.

Definition at line 806 of file Teuchos_StackedTimer.hpp.

Teuchos::RCP<std::ostream> Teuchos::StackedTimer::verbose_ostream_
protected

For debugging, this is the ostream used for printing.

Definition at line 809 of file Teuchos_StackedTimer.hpp.

bool Teuchos::StackedTimer::enable_timers_
protected

Used to disable timers for asynchronous work.

Definition at line 812 of file Teuchos_StackedTimer.hpp.


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