--- name: "pmdaEventNewArray" section: "3" platform: "linux" package: "pcp" version: "7.2.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/pmdaEventArray" --- # pmdaEventNewArray(3) utilities for PMDAs to build packed arrays of event records Part of [pmdaEventArray(3)](/pmdaEventArray/3.md). ## NAME **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 **#include \**\ **#include \** **int pmdaEventNewArray(void);**\ **int pmdaEventResetArray(int** *idx***);**\ **int pmdaEventReleaseArray(int** *idx***);**\ **int pmdaEventAddRecord(int** *idx***,** **struct timeval \****tp***,** **int** *flags***);**\ **int pmdaEventAddMissedRecord(int** *idx***,** **struct timeval \****tp***,** **int** *nmissed***);**\ **int pmdaEventAddParam(int** *idx***,** **pmID** *pmid***,** **int** *type***,** **pmAtomValue \****avp***);**\ **pmEventArray \*pmdaEventGetAddr(int** *idx***);** **int pmdaEventNewHighResArray(void);**\ **int pmdaEventResetHighResArray(int** *idx***);**\ **int pmdaEventReleaseHighResArray(int** *idx***);**\ **int pmdaEventAddHighResRecord(int** *idx***,** **struct timespec \****ts***,** **int** *flags***);**\ **int pmdaEventAddHighResMissedRecord(int** *idx***,** **struct timespec \****ts***,** **int** *nmissed***);**\ **int pmdaEventAddHighResParam(int** *idx***,** **pmID** *pmid***,** **int** *type***,** **pmAtomValue \****avp***);**\ **pmHighResEventArray \*pmdaEventGetHighResAddr(int** *idx***);** **cc ... -lpcp** ## DESCRIPTION A Performance Metrics Domain Agent (PMDA) that wishes to export event records (or trace records) is encouraged to use a metric of either type **PM\_TYPE\_EVENT** or **PM\_TYPE\_HIGHRES\_EVENT** to 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 (see [**clock\_gettime**(2)](/clock_gettime/2.md)), otherwise it is microseconds (see [**gettimeofday**(2)](/gettimeofday/2.md)). 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 *\* and consists of a **pmEventArray** structure containing a variable number of **pmEventRecord** structures, each of which contains a variable number of **pmEventParameter** structures, 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 location, and the structures are named the same. Note that the **pmEventParameter** structure 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 developer in building a packed array of event records, and managing all of the memory allocations required to hold each instance of an array of event records in a contiguous buffer. Normal use would be as part of PMDA's **pmdaFetchCallBack** method. **pmdaEventNewArray** is used to create a new event array. The return value is a small integer that is used as the *idx* 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, call **pmdaEventResetArray**. If the PMDA has finished with an event array, **pmdaEventReleaseArray** may be used to release the underlying storage and \`\`close'' the event array so that subsequent attempts to use *idx* will return **PM\_ERR\_NOCONTEXT**. To start a new event record, use **pmdaEventAddRecord**. The timestamp for the event record is given via *tp* and the *flags* 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 the **PM\_EVENT\_FLAG\_\*** values defined in *\* (but note that **PM\_EVENT\_FLAG\_MISSED** should 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, then **pmdaEventAddMissedRecord** may be used. *idx* and *tp* have the same meaning as for **pmdaEventAddRecord** and *nmissed* is the number of event records that have been missed at this point in the time-series of event records. **pmdaEventAddMissedRecord** may 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 calling **pmdaEventAddRecord**, one or more event parameters may be added using **pmdaEventAddParam**. The *pmid* and *type* parameters describe the PMID of the parameter and the data type (one of the **PM\_TYPE\_\*** values from *\*) of the value that is passed via *avp*. *type* should one where the size of the value is implied by the *type* or by the length of a string value (for **PM\_TYPE\_STRING**) or encoded within *avp-\>vbp* (for **PM\_TYPE\_AGGREGATE**). Once the packed array has been constructed, **pmdaEventGetAddr** should be used to initialize the **ea\_type** and **ea\_len** fields at the start of the **pmEventArray** and return the base address of the event array that is assigned to the **vp** field of the **pmAtomValue** structure that the **pmdaFetchCallBack** method should return. **pmdaEventHighResAddParam** and **pmdaEventHighResGetAddr** are previous names for **pmdaEventAddHighResParam** and **pmdaEventGetHighResAddr** (respectively) that have been maintained for backwards compatibility. ## EXAMPLE 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); ``` ## SEE ALSO [**clock\_gettime**(2)](/clock_gettime/2.md), [**gettimeofday**(2)](/gettimeofday/2.md), [**pmdaEventNewQueue**(3)](/pmdaEventNewQueue/3.md), [**pmdaEventNewClient**(3)](/pmdaEventNewClient/3.md), [**PMDA**(3)](/PMDA/3.md) and [**pmEventFlagsStr**(3)](/pmEventFlagsStr/3.md).