Movatterモバイル変換

NAME top

pmdaEventNewArray,pmdaEventResetArray,pmdaEventReleaseArray,pmdaEventAddRecord,pmdaEventAddMissedRecord,pmdaEventAddParam,pmdaEventGetAddr,pmdaEventNewHighResArray,pmdaEventResetHighResArray,pmdaEventReleaseHighResArray,pmdaEventAddHighResRecord,pmdaEventAddHighResMissedRecord,pmdaEventAddHighResParam,pmdaEventGetHighResAddr,pmdaEventHighResAddParam,pmdaEventHighResGetAddr- utilities for PMDAs to build packed arrays of event records

C SYNOPSIS top

#include <pcp/pmapi.h>#include <pcp/pmda.h>int pmdaEventNewArray(void);int pmdaEventResetArray(intidx);int pmdaEventReleaseArray(intidx);int pmdaEventAddRecord(intidx, struct timeval *tp, intflags);int pmdaEventAddMissedRecord(intidx, struct timeval *tp,intnmissed);int pmdaEventAddParam(intidx, pmIDpmid, inttype,pmAtomValue *avp);pmEventArray *pmdaEventGetAddr(intidx);int pmdaEventNewHighResArray(void);int pmdaEventResetHighResArray(intidx);int pmdaEventReleaseHighResArray(intidx);int pmdaEventAddHighResRecord(intidx, struct timespec *ts,intflags);int pmdaEventAddHighResMissedRecord(intidx, struct timespec *ts,intnmissed);int pmdaEventAddHighResParam(intidx, pmIDpmid, inttype,pmAtomValue *avp);pmHighResEventArray *pmdaEventGetHighResAddr(intidx);cc ... -lpcp

DESCRIPTION top

A Performance Metrics Domain Agent (PMDA) that wishes to export event records (or trace records) is encouraged to use a metric of either typePM_TYPE_EVENTorPM_TYPE_HIGHRES_EVENTto encode a group of event records into a single packed array. The only difference between the two metric types is the resolution of the timestamp associated with each - in high resolution form it is nanosecond scale (seeclock_gettime(2)), otherwise it is mi‐ croseconds (seegettimeofday(2)). For simplicity, we will only refer to the lower resolution API and data structures hereafter - however, the higher resolution variants are all named similarly and are used in the same way. The packed array of event records format is defined in<pcp/pmapi.h> and consists of apmEventArraystructure containing a variable number ofpmEventRecordstructures, each of which con‐ tains a variable number ofpmEventParameterstructures, which in turn may contain a variable length value for each parameter of each event record. The higher resolution equivalents are defined in the same loca‐ tion, and the structures are named the same. Note that thepmEventParameterstructure has no timestamp associated with it, hence it this does not have a high resolution counterpart. The routines described here are designed to assist the PMDA devel‐ oper in building a packed array of event records, and managing all of the memory allocations required to hold each instance of an ar‐ ray of event records in a contiguous buffer. Normal use would be as part of PMDA'spmdaFetchCallBackmethod.pmdaEventNewArrayis used to create a new event array. The return value is a small integer that is used as theidx parameter to the other routines to identify a specific event array. If needed, a PMDA can create and use multiple event arrays. To start a new cycle and refill an event array from the beginning, callpmdaEventResetArray. If the PMDA has finished with an event array,pmdaEventReleaseAr‐raymay be used to release the underlying storage and ``close'' the event array so that subsequent attempts to useidx will returnPM_ERR_NOCONTEXT. To start a new event record, usepmdaEventAddRecord. The time‐ stamp for the event record is given viatp and theflags parameter may be used to set the control field that determines the type of the event record -flags may be the bit-wise ``or'' of one or more of thePM_EVENT_FLAG_*values defined in<pcp/pmapi.h> (but note thatPM_EVENT_FLAG_MISSEDshould not be used in this context). If event records have been missed, either because the PMDA cannot keep up or because the PMAPI client cannot keep up, thenpmdaEven‐tAddMissedRecordmay be used.idx andtp have the same meaning as forpmdaEventAddRecordandnmissed is the number of event records that have been missed at this point in the time-series of event records.pmdaEventAddMissedRecordmay be called multiple times for a single batch of event records if there are more than one ``missed event record'' episode. Once an event record has been started by callingpmdaEventAd‐dRecord, one or more event parameters may be added usingpmdaEven‐tAddParam. Thepmid andtype parameters describe the PMID of the parameter and the data type (one of thePM_TYPE_*values from<pcp/pmapi.h>) of the value that is passed viaavp.type should one where the size of the value is implied by thetype or by the length of a string value (forPM_TYPE_STRING) or encoded withinavp->vbp (forPM_TYPE_AGGREGATE). Once the packed array has been constructed,pmdaEventGetAddr should be used to initialize theea_typeandea_lenfields at the start of thepmEventArrayand return the base address of the event array that is assigned to thevpfield of thepmAtomValuestruc‐ ture that thepmdaFetchCallBackmethod should return.pmdaEventHighResAddParamandpmdaEventHighResGetAddrare previous names forpmdaEventAddHighResParamandpmdaEventGetHighResAddr (respectively) that have been maintained for backwards compatibil‐ ity.

EXAMPLE top

The following skeletal code shows how these routines might be used. int sts; int myarray; int first = 1; pmEventArray eap; if (first) { first = 0; if ((myarray = pmdaEventNewArray()) < 0) { // report error and fail } } pmdaEventResetArray(myarray); // loop over all event records to be exported ... { struct timeval stamp; int flags; // establish timestamp and set flags to 0 or some combination // of PM_EVENT_FLAG_POINT, PM_EVENT_FLAG_START, PM_EVENT_FLAG_ID, // etc if ((sts = pmdaEventAddRecord(myarray, &stamp, flags)) < 0) { // report error and fail } // loop over all parameters for this event record ... { pmID pmid; int type; pmAtomValue atom; // construct pmid, type and atom for the parameter and // its value if ((sts = pmdaEventAddParam(myarray, pmid, type, &atom)) < 0) { // report error and fail } } // if some event records were missed (could be at the start // of the exported set, or at the end, or in the middle, or // a combination of multiple missed record episodes) ... { int nmissed; struct timeval stamp; if ((sts = pmdaEventAddMissedRecord(myarray, &stamp, nmissed)) < 0) { // report error and fail } } } // finish up eap = pmdaEventGetAddr(myarray);

COLOPHON top

This page is part of thePCP (Performance Co-Pilot) project. In‐ formation about the project can be found at ⟨http://www.pcp.io/⟩. If you have a bug report for this manual page, send it to pcp@groups.io. This page was obtained from the project's upstream Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-08-11.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgPerformance Co-Pilot PCPPMDAEVENTARRAY(3)

HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface.

For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere.

Hosting byjambit GmbH.

ページ先頭