hpmInit, f_hpminit, hpmStart, f_hpmstart, hpmStop, f_hpmstop, hpmTstart, f_hpmtstart, hpmTstop, f_hpmtstop, hpmGetTimeAndCounters, f_hpmgettimeandcounters, hpmGetCounters, f_hpmgetcounters, hpmTerminate, and f_hpmterminate Subroutine

Purpose

Provides application instrumentation for performance monitoring.

Library

HPM Library (libhpm.a)

HPM Library (libhpm.a) includes four additional subroutines for threaded applications.

Syntax

#include <libhpm.h>

void hpmInit(int  taskID, char  *progName); 
void f_hpminit(int  taskID, char  *progName); 

void hpmStart(int  instID, char  *label); 
void f_hpmstart(int  instID, char  *label); 

void hpmStop(int  instID); 
void f_hpmstop(int  instID); 

(libhpm_r only)
void hpmTstart(int  instID, char  *label);
void f_hpmtstart(int  instID, char  *label);
(libhpm_r only)
void hpmTstop(int  instID);
void f_hpmtstop(int  instID); 

void hpmGetTimeAndCounters(int  numCounters, double  *time, long long  *values); 
void f_hpmgettimeandcounters(int  numCounters, double  *time, long long  *values); 

void hpmGetCounters(long long  *values); 
void f_hpmgetcounters(long long  *values); 

void hpmTerminate(int  taskID); 
void f_hpmterminate(int  taskID);

Description

The hpmInit and f_hpminit subroutines initialize tasks specified by the taskID and progName parameters.

The hpmStart and f_hpmstart subroutines debut an instrumented code segment. If more than 100 instrumented sections are required, the HPM_NUM_INST_PTS environment variable can be set to indicate the higher value and instID should be less than this value.

The hpmStop and f_hpmstop subroutines indicate the end of the instrumented code segment instID. For each call to hpmStart and f_hpmstart, there should be a corresponding call to hpmStop and f_hpmstop with the matching instID.

The hpmTstart and f_hpmtstart subroutines perform the same function as hpmStart and f_hpmstart, but are used in threaded applications.

The hpmTstop and f_hpmtstop subroutines perform the same function as hpmStop and f_hpmstop, but are used in threaded applications.

The hpmGetTimeAndCounters and f_hpmgettimeandcounters subroutines are used to return the time in seconds and the accumulated counts since the call to hpmInit or f_hpminit.

The hpmGetCounters and f_hpmgetcounters subroutines return all the accumulated counts since the call to hpmInit or f_hpminit. To minimize intrusion and overhead, the hpmGetCounters and f_hpmgetcounters subroutines do not perform any check on the size of the values array. The number of counters can be obtained from the pm_info2_t.maxpmcs structure element supplied by pm_initialize or by using the pmlist -s command. Alternatively, the application can use the current maximum value of 8.

The hpmTerminate and f_hpmterminate subroutines end the taskID and generate the output. Applications that do not call hpmTerminate or f_hpmterminate, do not generate performance information.

A summary report for each task is written by default in the progName_pid_taskID.hpm file, where progName is the second parameter to the hpmInit subroutine. If progName contains a space or tab character, or is otherwise invalid, a diagnostic message is written to stderr and the library exits with an error to avoid further problems.

The output file name can be defined with the HPM_OUTPUT_NAME environment flag. The libhpm still adds the file name suffix _taskID.hpm for the performance files. By using this environment variable, you can specify the date and time for the output file name. For example: 

MYDATE=$(date +"m%d:11/15/18M%S")
export HPM_OUTPUT_NAME=myprogram_$MYDATE

where the output file for task 27 will have the following name:

myprogram_yyyymmdd:HHMMSS_0027.hpm

The GUI and .viz output is deactivated by default. The aligned set of performance files named progName_pid_taskID.viz or HPM_OUTPUT_NAME_taskID.viz will not be generated (the generation of the .viz file was previously activated by default and avoided with the HPM_VIZ_OUTPUT = FALSE environment variable).

Parameters

Item Description
instID Specifies the instrumented section ID as an integer value greater than 0 and less than 100.
label Specifies a label with a character string.
numCounters Specifies an integer value that indicates the number of counters to be accessed.
progName Specifies a program name using a character string label.
taskID Specifies a node ID with an integer value.
time Specifies a double precision float.
values Specifies an array of type long long of size numCounters.

Execution Environment

Functionality provided by the libhpm library is dependent upon corresponding functions in the libpmapi and libm libraries. Therefore, the -lpmapi -lm link flags must be specified when compiling applications.

Return Values

No return values are defined.

Error Codes

Upon failure, these libhpm subroutines either write error messages explicitly to stderr or use the PMAPI pm_error function. The pm_error function is called following an error return from any of the following subroutines:
  • pm_init_private
  • pm_set_program_mygroup
  • pm_stop_mygroup
  • pm_get_data_mygroup
  • pm_start_mygroup
  • pm_stop_mythread
  • pm_get_data_mythread
  • pm_start_mythread
  • pm_get_data_mythread
Diagnostic messages are explicitly written to stderr or stdout in the following situations:
  • pm_cycles or gettimeofday returns an error
  • The value of the instID parameter is invalid
  • An event set is out of range
  • The libHPMevents file or HPM_flags.env file has an incorrect format
  • There are internal errors.
Error messages that are not fatal are written to stdout or stderr with the text WARNING.