PMDAINIT

Section: C Library Functions (3) Updated: SGI Local index Up

NAME

pmdaInit - initialize a PMDA

C SYNOPSIS

#include <pcp/pmapi.h>
#include <pcp/impl.h>
#include <pcp/pmda.h>
void pmdaInit(pmdaInterface *dispatch, pmdaIndom *indoms, int nindoms, pmdaMetric *metrics, int nmetrics)

cc ... -lpcp_pmda -lpcp

DESCRIPTION

pmdaInit initializes a PMDA so that it is ready to receive PDUs from pmcd(1). The function expects as arguments the instance domain table (indoms) and the metric description table (metrics) that are initialized by the PMDA. The arguments nindoms and nmetrics should be set to the number of instances and metrics in the tables, respectively.

Much of the pmdaInterface structure can be automatically initialized with pmdaDaemon(3), pmdaGetOpt(3) and pmdaDSO(3). pmdaInit completes the PMDA initialization phase with three operations. The first operation adds the domain and instance numbers to the instance and metric tables. Singular metrics (metrics without an instance domain) should have the instance domain PM_INDOM_NULL set in the indom field of the pmDesc structure (see pmLookupDesc(3)). Metrics with an instance domain should set this field to be the serial number of the instance domain in the indoms table.

The instance domain table may be made empty by setting indoms to NULL and nindoms to 0. This allows the caller to provide custom Fetch and Instance callback functions. The metric table may be made empty by setting metrics to NULL and nmetrics to 0. This allows the caller to provide custom Fetch and Descriptor callback functions.

EXAMPLE

For example, a PMDA has three metrics: A, B and C, and two instance domains X and Y, with two instances in each instance domain. The instance domain and metrics description tables could be defined as:

static pmdaInstid _X[] = {
    { 0, "X1" }, { 1, "X2" }
};

static pmdaInstid _Y[] = {
    { 0, "Y1" }, { 1, "Y2" }
};

static pmdaIndom indomtab[] = {
#define X_INDOM 0
    { X_INDOM, 2, _X },
#define Y_INDOM 3
    { Y_INDOM, 2, _Y }
};

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_U32, X_INDOM, PM_SEM_INSTANT, 
        { 0,0,0,0,0,0} }, },
/* C */
    { (void *)0, 
      { PMDA_PMID(0,2), PM_TYPE_DOUBLE, Y_INDOM, PM_SEM_INSTANT, 
        { 0,1,0,0,PM_TIME_SEC,0} }, }
};

The metric description table defines metric A with no instance domain, metric B with instance domain X and metric C with instance domain Y. Metric C has units of seconds, while the other metrics have no units (simple counters). pmdaInit will take these structures and assign the PMDA(3) domain number to the it_indom field of each instance domain. This identifier also replaces the indom field of all metrics which have that instance domain, so that they are correctly associated.

The second stage opens the help text file, if one was specified with the -h command line option (see pmdaGetOpt(3)) or as a helptext argument to pmdaDSO(3) or pmdaDaemon(3).

The final stage determines if the metrics can be directly mapped to the metric table using their unique identifiers. If all of the metric PMID item numbers correspond to the position in the metrics table, then direct mapping is used. This can greatly improve the efficiency of the callback functions.

DIAGNOSTICS

pmdaInit will set dispatch->status to a value less than zero if there is an error that would prevent the PMDA(3) from successfully running. pmcd(1) will terminate the connection to the PMDA(3) if this occurs.

pmdaInit may issue any of these messages:

PMDA interface version interface not supported: The interface version is not supported by pmdaInit.
Using pmdaFetch() but fetch call back not set: The fetch callback, pmdaFetch(3), requires an additional callback to be provided using pmdaSetFetchCallBack(3).
Illegal instance domain inst for metric pmid: The instance domain inst that was specified for metric pmid is not within the range of the instance domain table.
No help text path specified: The help text callback, pmdaText(3), requires a help text file for the metrics to have been opened, however no path to the help text was specified as a command line option, or as an argument to pmdaDSO(3) or pmdaDaemon(3). This message is only a warning.
Direct mapping for metrics disabled @ num: The unit numbers of the metrics did not correspond to the index in the metric description table. The direct mapping failed for metric number num in the metrics table. This is less efficient but is not fatal and the message is only a warning.

CAVEAT

The PMDA must be using PMDA_INTERFACE_2 or later, as specified in the call to pmdaDSO(3) or pmdaDaemon(3).

This document was created by man2html, using the manual pages.
Time: 21:52:36 GMT, April 16, 2011