1PMDAMAIN(3)                Library Functions Manual                PMDAMAIN(3)
2
3
4

NAME

6       pmdaMain,  pmdaGetContext, pmdaSetResultCallBack, pmdaSetCheckCallBack,
7       pmdaSetDoneCallBack, pmdaSetEndContextCallBack - generic PDU processing
8       for a PMDA
9

C SYNOPSIS

11       #include <pcp/pmapi.h>
12       #include <pcp/pmda.h>
13
14       cc ... -lpcp_pmda -lpcp
15
16       void pmdaMain(pmdaInterface *dispatch);
17       void pmdaSetCheckCallBack(pmdaInterface *dispatch,
18               pmdaCheckCallBack callback);
19       void pmdaSetDoneCallBack(pmdaInterface *dispatch,
20               pmdaDoneCallBack callback);
21       void pmdaSetResultCallBack(pmdaInterface *dispatch,
22               pmdaResultCallBack callback);
23       void pmdaSetEndContextCallBack(pmdaInterface *dispatch,
24               pmdaEndContextCallBack callback);
25       int pmdaGetContext(void);
26
27

DESCRIPTION

29       For  Performance  Metric  Domain  Agents (PMDA(3)) using the binary PDU
30       protocols to communicate with pmcd(1), the routine pmdaMain provides  a
31       generic implementation of the PDU-driven main loop.
32
33       dispatch  describes how to process each incoming PDU. It is a vector of
34       function pointers, one per request PDU type, as used in the DSO  inter‐
35       face for a PMDA, namely:
36
37       /*
38        * Interface Definitions for PMDA Methods
39        */
40       typedef struct {
41           int domain;         /* set/return performance metrics domain id here */
42           struct {
43               unsigned int    pmda_interface: 8; /* PMDA DSO interface version */
44               unsigned int    pmapi_version : 8; /* PMAPI version */
45               unsigned int    flags : 16;        /* optional feature flags */
46           } comm;             /* set/return communication and version info */
47           int status;         /* return initialization status here */
48
49           union {
50               struct {                              /* PMDA_INTERFACE_2 or _3 */
51                   pmdaExt *ext;
52                   int (*profile)(pmProfile *, pmdaExt *);
53                   int (*fetch)(int, pmID *, pmResult **, pmdaExt *);
54                   int (*desc)(pmID, pmDesc *, pmdaExt *);
55                   int (*instance)(pmInDom, int, char *, pmInResult **, pmdaExt *);
56                   int (*text)(int, int, char **, pmdaExt *);
57                   int (*store)(pmResult *, pmdaExt *);
58               } two, three;
59
60               struct {                              /* PMDA_INTERFACE_4 or _5 */
61                   pmdaExt *ext;
62                   int     (*profile)(pmProfile *, pmdaExt *);
63                   int     (*fetch)(int, pmID *, pmResult **, pmdaExt *);
64                   int     (*desc)(pmID, pmDesc *, pmdaExt *);
65                   int     (*instance)(pmInDom, int, char *, pmInResult **, pmdaExt *);
66                   int     (*text)(int, int, char **, pmdaExt *);
67                   int     (*store)(pmResult *, pmdaExt *);
68                   int     (*pmid)(char *, pmID *, pmdaExt *);
69                   int     (*name)(pmID, char ***, pmdaExt *);
70                   int     (*children)(char *, int, char ***, int **, pmdaExt *);
71               } four, five;
72
73               struct {                              /* PMDA_INTERFACE_6 */
74                   pmdaExt *ext;
75                   int     (*profile)(pmProfile *, pmdaExt *);
76                   int     (*fetch)(int, pmID *, pmResult **, pmdaExt *);
77                   int     (*desc)(pmID, pmDesc *, pmdaExt *);
78                   int     (*instance)(pmInDom, int, char *, pmInResult **, pmdaExt *);
79                   int     (*text)(int, int, char **, pmdaExt *);
80                   int     (*store)(pmResult *, pmdaExt *);
81                   int     (*pmid)(char *, pmID *, pmdaExt *);
82                   int     (*name)(pmID, char ***, pmdaExt *);
83                   int     (*children)(char *, int, char ***, int **, pmdaExt *);
84                   int     (*attribute)(int, int, const char *, int, pmdaExt *);
85               } six;
86           } version;
87
88       } pmdaInterface;
89
90       This  structure has been extended to incorporate the multiple interface
91       versions that have evolved over time.  For  pmdaMain,  dispatch->domain
92       and  dispatch->status  are  ignored.   The comm.pmda_interface field is
93       used to determine the interface used by the PMDA.  Setting  this  field
94       to  PMDA_INTERFACE_2 or PMDA_INTERFACE_3 will force pmdaMain to use the
95       callbacks in the version.two or version.three structure.  A setting  of
96       PMDA_INTERFACE_4  or  PMDA_INTERFACE_5  will  force pmdaMain to use the
97       callbacks in the version.four or version.five structure, and  similarly
98       a  PMDA_INTERFACE_6 setting forces pmdaMain to use the callbacks in the
99       version.six structure.  Any other value will result  in  an  error  and
100       termination of pmdaMain.
101
102       Note  that the use of dispatch as the interface between the pmcd(1) and
103       the methods of the PMDA allows each PMDA to be implemented as though it
104       were  a  DSO,  with pmdaMain providing a convenient wrapper that may be
105       used to convert from the DSO interface to the binary PDU (daemon  PMDA)
106       interface.
107
108       pmdaMain  executes  as a continuous loop, returning only when an end of
109       file is encountered on the PDU input file descriptor.
110

CALLBACKS

112       In addition to the  individual  PDU  processing  callbacks  -  pmdaPro‐
113       file(3), pmdaFetch(3), pmdaDesc(3), pmdaInstance(3), pmdaText(3), pmda‐
114       Store(3),  pmdaPMID(3),  pmdaName(3),  pmdaChildren(3),   and   pmdaAt‐
115       tribute(3)  there are other callbacks that can affect or inform all PDU
116       processing within a PMDA, namely check, done and end.  These  callbacks
117       should  be  set  with pmdaSetCheckCallBack, pmdaSetDoneCallBack and pm‐
118       daSetEndContextCallBack.
119
120       If not null, check is called after each PDU is received (but before  it
121       was  processed),  and  done is called after each PDU is sent.  If check
122       returns a value less than zero (typically PM_ERR_AGAIN), the  PDU  pro‐
123       cessing  is skipped and in most cases the function value is returned as
124       an error PDU to pmcd(1) - this may be used for PMDAs that require  some
125       sort  of  deferred connection or reconnect protocols for the underlying
126       sources of performance metrics, e.g. a DBMS.  The error indication from
127       check  is  not passed back to pmcd(1) in the cases where no acknowledg‐
128       ment is expected, e.g. for a PDU_PROFILE.
129
130       The end callback allows a PMDA to keep track of  state  for  individual
131       clients  that  are  requesting  it to perform actions (PDU processing).
132       Using pmdaGetContext a PMDA can determine, at  any  point,  an  integer
133       identifier  that uniquely identifies the client tools at the remote end
134       of PMCD (for local context modes,  this  identifier  is  always  zero).
135       This  becomes  very  important  for  handling event metrics, where each
136       event must be propagated once only to each interested client.  It  also
137       underlies the mechanism whereby connection information is passed to the
138       PMDA, such as the the credentials (user and group identifiers) for  the
139       client tool.
140
141       One  final  callback  mechanism  is  provided for handling the pmResult
142       built for a PDU_RESULT in response to a PDU_FETCH request.  By default,
143       pmdaMain  will  free  the pmResult once the result has been sent to the
144       pmcd(1).  For some PMDAs this is inappropriate, e.g.  the  pmResult  is
145       statically  allocated, or contains a hybrid of pinned PDU buffer infor‐
146       mation and dynamically  allocated  information.   pmdaSetResultCallBack
147       may be used to define an alternative callback from pmdaMain.
148

DIAGNOSTICS

150       These messages may be appended to the PMDA's log file:
151
152       PMDA interface version interface not supported
153                                The  interface version is not supported by pm‐
154                                daMain.
155
156       Unrecognized pdu type    The PMDA received a PDU from pmcd that it does
157                                not recognize. This may indicate that the pmcd
158                                process is using  a  more  advanced  interface
159                                than pmdaMain.
160
161       If  the  PMAPI(3) debugging control options have the ``libpmda'' option
162       set then each PDU that is received is reported in the PMDA's log file.
163

SEE ALSO

165       pmcd(1), PMAPI(3), PMDA(3), pmdaProfile(3), pmdaFetch(3),  pmdaDesc(3),
166       pmdaInstance(3),  pmdaText(3),  pmdaStore(3), pmdaPMID(3), pmdaName(3),
167       pmdaChildren(3), and pmdaAttribute(3).
168
169
170
171Performance Co-Pilot                  PCP                          PMDAMAIN(3)
Impressum