NAME
pmdaFetch, pmdaSetFetchCallBack - fill a pmResult structure with the
requested metric values
C SYNOPSIS
#include <pcp/pmapi.h>
#include <pcp/impl.h>
#include <pcp/pmda.h>
int pmdaFetch(int numpmid, pmID *pmidlist, pmResult **resp, pmdaExt
*pmda);
void pmdaSetFetchCallBack(pmdaInterface *dispatch, pmdaFetchCallBack
callback);
cc ... -lpcp_pmda -lpcp
DESCRIPTION
pmdaFetch is a generic callback used by a PMDA(3) to process a fetch
request from pmcd(1). The request from pmcd is initiated by a client
calling pmFetch(3).
This is the only generic callback (see PMDA(3)) that is incomplete,
requiring a callback of it’s own. The additional callback should be
registered using pmdaSetFetchCallBack.
pmdaFetch will allocate and resize the resp result structure, to store
values for the numpmid metrics listed in pmidlist.
For each instance listed in the profile (see pmdaProfile(3)) of each
metric listed in pmidlist, the registered callback is required to fill
a pmAtomValue structure with the metric’s value. This value is then
copied into the pmResult structure.
For example, a PMDA has two metrics (A and B) and an instance domain
(X) with two instances (X1 and X2). The instance domain and metrics
description tables (see pmdaInit(3)) could be defined as:
static pmdaInstid _X[] = {
{ 0, "X1" }, { 1, "X2" }
};
static pmdaIndom indomtab[] = {
#define X_INDOM 0
{ 0, 2, _X },
};
static pmdaMetric metrictab[] = {
/* A */
{ (void *)0,
{ PMDA_PMID(0,0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT,
{ 0,0,0,0,0,0} }, },
/* B */
{ (void *)0,
{ PMDA_PMID(0,1), PM_TYPE_DOUBLE, X_INDOM, PM_SEM_INSTANT,
{ 0,1,0,0,PM_TIME_SEC,0} }, },
};
A callback for pmdaFetch could be defined as:
static int
myFetchCallBack(pmdaMetric *mdesc, unsigned int inst, pmdaAtomValue *atom)
{
__pmID_int *idp = (__pmID_int *)&(mdesc->m_desc.pmid);
switch (idp->item) {
case 0:
atom->l = /* assign some value for metric A */;
break;
case 1:
switch (inst) {
case 0:
atom->d = /* assign a value for metric B, instance X1 */;
break;
case 1:
atom->d = /* assign a value for metric B, instance X2 */;
break;
default:
return PM_ERR_INST;
}
default:
return PM_ERR_PMID;
}
return 1;
}
The metric description mdesc and the instance identifier inst are used
to determine which metric and instance is required. The callback
should return 1 on success, 0 if the metric value is not currently
available, or if the PMID or the instance are not supported then
PM_ERR_PMID or PM_ERR_INST should be returned, respectively.
DIAGNOSTICS
The following error messages indicate that there is discrepancy between
the namespace, pmdaMetric and pmdaIndom tables passed to pmdaInit(3),
and the registered fetch callback:
pmdaFetch: Requested metric metric is not defined
A requested metric metric is not listed in the
pmdaMetric table. The namespace for this PMDA(3) may
contain additional metrics.
pmdaFetch: PMID pmid not handled by fetch callback
The fetch callback has returned PM_ERR_PMID. This
indicates that a metric may be listed in the pmdaMetric
table, but is not supported by the callback.
pmdaFetch: Instance inst of PMID pmid not handled by fetch callback
The fetch callback has returned PM_ERR_INST. This
indicates that an instance of metric is listed in the
pmdaIndom table, but is not supported by the callback.
pmdaFetch: Fetch callback error:
The fetch callback returned a result other than 0,
PM_ERR_PMID or PM_ERR_INST.
pmdaFetch: Descriptor type (type) for metric pmid is bad
The data type type specified for the metric pmid in the
pmdaMetric table is illegal.
pmdaFetch will return -errno if an error occurred while allocating the
pmResult structure or copying the value from the pmAtomValue.
CAVEAT
The PMDA must be using PMDA_INTERFACE_2 or later, as specified in the
call to pmdaDSO(3) or pmdaDaemon(3).
SEE ALSO
pmcd(1), PMAPI(3), PMDA(3), pmdaDaemon(3), pmdaDSO(3), pmdaInit(3) and
pmFetch(3).