|
NAME | C SYNOPSIS | DESCRIPTION | EXAMPLE | SEE ALSO | COLOPHON |
PMDAEVENTARRAY(3) Library Functions Manual PMDAEVENTARRAY(3)
pmdaEventNewArray, pmdaEventResetArray, pmdaEventReleaseArray,
pmdaEventAddRecord, pmdaEventAddMissedRecord, pmdaEventAddParam,
pmdaEventGetAddr, pmdaEventNewHighResArray, pmdaEventResetHighResAr‐
ray, pmdaEventReleaseHighResArray, pmdaEventAddHighResRecord,
pmdaEventAddHighResMissedRecord, pmdaEventHighResAddParam, pmdaEven‐
tHighResGetAddr - utilities for PMDAs to build packed arrays of event
records
#include <pcp/pmapi.h>
#include <pcp/impl.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 pmdaEventHighResAddParam(int idx, pmID pmid, int type,
pmAtomValue *avp);
pmHighResEventArray *pmdaEventHighResGetAddr(int idx);
cc ... -lpcp
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 microseconds
(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 contains 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 location,
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 developer
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 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, pmdaEventReleaseArray
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 timestamp
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
pmdaEventAddMissedRecord 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 pmdaEventAddRecord,
one or more event parameters may be added using pmdaEventAddParam.
The pmid and type parameters decribe 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.
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 nmiss;
struct timeval stamp;
if ((sts = pmdaEventAddMissedRecord(myarray, &stamp, nmiss)) < 0) {
// report error and fail
}
}
}
// finish up
eap = pmdaEventGetAddr(myarray);
clock_gettime(2), gettimeofday(2), pmdaEventNewQueue(3),
pmdaEventNewClient(3), PMDA(3) and pmEventFlagsStr(3).
This page is part of the PCP (Performance Co-Pilot) project.
Information about the project can be found at ⟨http://www.pcp.io/⟩.
If you have a bug report for this manual page, send it to
pcp@oss.sgi.com. This page was obtained from the project's upstream
Git repository ⟨git://git.pcp.io/pcp⟩ on 2017-07-05. 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 man-pages@man7.org
Performance Co-Pilot PCP PMDAEVENTARRAY(3)
Pages that refer to this page: pmdaeventclient(3), pmdaeventqueue(3), pmeventflagsstr(3)