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(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 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

  name | counter 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 900 of file kmp_stats.h.

Referenced by __kmpc_barrier(), __kmpc_copyprivate(), __kmpc_critical(), __kmpc_critical_with_hint(), __kmpc_fork_teams(), __kmpc_master(), __kmpc_omp_reg_task_with_affinity(), __kmpc_proxy_task_completed_ooo(), __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

  name | timer name as specified under the KMP_FOREACH_TIMER() macro
  value | double 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 887 of file kmp_stats.h.

## KMP_FOREACH_COUNTER

#define KMP_FOREACH_COUNTER | ( |  | macro,
|  |  | arg
| ) |  |

Value:
macro(OMP_PARALLEL,stats_flags_e::onlyInMaster|stats_flags_e::noTotal,arg) \
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_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)
onlyInMaster
statistic is valid only for master
Definition: kmp_stats.h:51
noTotal
do not show a TOTAL_aggregation for this statistic
Definition: kmp_stats.h:50

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

Parameters

  macro | a user defined macro that takes three arguments - macro(COUNTER_NAME, flags, arg)
  arg | a 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

  macro | a user defined macro that takes three arguments - macro(TIMER_NAME, flags, arg)
  arg | a 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 292 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 paritioned timers to begin with name.

Parameters

  name | timer which you want this thread to begin with

Definition at line 929 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_string | heading 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 920 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 966 of file kmp_stats.h.

## Enumeration Type Documentation

## stats_flags_e

enum 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
notInMaster | statistic is valid only for non-master threads
logEvent | statistic can be logged on the event timeline when

Definition at line 49 of file kmp_stats.h.