# pmdaeventarray

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


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



           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  mi‐
           croseconds  (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  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 devel‐
           oper in building a packed array of event records, and managing all
           of the memory allocations required to hold each instance of an ar‐
           ray 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, **pmdaEventReleaseAr‐**
           **ray** 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 time‐
           stamp 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 **pmdaEven‐**
           **tAddMissedRecord** 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 **pmdaEventAd‐**
           **dRecord** , one or more event parameters may be added using **pmdaEven‐**
           **tAddParam**.  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** struc‐
           ture that the **pmdaFetchCallBack** method should return.
    
           **pmdaEventHighResAddParam** and **pmdaEventHighResGetAddr** are  previous
           names  for  **pmdaEventAddHighResParam** and  **pmdaEventGetHighResAddr**
           (respectively) that have been maintained for backwards compatibil‐
           ity.
    


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


* * *