Performance Timer Utilities

Performance Timer - Initialization and Timer Demarcation:
The following routines provide support for defining one or more wall-clock timers around specific code regions. Individual timers are delineated by a unique id. In addition to timing specific code regions identified with begin/end calls, the library also tracks the total application time from when the timing library was first initialized.
void	grvy_timer_init (const char *description)
void	grvy_timer_begin (const char *id)
void	grvy_timer_end (const char *id)
void	grvy_timer_reset ()
void	grvy_timer_finalize ()
double	grvy_timer ()

Performance Timer - Global Timing Summary:
The following routines are useful for summarizing the measured performance timings for all defined timers and the global runtime.
double	grvy_timer_elapsed_global ()
void	grvy_timer_summarize ()
int	grvy_timer_set_summarize_width (const int maxwidth)

Performance Timer - Individual Timer Query Tools (exclusive timings):
The following routines allow for the querying of defined performance timers. Note that, except for the global timer, these routines provide exclusive timing measurements (ie. they do not include runtime contributions from any embedded timers).
double	grvy_timer_elapsedseconds (const char *id)
double	grvy_timer_stats_mean (const char *id)
double	grvy_timer_stats_variance (const char *id)
double	grvy_timer_stats_min (const char *id)
double	grvy_timer_stats_max (const char *id)
int	grvy_timer_stats_count (const char *id)

Performance Timer - Individual Timer Query Tools (inclusive timings):
The following routines also allow for the querying of defined performance timers. These are similar to the timing utilities above, except these versions provide inclusive timing measurements (ie. they provide wallclock measurements between the begin/end of each timer, including the time associated with any embedded timers).
double	grvy_timer_elapsedseconds_inc (const char *id)
double	grvy_timer_stats_mean_inc (const char *id)
double	grvy_timer_stats_variance_inc (const char *id)
double	grvy_timer_stats_min_inc (const char *id)
double	grvy_timer_stats_max_inc (const char *id)

Performance Timing - Historical Logging:
These routines provide support to store measured runtime performance into an HDF5 file for logging purposes (this functionality requires HDF5 library linkage during the libGRVY configuration phase). Results are stored on a per-machine basis and are appended to the HDF5 file with timestamps to document historical performance over time. Stored results can be retrieved using the API below or via standalone executables installed with libGRVY. There are two primary modes for saving historical performance data: Mode 1: you are using the grvy_timer_* class of routines to define individual sections to monitor and want to save the global runtime measurement along with all individually defined subtimers. Mode 2: you are using other means to profile the application code and want to save a single global timing value. Routines for this mode are distinguished by the presence of an extra "timing" argument in the calling sequence. In both modes, standard and expanded (exp) calling sequences are supported with the expanded version allowing additional optional runtime documentation (e.g. flops, code revision) to be provided.
int	grvy_timer_save_hist (const char *experiment_name, const char *comment, int num_procs, const char *filename)
int	grvy_timer_save_hist_exp (const char *experiment_name, const char *comment, int num_procs, int jobId, const char *code_revision, double flops, const char *filename)
int	grvy_timer_save_hist_ext (double timing, const char *machinename, const char *experiment, const char *comment, int num_procs, const char *filename)
int	grvy_timer_save_hist_ext_exp (double timing, const char *machinename, const char *experiment, const char *comment, int num_procs, int jobId, const char *code_revision, double flops, const char *filename)
void	grvy_summarize_hist_timing (const char *filename, const char *delimiter, const char *outdir)

Detailed Description

This section presents available C routines for measuring runtime performance of specific code sections to aid in overall performance/statistical analysis, and to maintain historical performance records as application codes evolve or across alternate compute platforms. Individual code timers are defined based on begin/end demarcation around the desired code snippet to measure along with a unique user-provided id string. Note that individual timers can be nested and the library will report exclusive timing of the innermost timers. Various options are provided to interrogate timer measurements, statistics, and relative timer comparisons. A convenient use of these routines is to define timers around various important work constructs within your application and use the grvy_timer_summarize() function to obtain a concise summary of the runtime performance, variability, and relative wallclock comparisions. Example output using this approach is shown below:

-----------------------------------------------------------------------------------------------
GRVY Example Timing - Performance Timings:              |      Mean      Variance       Count
--> foo                 : 3.00978e+00 secs ( 64.0889 %) | [3.00978e-01  2.70727e-08         10]
--> boo                 : 1.17648e+00 secs ( 25.0513 %) | [1.17648e-01  2.35981e-08         10]
--> bar                 : 5.09513e-01 secs ( 10.8493 %) | [5.09513e-02  5.02795e-08         10]
--> Main Program        : 4.48704e-04 secs (  0.0096 %) | [4.48704e-04  0.00000e+00          1]
--> GRVY_Unassigned     : 4.02927e-05 secs (  0.0009 %)
 
    Total Measured Time = 4.69626e+00 secs (100.0000 %)
-----------------------------------------------------------------------------------------------

Code Example: A specific C example using the performance timing routines is available in timer.c.

---

Function Documentation

grvy_timer()

double grvy_timer

(

)

Basic wallclock timer which provides the time since epoch in seconds.

Returns

time since epoch in seconds