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_COUNT_VALUE(name, value)    __kmp_stats_thread_ptr->getTimer(TIMER_##name)->addSample((double)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_OUTPUT_STATS(heading_string)   __kmp_output_stats(heading_string)
 Outputs the current thread statistics and reset them. More...
 
#define KMP_INIT_PARTITIONED_TIMERS(name)
 Initializes the partitioned 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 908 of file kmp_stats.h.

◆ KMP_COUNT_VALUE

#define KMP_COUNT_VALUE (   name,
  value 
)     __kmp_stats_thread_ptr->getTimer(TIMER_##name)->addSample((double)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 895 of file kmp_stats.h.

◆ KMP_FOREACH_COUNTER

#define KMP_FOREACH_COUNTER (   macro,
  arg 
)
Value:
macro(OMP_NESTED_PARALLEL, 0, arg) \
macro(OMP_LOOP_STATIC, 0, arg) \
macro(OMP_LOOP_STATIC_STEAL, 0, arg) \
macro(OMP_LOOP_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_MASKED, 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)
@ noTotal
do not show a TOTAL_aggregation for this statistic
Definition: kmp_stats.h:50
@ onlyInMaster
statistic is valid only for primary thread
Definition: kmp_stats.h:51

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 95 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 300 of file kmp_stats.h.

◆ KMP_INIT_PARTITIONED_TIMERS

#define KMP_INIT_PARTITIONED_TIMERS (   name)
Value:
__kmp_stats_thread_ptr->getPartitionedTimers()->init(explicitTimer( \
__kmp_stats_thread_ptr->getTimer(TIMER_##name), TIMER_##name))

Initializes the partitioned timers to begin with name.

Parameters
nametimer which you want this thread to begin with

Definition at line 937 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 928 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 974 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 primary thread

noUnits 

statistic doesn't need units printed next to it

notInMaster 

statistic is valid only for non-primary threads

logEvent 

statistic can be logged on the event timeline when

Definition at line 49 of file kmp_stats.h.