NAME

       pmdaEventNewArray, pmdaEventResetArray, pmdaEventReleaseArray, pmdaEventAddRecord,
       pmdaEventAddMissedRecord, pmdaEventAddParam, pmdaEventGetAddr - utilities for PMDAs to build packed
       arrays of event records

C SYNOPSIS

       #include <pcp/pmapi.h>
       #include <pcp/impl.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);

       cc ... -lpcp

DESCRIPTION

       A  Performance  Metrics Domain Agent (PMDA) that wishes to export event records (or trace records) is en‐
       couraged to use a metric of type PM_TYPE_EVENT to encode a group of event records into  a  single  packed
       array.

       The  packed  array  of  event  records  format is defined in <pcp/pmapi.h> 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 parame‐
       ter of each event record.

       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_NOCON‐
       TEXT.

       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  <pcp/pmapi.h>
       (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  pm‐
       daEventAddRecord  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 decribe the PMID of the  parameter  and  the
       data  type  (one  of  the PM_TYPE_* values from <pcp/pmapi.h>) 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 as‐
       signed to the vp field of the pmAtomValue structure that the pmdaFetchCallBack method should return.

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              nmiss;
             struct timeval   stamp;

             if ((sts = pmdaEventAddMissedRecord(myarray, &stamp, nmiss)) < 0) {
             // report error and fail
             }
          }
       }

       // finish up
       eap = pmdaEventGetAddr(myarray);

SEE ALSO

       pmdaEventNewQueue(3), pmdaEventNewClient(3), PMDA(3) and pmEventFlagsStr(3).

Performance Co-Pilot                                   PCP                                     PMDAEVENTARRAY(3)