1PMDAEVENTARRAY(3) Library Functions Manual PMDAEVENTARRAY(3)
2
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
14 #include <pcp/pmapi.h>
15 #include <pcp/pmda.h>
16 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 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 cc ... -lpcp
36
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 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 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 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 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 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 To start a new cycle and refill an event array from the beginning, call
73 pmdaEventResetArray.
74 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 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 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 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 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
109 The following skeletal code shows how these routines might be used.
110 int sts;
112 int myarray;
113 int first = 1;
114 pmEventArray eap;
115 if (first) {
117 first = 0;
118 if ((myarray = pmdaEventNewArray()) < 0) {
119 // report error and fail
120 }
121 }
122 pmdaEventResetArray(myarray);
124 // loop over all event records to be exported
126 ... {
127 struct timeval stamp;
128 int flags;
129 // 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 // loop over all parameters for this event record
138 ... {
139 pmID pmid;
140 int type;
141 pmAtomValue atom;
142 // 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 // 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 if ((sts = pmdaEventAddMissedRecord(myarray, &stamp, nmiss)) < 0) {
158 // report error and fail
159 }
160 }
161 }
162 // finish up
164 eap = pmdaEventGetAddr(myarray);
165
167 clock_gettime(2), gettimeofday(2), pmdaEventNewQueue(3), pmdaEventNew‐
168 Client(3), PMDA(3) and pmEventFlagsStr(3).
169Performance Co-Pilot PCP PMDAEVENTARRAY(3)