pmdaeventarray(3) — Linux manual page

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,
       pmdaEventResetHighResArray, pmdaEventReleaseHighResArray,
       pmdaEventAddHighResRecord, pmdaEventAddHighResMissedRecord,
       pmdaEventAddHighResParam, pmdaEventGetHighResAddr,
       pmdaEventHighResAddParam, pmdaEventHighResGetAddr - utilities for
       PMDAs to build packed arrays of event records

C SYNOPSIS         top

       #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         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 resolu‐
       tion 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 here‐
       after - 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 con‐
       tains 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  loca‐
       tion,  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 de‐
       veloper 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  re‐
       turn  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 begin‐
       ning, call pmdaEventResetArray.

       If the PMDA has finished with an event array, pmdaEventReleaseAr‐
       ray may be used to release the underlying storage  and  ``close''
       the  event  array so that subsequent attempts to use idx will re‐
       turn PM_ERR_NOCONTEXT.

       To start a new event record, use pmdaEventAddRecord.   The  time‐
       stamp  for the event record is given via tp and the flags parame‐
       ter 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  con‐
       text).

       If event records have been missed, either because the PMDA cannot
       keep  up  or  because  the  PMAPI client cannot keep up, then pm‐
       daEventAddMissedRecord 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-se‐
       ries 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  pmdaEventAd‐
       dRecord,  one  or  more  event  parameters may be added using pm‐
       daEventAddParam.  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 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 compati‐
       bility.

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

             if ((sts = pmdaEventAddMissedRecord(myarray, &stamp, nmissed)) < 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.  In‐
       formation about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug  report  for  this  manual  page,  send  it  to
       [email protected].    This  page  was  obtained  from  the  project's
       upstream                      Git                      repository
       ⟨https://github.com/performancecopilot/pcp.git⟩   on  2024-06-14.
       (At that time, the date of the most recent commit that was  found
       in the repository was 2024-06-14.)  If you discover any rendering
       problems  in  this HTML version 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 manual page), send a  mail  to
       [email protected]

Performance Co-Pilot               PCP                 PMDAEVENTARRAY(3)

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