1PMDAEVENTARRAY(3) Library Functions Manual PMDAEVENTARRAY(3)
2
6 pmdaEventNewArray, pmdaEventResetArray, pmdaEventReleaseArray, pm‐
7 daEventAddRecord, pmdaEventAddMissedRecord, pmdaEventAddParam, pm‐
8 daEventGetAddr, pmdaEventNewHighResArray, pmdaEventResetHighResArray,
9 pmdaEventReleaseHighResArray, pmdaEventAddHighResRecord, pmdaEventAd‐
10 dHighResMissedRecord, pmdaEventAddHighResParam, pmdaEventGetHighRe‐
11 sAddr, pmdaEventHighResAddParam, pmdaEventHighResGetAddr - utilities
12 for PMDAs to build packed arrays of event records
13
15 #include <pcp/pmapi.h>
16 #include <pcp/pmda.h>
17 int pmdaEventNewArray(void);
19 int pmdaEventResetArray(int idx);
20 int pmdaEventReleaseArray(int idx);
21 int pmdaEventAddRecord(int idx, struct timeval *tp, int flags);
22 int pmdaEventAddMissedRecord(int idx, struct timeval *tp, int nmissed);
23 int pmdaEventAddParam(int idx, pmID pmid, int type, pmAtomValue *avp);
24 pmEventArray *pmdaEventGetAddr(int idx);
25 int pmdaEventNewHighResArray(void);
27 int pmdaEventResetHighResArray(int idx);
28 int pmdaEventReleaseHighResArray(int idx);
29 int pmdaEventAddHighResRecord(int idx, struct timespec *ts, int flags);
30 int pmdaEventAddHighResMissedRecord(int idx, struct timespec *ts,
31 int nmissed);
32 int pmdaEventAddHighResParam(int idx, pmID pmid, int type,
33 pmAtomValue *avp);
34 pmHighResEventArray *pmdaEventGetHighResAddr(int idx);
35 cc ... -lpcp
37
39 A Performance Metrics Domain Agent (PMDA) that wishes to export event
40 records (or trace records) is encouraged to use a metric of either type
41 PM_TYPE_EVENT or PM_TYPE_HIGHRES_EVENT to encode a group of event
42 records into a single packed array.
43 The only difference between the two metric types is the resolution of
45 the timestamp associated with each - in high resolution form it is
46 nanosecond scale (see clock_gettime(2)), otherwise it is microseconds
47 (see gettimeofday(2)). For simplicity, we will only refer to the lower
48 resolution API and data structures hereafter - however, the higher res‐
49 olution variants are all named similarly and are used in the same way.
50 The packed array of event records format is defined in <pcp/pmapi.h>
52 and consists of a pmEventArray structure containing a variable number
53 of pmEventRecord structures, each of which contains a variable number
54 of pmEventParameter structures, which in turn may contain a variable
55 length value for each parameter of each event record.
56 The higher resolution equivalents are defined in the same location, and
58 the structures are named the same. Note that the pmEventParameter
59 structure has no timestamp associated with it, hence it this does not
60 have a high resolution counterpart.
61 The routines described here are designed to assist the PMDA developer
63 in building a packed array of event records, and managing all of the
64 memory allocations required to hold each instance of an array of event
65 records in a contiguous buffer. Normal use would be as part of PMDA's
66 pmdaFetchCallBack method.
67 pmdaEventNewArray is used to create a new event array. The return val‐
69 ue is a small integer that is used as the idx parameter to the other
70 routines to identify a specific event array. If needed, a PMDA can
71 create and use multiple event arrays.
72 To start a new cycle and refill an event array from the beginning, call
74 pmdaEventResetArray.
75 If the PMDA has finished with an event array, pmdaEventReleaseArray may
77 be used to release the underlying storage and ``close'' the event array
78 so that subsequent attempts to use idx will return PM_ERR_NOCONTEXT.
79 To start a new event record, use pmdaEventAddRecord. The timestamp for
81 the event record is given via tp and the flags parameter may be used to
82 set the control field that determines the type of the event record -
83 flags may be the bit-wise ``or'' of one or more of the PM_EVENT_FLAG_*
84 values defined in <pcp/pmapi.h> (but note that PM_EVENT_FLAG_MISSED
85 should not be used in this context).
86 If event records have been missed, either because the PMDA cannot keep
88 up or because the PMAPI client cannot keep up, then pmdaEventAddMisse‐
89 dRecord may be used. idx and tp have the same meaning as for pmdaEven‐
90 tAddRecord and nmissed is the number of event records that have been
91 missed at this point in the time-series of event records. pmdaEventAd‐
92 dMissedRecord may be called multiple times for a single batch of event
93 records if there are more than one ``missed event record'' episode.
94 Once an event record has been started by calling pmdaEventAddRecord,
96 one or more event parameters may be added using pmdaEventAddParam. The
97 pmid and type parameters decribe the PMID of the parameter and the data
98 type (one of the PM_TYPE_* values from <pcp/pmapi.h>) of the value that
99 is passed via avp. type should one where the size of the value is im‐
100 plied by the type or by the length of a string value (for
101 PM_TYPE_STRING) or encoded within avp->vbp (for PM_TYPE_AGGREGATE).
102 Once the packed array has been constructed, pmdaEventGetAddr should be
104 used to initialize the ea_type and ea_len fields at the start of the
105 pmEventArray and return the base address of the event array that is as‐
106 signed to the vp field of the pmAtomValue structure that the pmdaFetch‐
107 CallBack method should return.
108 pmdaEventHighResAddParam and pmdaEventHighResGetAddr are previous names
110 for pmdaEventAddHighResParam and pmdaEventGetHighResAddr (respectively)
111 that have been maintained for backwards compatibility.
112
114 The following skeletal code shows how these routines might be used.
115 int sts;
117 int myarray;
118 int first = 1;
119 pmEventArray eap;
120 if (first) {
122 first = 0;
123 if ((myarray = pmdaEventNewArray()) < 0) {
124 // report error and fail
125 }
126 }
127 pmdaEventResetArray(myarray);
129 // loop over all event records to be exported
131 ... {
132 struct timeval stamp;
133 int flags;
134 // establish timestamp and set flags to 0 or some combination
136 // of PM_EVENT_FLAG_POINT, PM_EVENT_FLAG_START, PM_EVENT_FLAG_ID,
137 // etc
138 if ((sts = pmdaEventAddRecord(myarray, &stamp, flags)) < 0) {
139 // report error and fail
140 }
141 // loop over all parameters for this event record
143 ... {
144 pmID pmid;
145 int type;
146 pmAtomValue atom;
147 // construct pmid, type and atom for the parameter and
149 // its value
150 if ((sts = pmdaEventAddParam(myarray, pmid, type, &atom)) < 0) {
151 // report error and fail
152 }
153 }
154 // if some event records were missed (could be at the start
156 // of the exported set, or at the end, or in the middle, or
157 // a combination of multiple missed record episodes)
158 ... {
159 int nmiss;
160 struct timeval stamp;
161 if ((sts = pmdaEventAddMissedRecord(myarray, &stamp, nmiss)) < 0) {
163 // report error and fail
164 }
165 }
166 }
167 // finish up
169 eap = pmdaEventGetAddr(myarray);
170
172 clock_gettime(2), gettimeofday(2), pmdaEventNewQueue(3), pmdaEventNew‐
173 Client(3), PMDA(3) and pmEventFlagsStr(3).
174Performance Co-Pilot PCP PMDAEVENTARRAY(3)