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 encouraged 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 parameter 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_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 <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 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 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 assigned 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).