NAME | C SYNOPSIS | DESCRIPTION | EXAMPLE | SEE ALSO | COLOPHON

PMDAEVENTARRAY(3)         Library Functions Manual         PMDAEVENTARRAY(3)

NAME         top

       pmdaEventNewArray, pmdaEventResetArray, pmdaEventReleaseArray,
       pmdaEventAddRecord, pmdaEventAddMissedRecord, pmdaEventAddParam,
       pmdaEventGetAddr, pmdaEventNewHighResArray, pmdaEventResetHighResAr‐
       ray, pmdaEventReleaseHighResArray, pmdaEventAddHighResRecord,
       pmdaEventAddHighResMissedRecord, pmdaEventHighResAddParam, pmdaEven‐
       tHighResGetAddr - utilities for PMDAs to build packed arrays of event
       records

C SYNOPSIS         top

       #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);

       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 pmdaEventHighResAddParam(int idx, pmID pmid, int type,
               pmAtomValue *avp);
       pmHighResEventArray *pmdaEventHighResGetAddr(int idx);

       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
       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)), otherwise it is microseconds
       (see gettimeofday(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 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 <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         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              nmiss;
             struct timeval   stamp;

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

       // finish up
       eap = pmdaEventGetAddr(myarray);

SEE ALSO         top

       clock_gettime(2), gettimeofday(2), pmdaEventNewQueue(3),
       pmdaEventNewClient(3), PMDA(3) and pmEventFlagsStr(3).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information 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@oss.sgi.com.  This page was obtained from the project's upstream
       Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
       2017-09-15.  If you discover any rendering problems in this HTML ver‐
       sion 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 is not part of the original man‐
       ual page), send a mail to man-pages@man7.org

Performance Co-Pilot                 PCP                   PMDAEVENTARRAY(3)

Pages that refer to this page: pmdaeventclient(3)pmdaeventqueue(3)pmeventflagsstr(3)