1PMDAEVENTARRAY(3)          Library Functions Manual          PMDAEVENTARRAY(3)
2
3
4

NAME

6       pmdaEventNewArray, pmdaEventResetArray, pmdaEventReleaseArray,
7       pmdaEventAddRecord, pmdaEventAddMissedRecord, pmdaEventAddParam,
8       pmdaEventGetAddr, pmdaEventNewHighResArray, pmdaEventResetHighResArray,
9       pmdaEventReleaseHighResArray, pmdaEventAddHighResRecord, pmdaEventAd‐
10       dHighResMissedRecord, pmdaEventHighResAddParam, pmdaEventHighResGetAddr
11       - utilities for PMDAs to build packed arrays of event records
12

C SYNOPSIS

14       #include <pcp/pmapi.h>
15       #include <pcp/pmda.h>
16
17       int pmdaEventNewArray(void);
18       int pmdaEventResetArray(int idx);
19       int pmdaEventReleaseArray(int idx);
20       int pmdaEventAddRecord(int idx, struct timeval *tp, int flags);
21       int pmdaEventAddMissedRecord(int idx, struct timeval *tp, int nmissed);
22       int pmdaEventAddParam(int idx, pmID pmid, int type, pmAtomValue *avp);
23       pmEventArray *pmdaEventGetAddr(int idx);
24
25       int pmdaEventNewHighResArray(void);
26       int pmdaEventResetHighResArray(int idx);
27       int pmdaEventReleaseHighResArray(int idx);
28       int pmdaEventAddHighResRecord(int idx, struct timespec *ts, int flags);
29       int pmdaEventAddHighResMissedRecord(int idx, struct timespec *ts,
30               int nmissed);
31       int pmdaEventHighResAddParam(int idx, pmID pmid, int type,
32               pmAtomValue *avp);
33       pmHighResEventArray *pmdaEventHighResGetAddr(int idx);
34
35       cc ... -lpcp
36

DESCRIPTION

38       A Performance Metrics Domain Agent (PMDA) that wishes to  export  event
39       records (or trace records) is encouraged to use a metric of either type
40       PM_TYPE_EVENT or PM_TYPE_HIGHRES_EVENT  to  encode  a  group  of  event
41       records into a single packed array.
42
43       The  only  difference between the two metric types is the resolution of
44       the timestamp associated with each - in  high  resolution  form  it  is
45       nanosecond  scale  (see clock_gettime(2)), otherwise it is microseconds
46       (see gettimeofday(2)).  For simplicity, we will only refer to the lower
47       resolution API and data structures hereafter - however, the higher res‐
48       olution variants are all named similarly and are used in the same way.
49
50       The packed array of event records format is  defined  in  <pcp/pmapi.h>
51       and  consists  of a pmEventArray structure containing a variable number
52       of pmEventRecord structures, each of which contains a  variable  number
53       of  pmEventParameter  structures,  which in turn may contain a variable
54       length value for each parameter of each event record.
55
56       The higher resolution equivalents are defined in the same location, and
57       the  structures  are  named  the  same.  Note that the pmEventParameter
58       structure has no timestamp associated with it, hence it this  does  not
59       have a high resolution counterpart.
60
61       The  routines  described here are designed to assist the PMDA developer
62       in building a packed array of event records, and managing  all  of  the
63       memory  allocations required to hold each instance of an array of event
64       records in a contiguous buffer.  Normal use would be as part of  PMDA's
65       pmdaFetchCallBack method.
66
67       pmdaEventNewArray is used to create a new event array.  The return val‐
68       ue is a small integer that is used as the idx parameter  to  the  other
69       routines  to  identify  a  specific event array.  If needed, a PMDA can
70       create and use multiple event arrays.
71
72       To start a new cycle and refill an event array from the beginning, call
73       pmdaEventResetArray.
74
75       If the PMDA has finished with an event array, pmdaEventReleaseArray may
76       be used to release the underlying storage and ``close'' the event array
77       so that subsequent attempts to use idx will return PM_ERR_NOCONTEXT.
78
79       To start a new event record, use pmdaEventAddRecord.  The timestamp for
80       the event record is given via tp and the flags parameter may be used to
81       set  the  control  field that determines the type of the event record -
82       flags may be the bit-wise ``or'' of one or more of the  PM_EVENT_FLAG_*
83       values  defined  in  <pcp/pmapi.h>  (but note that PM_EVENT_FLAG_MISSED
84       should not be used in this context).
85
86       If event records have been missed, either because the PMDA cannot  keep
87       up  or because the PMAPI client cannot keep up, then pmdaEventAddMisse‐
88       dRecord may be used.  idx and tp have the same meaning as for pmdaEven‐
89       tAddRecord  and  nmissed  is the number of event records that have been
90       missed at this point in the time-series of event records.  pmdaEventAd‐
91       dMissedRecord  may be called multiple times for a single batch of event
92       records if there are more than one ``missed event record'' episode.
93
94       Once an event record has been started  by  calling  pmdaEventAddRecord,
95       one or more event parameters may be added using pmdaEventAddParam.  The
96       pmid and type parameters decribe the PMID of the parameter and the data
97       type (one of the PM_TYPE_* values from <pcp/pmapi.h>) of the value that
98       is passed via avp.  type should one where the size of the value is  im‐
99       plied   by   the  type  or  by  the  length  of  a  string  value  (for
100       PM_TYPE_STRING) or encoded within avp->vbp (for PM_TYPE_AGGREGATE).
101
102       Once the packed array has been constructed, pmdaEventGetAddr should  be
103       used  to  initialize  the ea_type and ea_len fields at the start of the
104       pmEventArray and return the base address of the event array that is as‐
105       signed to the vp field of the pmAtomValue structure that the pmdaFetch‐
106       CallBack method should return.
107

EXAMPLE

109       The following skeletal code shows how these routines might be used.
110
111       int             sts;
112       int             myarray;
113       int             first = 1;
114       pmEventArray    eap;
115
116       if (first) {
117          first = 0;
118          if ((myarray = pmdaEventNewArray()) < 0) {
119             // report error and fail
120          }
121       }
122
123       pmdaEventResetArray(myarray);
124
125       // loop over all event records to be exported
126       ... {
127          struct timeval   stamp;
128          int              flags;
129
130          // establish timestamp and set flags to 0 or some combination
131          // of PM_EVENT_FLAG_POINT, PM_EVENT_FLAG_START, PM_EVENT_FLAG_ID,
132          // etc
133          if ((sts = pmdaEventAddRecord(myarray, &stamp, flags)) < 0) {
134             // report error and fail
135          }
136
137          // loop over all parameters for this event record
138          ... {
139             pmID          pmid;
140             int           type;
141             pmAtomValue   atom;
142
143             // construct pmid, type and atom for the parameter and
144             // its value
145             if ((sts = pmdaEventAddParam(myarray, pmid, type, &atom)) < 0) {
146             // report error and fail
147             }
148          }
149
150          // if some event records were missed (could be at the start
151          // of the exported set, or at the end, or in the middle, or
152          // a combination of multiple missed record episodes)
153          ... {
154             int              nmiss;
155             struct timeval   stamp;
156
157             if ((sts = pmdaEventAddMissedRecord(myarray, &stamp, nmiss)) < 0) {
158             // report error and fail
159             }
160          }
161       }
162
163       // finish up
164       eap = pmdaEventGetAddr(myarray);
165

SEE ALSO

167       clock_gettime(2), gettimeofday(2), pmdaEventNewQueue(3),  pmdaEventNew‐
168       Client(3), PMDA(3) and pmEventFlagsStr(3).
169
170
171
172Performance Co-Pilot                  PCP                    PMDAEVENTARRAY(3)
Impressum