LLVM OpenMP* Runtime Library
Macros | Enumerations
Statistics Gathering from OMPTB

Macros

#define KMP_FOREACH_COUNTER(macro, arg)
 Add new counters under KMP_FOREACH_COUNTER() macro in kmp_stats.h. More...
 
#define KMP_FOREACH_EXPLICIT_TIMER(macro, arg)   KMP_FOREACH_TIMER(macro, arg)
 Add new explicit timers under KMP_FOREACH_EXPLICIT_TIMER() macro. More...
 
#define KMP_TIME_BLOCK(name)   blockTimer __BLOCKTIME__(__kmp_stats_thread_ptr->getTimer(TIMER_##name), TIMER_##name)
 Uses specified timer (name) to time code block. More...
 
#define KMP_COUNT_VALUE(name, value)   __kmp_stats_thread_ptr->getTimer(TIMER_##name)->addSample(value)
 Adds value to specified timer (name). More...
 
#define KMP_COUNT_BLOCK(name)   __kmp_stats_thread_ptr->getCounter(COUNTER_##name)->increment()
 Increments specified counter (name). More...
 
#define KMP_START_EXPLICIT_TIMER(name)   __kmp_stats_thread_ptr->getExplicitTimer(EXPLICIT_TIMER_##name)->start(TIMER_##name)
 "Starts" an explicit timer which will need a corresponding KMP_STOP_EXPLICIT_TIMER() macro. More...
 
#define KMP_STOP_EXPLICIT_TIMER(name)   __kmp_stats_thread_ptr->getExplicitTimer(EXPLICIT_TIMER_##name)->stop(TIMER_##name)
 "Stops" an explicit timer. More...
 
#define KMP_OUTPUT_STATS(heading_string)   __kmp_output_stats(heading_string)
 Outputs the current thread statistics and reset them. More...
 
#define KMP_INIT_PARTITIONED_TIMERS(name)   __kmp_stats_thread_ptr->getPartitionedTimers()->init(timerPair(EXPLICIT_TIMER_##name, TIMER_##name))
 Initializes the paritioned timers to begin with name. More...
 
#define KMP_RESET_STATS()   __kmp_reset_stats()
 resets all stats (counters to 0, timers to 0 elapsed ticks) More...
 

Enumerations

enum  stats_flags_e {
  noTotal = 1<<0, onlyInMaster = 1<<1, noUnits = 1<<2, notInMaster = 1<<3,
  logEvent = 1<<4
}
 flags to describe the statistic (timer or counter) More...
 
enum  stats_state_e
 the states which a thread can be in
 

Detailed Description

These macros support profiling the libomp library. Use –stats=on when building with build.pl to enable and then use the KMP_* macros to profile (through counts or clock ticks) libomp during execution of an OpenMP program.

Environment Variables

This section describes the environment variables relevant to stats-gathering in libomp

KMP_STATS_FILE

This environment variable is set to an output filename that will be appended NOT OVERWRITTEN if it exists. If this environment variable is undefined, the statistics will be output to stderr

KMP_STATS_THREADS

This environment variable indicates to print thread-specific statistics as well as aggregate statistics. Each thread's statistics will be shown as well as the collective sum of all threads. The values "true", "on", "1", "yes" will all indicate to print per thread statistics.

Macro Definition Documentation

◆ KMP_COUNT_BLOCK

#define KMP_COUNT_BLOCK (   name)    __kmp_stats_thread_ptr->getCounter(COUNTER_##name)->increment()

Increments specified counter (name).

Parameters
namecounter name as specified under the KMP_FOREACH_COUNTER() macro

Use KMP_COUNT_BLOCK(name, value) macro to increment a statistics counter for the executing thread.

Definition at line 747 of file kmp_stats.h.

Referenced by __kmpc_barrier(), __kmpc_copyprivate(), __kmpc_critical(), __kmpc_fork_call(), __kmpc_fork_teams(), __kmpc_master(), __kmpc_reduce(), __kmpc_reduce_nowait(), and __kmpc_single().

◆ KMP_COUNT_VALUE

#define KMP_COUNT_VALUE (   name,
  value 
)    __kmp_stats_thread_ptr->getTimer(TIMER_##name)->addSample(value)

Adds value to specified timer (name).

Parameters
nametimer name as specified under the KMP_FOREACH_TIMER() macro
valuedouble precision sample value to add to statistics for the timer

Use KMP_COUNT_VALUE(name, value) macro to add a particular value to a timer statistics.

Definition at line 735 of file kmp_stats.h.

◆ KMP_FOREACH_COUNTER

#define KMP_FOREACH_COUNTER (   macro,
  arg 
)
Value:
macro (OMP_NESTED_PARALLEL, 0, arg) \
macro (OMP_FOR_static, 0, arg) \
macro (OMP_FOR_dynamic, 0, arg) \
macro (OMP_DISTRIBUTE, 0, arg) \
macro (OMP_BARRIER, 0, arg) \
macro (OMP_CRITICAL,0, arg) \
macro (OMP_SINGLE, 0, arg) \
macro (OMP_MASTER, 0, arg) \
macro (OMP_TEAMS, 0, arg) \
macro (OMP_set_lock, 0, arg) \
macro (OMP_test_lock, 0, arg) \
macro (REDUCE_wait, 0, arg) \
macro (REDUCE_nowait, 0, arg) \
macro (OMP_TASKYIELD, 0, arg) \
macro (OMP_TASKLOOP, 0, arg) \
macro (TASK_executed, 0, arg) \
macro (TASK_cancelled, 0, arg) \
macro (TASK_stolen, 0, arg)
statistic is valid only for master
Definition: kmp_stats.h:49
do not show a TOTAL_aggregation for this statistic
Definition: kmp_stats.h:48

Add new counters under KMP_FOREACH_COUNTER() macro in kmp_stats.h.

Parameters
macroa user defined macro that takes three arguments - macro(COUNTER_NAME, flags, arg)
arga user defined argument to send to the user defined macro

A counter counts the occurrence of some event. Each thread accumulates its own count, at the end of execution the counts are aggregated treating each thread as a separate measurement. (Unless onlyInMaster is set, in which case there's only a single measurement). The min,mean,max are therefore the values for the threads. Adding the counter here and then putting a KMP_BLOCK_COUNTER(name) at the point you want to count is all you need to do. All of the tables and printing is generated from this macro. Format is "macro(name, flags, arg)"

Definition at line 88 of file kmp_stats.h.

◆ KMP_FOREACH_EXPLICIT_TIMER

#define KMP_FOREACH_EXPLICIT_TIMER (   macro,
  arg 
)    KMP_FOREACH_TIMER(macro, arg)

Add new explicit timers under KMP_FOREACH_EXPLICIT_TIMER() macro.

Parameters
macroa user defined macro that takes three arguments - macro(TIMER_NAME, flags, arg)
arga user defined argument to send to the user defined macro
Warning
YOU MUST HAVE THE SAME NAMED TIMER UNDER KMP_FOREACH_TIMER() OR ELSE BAD THINGS WILL HAPPEN!

Explicit timers are ones where we need to allocate a timer itself (as well as the accumulated timing statistics). We allocate these on a per-thread basis, and explicitly start and stop them. Block timers just allocate the timer itself on the stack, and use the destructor to notice block exit; they don't need to be defined here. The name here should be the same as that of a timer above.

Definition at line 229 of file kmp_stats.h.

◆ KMP_INIT_PARTITIONED_TIMERS

#define KMP_INIT_PARTITIONED_TIMERS (   name)    __kmp_stats_thread_ptr->getPartitionedTimers()->init(timerPair(EXPLICIT_TIMER_##name, TIMER_##name))

Initializes the paritioned timers to begin with name.

Parameters
nametimer which you want this thread to begin with

Definition at line 802 of file kmp_stats.h.

◆ KMP_OUTPUT_STATS

#define KMP_OUTPUT_STATS (   heading_string)    __kmp_output_stats(heading_string)

Outputs the current thread statistics and reset them.

Parameters
heading_stringheading put above the final stats output

Explicitly stops all timers and outputs all stats. Environment variable, OMPTB_STATSFILE=filename, can be used to output the stats to a filename instead of stderr Environment variable, OMPTB_STATSTHREADS=true|undefined, can be used to output thread specific stats For now the OMPTB_STATSTHREADS environment variable can either be defined with any value, which will print out thread specific stats, or it can be undefined (not specified in the environment) and thread specific stats won't be printed It should be noted that all statistics are reset when this macro is called.

Definition at line 792 of file kmp_stats.h.

◆ KMP_RESET_STATS

#define KMP_RESET_STATS ( )    __kmp_reset_stats()

resets all stats (counters to 0, timers to 0 elapsed ticks)

Reset all stats for all threads.

Definition at line 831 of file kmp_stats.h.

◆ KMP_START_EXPLICIT_TIMER

#define KMP_START_EXPLICIT_TIMER (   name)    __kmp_stats_thread_ptr->getExplicitTimer(EXPLICIT_TIMER_##name)->start(TIMER_##name)

"Starts" an explicit timer which will need a corresponding KMP_STOP_EXPLICIT_TIMER() macro.

Parameters
nameexplicit timer name as specified under the KMP_FOREACH_EXPLICIT_TIMER() macro

Use to start a timer. This will need a corresponding KMP_STOP_EXPLICIT_TIMER() macro to stop the timer unlike the KMP_TIME_BLOCK(name) macro which has an implicit stopping macro at the end of the code block. All explicit timers are stopped at library exit time before the final statistics are outputted.

Definition at line 761 of file kmp_stats.h.

Referenced by __kmpc_critical().

◆ KMP_STOP_EXPLICIT_TIMER

#define KMP_STOP_EXPLICIT_TIMER (   name)    __kmp_stats_thread_ptr->getExplicitTimer(EXPLICIT_TIMER_##name)->stop(TIMER_##name)

"Stops" an explicit timer.

Parameters
nameexplicit timer name as specified under the KMP_FOREACH_EXPLICIT_TIMER() macro

Use KMP_STOP_EXPLICIT_TIMER(name) to stop a timer. When this is done, the time between the last KMP_START_EXPLICIT_TIMER(name) and this KMP_STOP_EXPLICIT_TIMER(name) will be added to the timer's stat value. The timer will then be reset. After the KMP_STOP_EXPLICIT_TIMER(name) macro is called, another call to KMP_START_EXPLICIT_TIMER(name) will start the timer once again.

Definition at line 775 of file kmp_stats.h.

◆ KMP_TIME_BLOCK

#define KMP_TIME_BLOCK (   name)    blockTimer __BLOCKTIME__(__kmp_stats_thread_ptr->getTimer(TIMER_##name), TIMER_##name)

Uses specified timer (name) to time code block.

Parameters
nametimer name as specified under the KMP_FOREACH_TIMER() macro

Use KMP_TIME_BLOCK(name) macro to time a code block. This will record the time taken in the block and use the destructor to stop the timer. Convenient! With this definition you can't have more than one KMP_TIME_BLOCK in the same code block. I don't think that's a problem.

Definition at line 722 of file kmp_stats.h.

Enumeration Type Documentation

◆ stats_flags_e

flags to describe the statistic (timer or counter)

Enumerator
noTotal 

do not show a TOTAL_aggregation for this statistic

onlyInMaster 

statistic is valid only for master

noUnits 

statistic doesn't need units printed next to it in output

notInMaster 

statistic is valid only for non-master threads

logEvent 

statistic can be logged on the event timeline when KMP_STATS_EVENTS is on (valid only for timers)

Definition at line 47 of file kmp_stats.h.