Provides application instrumentation for performance monitoring.
HPM Library (libhpm.a)
HPM Library (libhpm.a) includes four additional subroutines for threaded applications.
#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);
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:1/14/10M%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).
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.
No return values are defined.
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:
Diagnostic messages are explicitly written to stderr or stdout in the following situations:
Error messages that are not fatal are written to stdout or stderr with the text WARNING.
The getrusage, getrusage64, times, or vtimes Subroutine, pm_initialize Subroutine.
Performance Monitor API Programming in AIX Version 6.1 Performance Tools Guide and Reference.