PMDAEVENTARRAY(3)

💖 PMDAEVENTARRAY 💖

okay bestie, this one is from the Library Functions Manual, and it's the whole glow-up guide for PMDA devs who wanna ship packed arrays of event records. sit down, hydrate, let's go 🫶

---

✨ 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. yes, all of them. the whole girl group. 💅

---

🌸 C SYNOPSIS 🌸

#include <pcp/pmapi.h>
#include <pcp/pmda.h>

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 🦋

So. If you're a Performance Metrics Domain Agent (PMDA) and you wanna export event records (or trace records, same vibe), the move is to use a metric of either type PM_TYPE_EVENT or PM_TYPE_HIGHRES_EVENT to encode a whole group of event records into one single packed array. one metric, many records, main character energy. 👑

The only difference between those two metric types? the resolution of the timestamp attached to each one. high-res form is nanosecond scale (peep clock_gettime(2)), otherwise it's microseconds (peep gettimeofday(2)). for simplicity, this whole page is gonna talk about the lower-res API and its data structures — but bestie, the higher resolution variants are all named similarly and you use them the exact same way. no cap.

The packed array of event records format is defined in <pcp/pmapi.h> and it's giving layers:

• a pmEventArray structure containing a variable number of pmEventRecord structures
• each of those contains a variable number of pmEventParameter structures
• which in turn may contain a variable length value for each parameter of each event record

it's nesting all the way down, fr fr. 🪆

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. (yes, that's the original wording, we're keeping it, it's iconic.)

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 your PMDA's pmdaFetchCallBack method.

Here's the cast of characters, one by one:

• pmdaEventNewArray — creates a new event array. the return value is a small integer used as the idx parameter to all the other routines, so they know which specific event array you mean. if needed, a PMDA can create and use multiple event arrays. you're not limited to one, live your truth. ✨
• pmdaEventResetArray — call this to start a new cycle and refill an event array from the beginning.
• pmdaEventReleaseArray — if the PMDA is finished with an event array, this releases the underlying storage and ``close''s the event array, so that subsequent attempts to use idx will return PM_ERR_NOCONTEXT. she's done, she's gone, don't come back. 💀
• pmdaEventAddRecord — starts a new event record. the timestamp for the record comes in 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 <pcp/pmapi.h> — but note that PM_EVENT_FLAG_MISSED should not be used in this context.
• pmdaEventAddMissedRecord — if event records have been missed, either because the PMDA cannot keep up or because the PMAPI client cannot keep up, use this. idx and tp mean the same thing 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. it may be called multiple times for a single batch of event records if there's more than one ``missed event record'' episode. 😭
• pmdaEventAddParam — once an event record has been started by calling pmdaEventAddRecord, add one or more event parameters with this. the pmid and type parameters describe the PMID of the parameter and the data type (one of the PM_TYPE_* values from <pcp/pmapi.h>) of the value 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).
• pmdaEventGetAddr — once the packed array has been constructed, use this 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. the final reveal. 🎀

and one more lil history lesson: pmdaEventHighResAddParam and pmdaEventHighResGetAddr are previous names for pmdaEventAddHighResParam and pmdaEventGetHighResAddr (respectively) that have been maintained for backwards compatibility. legacy queens, we respect them. 👑

---

🌈 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), gettimeofday(2), pmdaEventNewQueue(3), pmdaEventNewClient(3), PMDA(3) and pmEventFlagsStr(3).

go read those next bestie, you got this 💜

---

k that's the whole page!! this one came out of the Performance Co-Pilot / PCP world, and like every good thing it lives under PMDAEVENTARRAY(3). mwah, bye!! 🎀✨🦋