MACSio  0.9
Multi-purpose, Application-Centric, Scalable I/O Proxy App
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
MACSIO_TIMING

Timing utilities. More...

Macros

#define MACSIO_TIMING_ITER_AUTO   -1
 Automatic iteration numbering Use for iter argument to StartTimer() when you don't want to manager iteration numbering of the timer explicitly. More...
 
#define MACSIO_TIMING_ITER_IGNORE   -2
 What is this? More...
 
#define MACSIO_TIMING_INVALID_TIMER   (~((MACSIO_TIMING_TimerId_t)0x0))
 Maybe returned from StartTimer() More...
 
#define MACSIO_TIMING_NO_GROUP   (((MACSIO_TIMING_GroupMask_t)0x0)
 Group mask when timer is not assigned to any group. More...
 
#define MACSIO_TIMING_ALL_GROUPS   (~((MACSIO_TIMING_GroupMask_t)0))
 Group mask representing all groups. More...
 
#define MT_Time   MACSIO_TIMING_GetCurrentTime
 Convenience macro for getting current time. More...
 
#define MT_StartTimer(LAB, GMASK, ITER)   MACSIO_TIMING_StartTimer(LAB, GMASK, ITER, __FILE__, __LINE__)
 Convenience macro for starting a timer. More...
 
#define MT_StopTimer(ID)   MACSIO_TIMING_StopTimer(ID)
 Convenience macro for stopping a timer. More...
 

Typedefs

typedef unsigned int MACSIO_TIMING_TimerId_t
 
typedef unsigned long long MACSIO_TIMING_GroupMask_t
 

Functions

MACSIO_TIMING_GroupMask_t MACSIO_TIMING_GroupMask (char const *grpName)
 Create a group name and mask. More...
 
MACSIO_TIMING_TimerId_t MACSIO_TIMING_StartTimer (char const *label, MACSIO_TIMING_GroupMask_t gmask, int iter_num, char const *file, int line)
 Create/Start a timer. More...
 
double MACSIO_TIMING_StopTimer (MACSIO_TIMING_TimerId_t id)
 Stop a timer. More...
 
double MACSIO_TIMING_GetTimer (MACSIO_TIMING_TimerId_t tid, char const *field)
 Get data from a specific timer. More...
 
double MACSIO_TIMING_GetReducedTimer (MACSIO_TIMING_TimerId_t tid, char const *field)
 Get data from a specific reduced timer. More...
 
void MACSIO_TIMING_DumpTimersToStrings (MACSIO_TIMING_GroupMask_t gmask, char ***strs, int *nstrs, int *maxlen)
 Dump timers to ascii strings. More...
 
void MACSIO_TIMING_ReduceTimers (MPI_Comm comm, int root)
 Reduce timers across MPI tasks. More...
 
void MACSIO_TIMING_DumpReducedTimersToStrings (MACSIO_TIMING_GroupMask_t gmask, char ***strs, int *nstrs, int *maxlen)
 Dump reduced timers to ascii strings. More...
 
void MACSIO_TIMING_ClearTimers (MACSIO_TIMING_GroupMask_t gmask)
 Clear a group of timers. More...
 
double MACSIO_TIMING_GetCurrentTime (void)
 Get current time. More...
 

Variables

int MACSIO_TIMING_UseMPI_Wtime
 Integer variable to control function used to get timer values. More...
 

Detailed Description

Timing utilities.

MACSIO_TIMING utilities support the creation of a number of timers to time different sections of code.

Timers are initialized/started with a user-defined label, and an optional group mask and iteration number. A hash of the timer is computed from its label and group combined with the source file name and line number. The resulting hash value is used to identify the timer.

Timers can be iterated and re-started. These are two different concepts. During iteration, the same timer can be used to time the same section of code as it gets executed multiple times. Each time represents a different iteration of the timer. The timer will keep track of the minimum time, maximum time, average time and variance of times over all iterations it is invoked. However, apart from these running statistics, a timer maintains no memory of past values. If a timer is iterated 10 times, it does not maintain knowledge of all 10 individual times. It maintains only knowledge of the running statistics; min, max, avg, var. The algorithm it uses to maintain these running statistics is the Knuth "online" algorithm.

Within any timer iteration, a timer can be stopped and restarted. If a timer is being used to time a block of code that involves some occasional and perhaps irrlevant alternative logic path, the timer can be stopped until execution returns from the alternative path. Then the timer can be restarted. This can only be done within a given iteration.

Timers can also be grouped into a small number of different classes. For example, it is possible to maintain a set of timers for MIF file I/O apart from a set of timers being used to time a particular plugin's operations to marshal a mesh or variable to/from persistent storage. Or, operations use to interact with filesystem metadata directly (e.g. mkdir(2), chdir(2), readir(2), etc.) can be maintained separately from timers used for entirely other purposes.

Finally, timers can be reduced across MPI ranks thereby creating a statistical summary of timer information across processors.

A timer is initialized/started by a call to MACSIO_TIMING_StartTimer() or the convenience macro MT_StartTimer(). This call returns the timer's ID which is used in a subsequent call to MACSIO_TIMING_StopTimer() to stop the timer.

MACSIO_TIMING_TimerId_t tid = MT_StartTimer("my timer", MACSIO_TIMING_GROUP_NONE, MACSIO_TIMING_ITER_AUTO);
...do some work here...
MT_StopTimer(tid);

In the above code, the call to MT_StartTimer starts a timer for a new (automatic) iteration. In this simple examle, we do not worry about timer group masks.

By default, MACSIO_TIMING uses MPI_Wtime but a caller can set MACSIO_TIMING_UseMPI_Wtime() to zero to instead use gettimeofday().

Macro Definition Documentation

#define MACSIO_TIMING_ITER_AUTO   -1

Automatic iteration numbering Use for iter argument to StartTimer() when you don't want to manager iteration numbering of the timer explicitly.

Definition at line 97 of file macsio_timing.h.

#define MACSIO_TIMING_ITER_IGNORE   -2

What is this?

Definition at line 103 of file macsio_timing.h.

#define MACSIO_TIMING_INVALID_TIMER   (~((MACSIO_TIMING_TimerId_t)0x0))

Maybe returned from StartTimer()

Definition at line 109 of file macsio_timing.h.

#define MACSIO_TIMING_NO_GROUP   (((MACSIO_TIMING_GroupMask_t)0x0)

Group mask when timer is not assigned to any group.

Definition at line 115 of file macsio_timing.h.

#define MACSIO_TIMING_ALL_GROUPS   (~((MACSIO_TIMING_GroupMask_t)0))

Group mask representing all groups.

Definition at line 121 of file macsio_timing.h.

#define MT_Time   MACSIO_TIMING_GetCurrentTime

Convenience macro for getting current time.

Definition at line 127 of file macsio_timing.h.

#define MT_StartTimer (   LAB,
  GMASK,
  ITER 
)    MACSIO_TIMING_StartTimer(LAB, GMASK, ITER, __FILE__, __LINE__)

Convenience macro for starting a timer.

Parameters
[in]LABUser defined timer label string
[in]GMASKUser defined group mask. Use MACSIO_TIMING_NO_GROUP if timer grouping is not needed.
[in]ITERThe iteration number. Use MACSIO_TIMING_ITER_IGNORE if timer iteration is not needed.

Definition at line 136 of file macsio_timing.h.

#define MT_StopTimer (   ID)    MACSIO_TIMING_StopTimer(ID)

Convenience macro for stopping a timer.

Parameters
[in]IDThe timer's hash id returned from a call to MT_StartTimer().

Definition at line 143 of file macsio_timing.h.

Typedef Documentation

typedef unsigned int MACSIO_TIMING_TimerId_t

Definition at line 145 of file macsio_timing.h.

typedef unsigned long long MACSIO_TIMING_GroupMask_t

Definition at line 146 of file macsio_timing.h.

Function Documentation

MACSIO_TIMING_GroupMask_t MACSIO_TIMING_GroupMask ( char const *  grpName)

Create a group name and mask.

A small number of groups (less than 64) can be defined into which timers can be grouped Timers can be assigned to multiple groups by or'ing the resulting group masks.

Parameters
grpNameName of the group for which group mask is needed

Definition at line 163 of file macsio_timing.c.

MACSIO_TIMING_TimerId_t MACSIO_TIMING_StartTimer ( char const *  label,
MACSIO_TIMING_GroupMask_t  gmask,
int  iter_num,
char const *  file,
int  line 
)

Create/Start a timer.

This call either creates a new timer and starts it or starts a new iteration of an existing timer.

Returns
A hash derived from a string catenation the label, gmask, file and line.
Parameters
labelUser defined label to be assigned to the timer
gmaskMask to indicate the timer's group membership
iter_numIteration number
fileThe source file name
lineThe source file line number

Definition at line 202 of file macsio_timing.c.

double MACSIO_TIMING_StopTimer ( MACSIO_TIMING_TimerId_t  id)

Stop a timer.

This call stops a currently running timer.

Returns
Returns the time for the current iteration of the timer
Parameters
idThe timer's ID, returned from a call to StartTimer

Definition at line 279 of file macsio_timing.c.

double MACSIO_TIMING_GetTimer ( MACSIO_TIMING_TimerId_t  tid,
char const *  field 
)

Get data from a specific timer.

For field names, see definition of timerInfo_t

Parameters
tidThe timer's ID, returned from a call to StartTimer
fieldThe name of the field from the timer to return

Definition at line 366 of file macsio_timing.c.

double MACSIO_TIMING_GetReducedTimer ( MACSIO_TIMING_TimerId_t  tid,
char const *  field 
)

Get data from a specific reduced timer.

Parameters
tidThe timer's ID, returned from a call to StartTimer
fieldThe name of the field from the timer to return

Definition at line 371 of file macsio_timing.c.

void MACSIO_TIMING_DumpTimersToStrings ( MACSIO_TIMING_GroupMask_t  gmask,
char ***  strs,
int *  nstrs,
int *  maxlen 
)

Dump timers to ascii strings.

This call will find all used timers in the hash table matching the specified gmask group mask and dumps each timer to a string. For convenience, the maximum length of the strings is also returned. This is to facilitate dumping the strings to a MACSIO_LOG.

Parameters
gmaskGroup mask to filter only timers belonging to specific groups
strsAn array of strings, one for each timer, returned to caller. Caller is responsible for freeing
nstrsNumber of strings returned to caller
maxlenThe maximum length of all strings

Definition at line 639 of file macsio_timing.c.

void MACSIO_TIMING_ReduceTimers ( MPI_Comm  comm,
int  root 
)

Reduce timers across MPI tasks.

Computes a parallel reduction across MPI tasks of all timers.

Parameters
commThe MPI communicator to use for the reduction
rootThe MPI rank of the root task to be used for the reduction

Definition at line 499 of file macsio_timing.c.

void MACSIO_TIMING_DumpReducedTimersToStrings ( MACSIO_TIMING_GroupMask_t  gmask,
char ***  strs,
int *  nstrs,
int *  maxlen 
)

Dump reduced timers to ascii strings.

Similar to DumpTimersToStrings except this call dumps reduced timers

Parameters
gmaskGroup mask to filter only timers belonging to specific groups
strsAn array of strings, one for each timer, returned to caller. Caller is responsible for freeing
nstrsNumber of strings returned to caller
maxlenThe maximum length of all strings

Definition at line 649 of file macsio_timing.c.

void MACSIO_TIMING_ClearTimers ( MACSIO_TIMING_GroupMask_t  gmask)

Clear a group of timers.

Clears and resets timers of specified group

Parameters
gmaskGroup mask to filter only timers belonging to specific groups

Definition at line 659 of file macsio_timing.c.

double MACSIO_TIMING_GetCurrentTime ( void  )

Get current time.

Definition at line 665 of file macsio_timing.c.

Variable Documentation

int MACSIO_TIMING_UseMPI_Wtime

Integer variable to control function used to get timer values.

A non-zero value indicates that MACSIO_TIMING should use MPI_Wtime. Otherwise, it will use gettimeofday().

Definition at line 44 of file macsio_timing.c.