1PMDAINIT(3) Library Functions Manual PMDAINIT(3)
2
6 pmdaInit, pmdaRehash, pmdaSetFlags - initialize a PMDA
7
9 #include <pcp/pmapi.h>
10 #include <pcp/impl.h>
11 #include <pcp/pmda.h>
12 void pmdaInit(pmdaInterface *dispatch, pmdaIndom *indoms, int nindoms,
14 pmdaMetric *metrics, int nmetrics);
15 void pmdaRehash(pmdaExt *pmda, pmdaMetric *metrics, int nmetrics);
16 void pmdaSetFlags(pmdaInterface *dispatch, int flags);
17 cc ... -lpcp_pmda -lpcp
19
21 pmdaInit initializes a PMDA so that it is ready to receive PDUs from
22 pmcd(1). The function expects as arguments the instance domain table
23 (indoms) and the metric description table (metrics) that are initial‐
24 ized by the PMDA. The arguments nindoms and nmetrics should be set to
25 the number of instances and metrics in the tables, respectively.
26 Much of the pmdaInterface structure can be automatically initialized
28 with pmdaDaemon(3), pmdaGetOpt(3) and pmdaDSO(3). pmdaInit completes
29 the PMDA initialization phase with three operations. The first opera‐
30 tion adds the domain and instance numbers to the instance and metric
31 tables. Singular metrics (metrics without an instance domain) should
32 have the instance domain PM_INDOM_NULL set in the indom field of the
33 pmDesc structure (see pmLookupDesc(3)). Metrics with an instance do‐
34 main should set this field to be the serial number of the instance do‐
35 main in the indoms table.
36 The instance domain table may be made empty by setting indoms to NULL
38 and nindoms to 0. This allows the caller to provide custom Fetch and
39 Instance callback functions. The metric table may be made empty by
40 setting metrics to NULL and nmetrics to 0. This allows the caller to
41 provide custom Fetch and Descriptor callback functions.
42
44 For example, a PMDA has three metrics: A, B and C, and two instance do‐
45 mains X and Y, with two instances in each instance domain. The in‐
46 stance domain and metrics description tables could be defined as:
47 static pmdaInstid _X[] = {
49 { 0, "X1" }, { 1, "X2" }
50 };
51 static pmdaInstid _Y[] = {
53 { 0, "Y1" }, { 1, "Y2" }
54 };
55 static pmdaIndom indomtab[] = {
57 #define X_INDOM 0
58 { X_INDOM, 2, _X },
59 #define Y_INDOM 3
60 { Y_INDOM, 2, _Y }
61 };
62 static pmdaMetric metrictab[] = {
64 /* A */
65 { (void *)0,
66 { PMDA_PMID(0,0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT,
67 { 0,0,0,0,0,0} }, },
68 /* B */
69 { (void *)0,
70 { PMDA_PMID(0,1), PM_TYPE_U32, X_INDOM, PM_SEM_INSTANT,
71 { 0,0,0,0,0,0} }, },
72 /* C */
73 { (void *)0,
74 { PMDA_PMID(0,2), PM_TYPE_DOUBLE, Y_INDOM, PM_SEM_INSTANT,
75 { 0,1,0,0,PM_TIME_SEC,0} }, }
76 };
77 The metric description table defines metric A with no instance domain,
79 metric B with instance domain X and metric C with instance domain Y.
80 Metric C has units of seconds, while the other metrics have no units
81 (simple counters). pmdaInit will take these structures and assign the
82 PMDA(3) domain number to the it_indom field of each instance domain.
83 This identifier also replaces the indom field of all metrics which have
84 that instance domain, so that they are correctly associated.
85 The second stage opens the help text file, if one was specified with
87 the -h command line option (see pmdaGetOpt(3)) or as a helptext argu‐
88 ment to pmdaDSO(3) or pmdaDaemon(3).
89 The final stage involves preparing the metric table lookup strategy.
91
93 When fetch and descriptor requests are made of the PMDA, each requested
94 PMID must be mapped to a metric table entry. There are currently three
95 strategies for performing this mapping - direct, linear and hashed.
96 Each has its own set of tradeoffs and an appropriate strategy should be
97 selected for each PMDA.
98 If all of the metric PMID item numbers correspond to the position in
100 the metrics table, then direct mapping is used. This is the most effi‐
101 cient of the lookup functions as it involves a direct array index (no
102 additional memory is required nor any additional processing overhead).
103 If the PMID numbering requirement is met by the PMDA, it is ideal.
104 This strategy can be explicitly requested by calling pmdaSetFlags(pmda,
105 PMDA_FLAG_EXT_DIRECT) before calling pmdaInit. In this case, if the
106 direct mapping is not possible (e.g. due to an oversight on the part of
107 the PMDA developer), a warning is logged and the linear strategy is
108 used instead.
109 The second strategy (linear search) is the default, when a direct map‐
111 ping cannot be established. This provides greater flexibility in the
112 PMID numbering scheme, as the PMDA item numbers do not have to be
113 unique (hence, the PMID cluster numbers can be used more freely, which
114 is often extremely convenient for the PMDA developer). However, lookup
115 involves a linear walk from the start of the metric table until a
116 matching PMID is found, for each requested PMID in a request.
117 The third strategy (hash lookup) can be requested by calling pmdaSet‐
119 Flags(pmda, PMDA_FLAG_EXT_HASHED) before calling pmdaInit. This strat‐
120 egy is most useful for PMDAs with large numbers of metrics (many hun‐
121 dreds, or thousands). Such PMDAs will almost always use the cluster
122 numbering scheme, so the direct lookup scheme becomes inappropriate.
123 They may also be prepared to sacrifice a small amount of additional
124 memory for a hash table, mapping PMID to metric table offsets, to speed
125 up lookups in their vast metric tables.
126 This final strategy can also be used by PMDAs serving up dynamically
128 numbered metrics. For this case, the pmdaRehash function should be
129 used to replace the metric table when new metrics become available, or
130 existing metrics are removed. The PMID hash mapping will be recomputed
131 at the same time that the new metric table is installed.
132
135 pmdaInit will set dispatch->status to a value less than zero if there
136 is an error that would prevent the PMDA(3) from successfully running.
137 pmcd(1) will terminate the connection to the PMDA(3) if this occurs.
138 pmdaInit may issue any of these messages:
140 PMDA interface version interface not supported
142 The interface version is not supported by pmdaInit.
143 Using pmdaFetch() but fetch call back not set
145 The fetch callback, pmdaFetch(3), requires an additional
146 callback to be provided using pmdaSetFetchCallBack(3).
147 Illegal instance domain inst for metric pmid
149 The instance domain inst that was specified for metric
150 pmid is not within the range of the instance domain ta‐
151 ble.
152 No help text path specified
154 The help text callback, pmdaText(3), requires a help
155 text file for the metrics to have been opened, however
156 no path to the help text was specified as a command line
157 option, or as an argument to pmdaDSO(3) or pmdaDae‐
158 mon(3). This message is only a warning.
159 Direct mapping for metrics disabled @ num
161 The unit numbers of the metrics did not correspond to
162 the index in the metric description table. The direct
163 mapping failed for metric number num in the metrics ta‐
164 ble. This is less efficient but is not fatal and the
165 message is only a warning.
166 Hashed mapping for metrics disabled @ num
168 A memory allocation failure occurred while building the
169 hash table to index the metric description table. This
170 is a non-fatal warning message - a fallback to linear
171 searching will be automatically performed should this
172 situation arise.
173
175 The PMDA must be using PMDA_INTERFACE_2 or later, as specified in the
176 call to pmdaDSO(3) or pmdaDaemon(3).
177
179 newhelp(1), pmcd(1), PMAPI(3), PMDA(3), pmdaDaemon(3), pmdaDSO(3),
180 pmdaFetch(3), pmdaGetOpt(3), pmdaText(3) and pmLookupDesc(3).
181Performance Co-Pilot PCP PMDAINIT(3)