1PMDACACHE(3) Library Functions Manual PMDACACHE(3)
2
6 pmdaCacheStore, pmdaCacheLookup, pmdaCacheLookupName, pmdaCacheOp,
7 pmdaCachePurge - manage a cache of instance domain information for a
8 PMDA
9
11 #include <pcp/pmapi.h>
12 #include <pcp/impl.h>
13 #include <pcp/pmda.h>
14 int pmdaCacheStore(pmInDom indom, int flags, const char *name, void
16 *private)
17 int pmdaCacheLookup(pmInDom indom, int inst, char **name, void **pri‐
18 vate)
19 int pmdaCacheLookupName(pmInDom indom, const char *name, int *inst,
20 void **private)
21 int pmdaCacheOp(pmInDom indom, int op)
22 int pmdaCachePurge(pmInDom indom, time_t recent)
23 cc ... -lpcp_pmda -lpcp
25
27 The pmdaCache family of routines provide services to support the main‐
28 tenance of complex instance domains for Performance Co-Pilot PMDAs.
29 There is potentially one cache of information for each instance domain,
30 and for each instance the cache maintains:
31 - external instance name (supplied by the PMDA)
32 - internal instance identifier (assigned by pmdaCacheStore)
33 - state, where active instances are visible and part of the current
34 instance domain, and inactive instances are hidden, but not forgot‐
35 ten; pmdaCacheStore may be used to change the state of an instance
36 - an opaque pointer to data that is associated with the instance, but
37 maintained by the PMDA
38 - the last time the cache was saved and the instance had been marked as
39 active at some point since the previous cache load or save operation
40 The semantics of a PCP instance domain require a number of rules to be
42 followed, namely:
43 1. Each internal instance identifier must be unique and in the range 0
44 to 2^31 - 1. This rule is enforced by the pmdaCache family of rou‐
45 tines.
46 2. The external instance name must be unique. When the instance name
47 contains a space, it is further constrained such that the name to
48 the left of the first space (the short name) must also be unique.
49 Refer to the INSTANCE NAME MATCHING section below. The PMDA must
50 honor this rule, the pmdaCache family of routines will detect
51 attempts to violate this rule.
52 3. Where an external instance name corresponds to some object or
53 entity, there is an expectation that the association between the
54 name and the object is fixed, e.g. ``/dev/hda'' is always the name
55 of the same disk on a particular system. This rule is perhaps the
56 responsibility of the PMDA, but is often a characteristic of the
57 environment in which the PMDA runs.
58 4. It is preferable, although not mandatory, for the association
59 between and external instance name and an internal instance identi‐
60 fier to be persistent. This rule is supported by the pmdaCache fam‐
61 ily of routines.
62 The visible interface to the cache is oriented towards the PMDA devel‐
64 oper who is most concerned about the names of instances, while the
65 details of how the rest of the PCP infrastructure expects the internal
66 instance identifiers to be managed is not relevant.
67 Instances are updated in the cache for instance domain indom by calling
69 pmdaCacheStore with the external name of the instance passed via name.
70 The opaque pointer private may be used to associate additional data
71 with the entry in the cache; if no such data is required, private
72 should be NULL. Any manipulation of the additional data (including
73 allocation or freeing) is the responsibility of the PMDA caller, as the
74 cache simply maintains the pointer to the data (passed via private).
75 The flags argument controls how the instance should be processed in the
77 cache as follows:
78 PMDA_CACHE_ADD
80 Insert the entry into the cache if it is not already there and
81 mark it active. If the entry is already in the cache mark it
82 active.
83 PMDA_CACHE_HIDE
85 Mark the entry in the cache as inactive, but remember the
86 details of the association between the external instance name
87 and the internal instance identifier. Entries that are inactive
88 will be hidden from cache traversal via PMDA_CACHE_WALK_NEXT
89 operations, but remain visible to pmdaCacheLookup and pmdaCache‐
90 LookupName requests.
91 PMDA_CACHE_CULL
93 Remove the entry from the cache.
94 On success pmdaCacheStore will return the internal instance identifier
96 of the associated cache entry. Valid instance identifiers are guaran‐
97 teed to be unique and non-negative. Failure will be indicated by a
98 negative value (suitable for decoding with pmErrStr(3)) and most likely
99 PM_ERR_INST to indicate the requested instance is not in the cache, or
100 -EINVAL to indicate a potential violation of the short name uniqueness
101 property (see the INSTANCE NAME MATCHING section below).
102 pmdaCacheLookup is used to search the entries in the cache based on the
104 internal instance identifier inst.
105 On success the return value will be PMDA_CACHE_ACTIVE or
107 PMDA_CACHE_INACTIVE (depending on the active or inactive state of the
108 cache entry), name (if not NULL) and private (if not NULL) will be set
109 to the external instance name and the associate additional data area as
110 provided when the instance was last activated via pmdaCacheStore.
111 pmdaCacheLookup failure is indicated by a negative return value suit‐
113 able for decoding with pmErrStr(3).
114 The pmdaCacheLookup interface is required by the PMDA's fetch callback
116 that is registered via pmdaSetFetchCallback(3). Here the internal
117 instance identifier is passed to the fetch callback to identifier for
118 which instance a value is required. Typical usage is shown in the code
119 fragment below.
120 static int
122 foo_callback(pmdaMetric *mdesc, unsigned int inst, pmAtomValue *atom)
123 {
124 mydata *mdp;
125 char *name;
126 int sts;
127 sts = pmdaCacheLookup(mdesc->m_desc.indom, inst, &name, (void **)&mdp);
129 /*
130 * expect sts == PMDA_CACHE_ACTIVE except for cataclysmic events
131 * use mdp as required, name may be useful for diagnostics
132 */
133 ...
134 pmdaCacheLookupName is used to search the entries in the cache based on
137 the external instance name name.
138 On success the return value will be PMDA_CACHE_ACTIVE or
140 PMDA_CACHE_INACTIVE (depending on the active or inactive state of the
141 cache entry), inst (if not NULL) and private (if not NULL) will be set
142 to the internal instance identifier and the associate additional data
143 area as provided when the instance was last activated via pmdaCache‐
144 Store.
145 pmdaCacheLookupName failure is indicated by a negative return value
147 suitable for decoding with pmErrStr(3).
148 The pmdaCacheLookupName interface is useful for PMDAs wishing to update
150 an instance domain based on the external instance names.
151 To avoid a persistent cache growing without bound, pmdaCachePurge can
153 be used to cull all entries that have not been active in the last
154 recent seconds. For performance reasons, the time accounting is impre‐
155 cise and the entries are timestamped at the time of the next cache save
156 operation after the entry has been added or marked active (refer to
157 PMDA_CACHE_SAVE and PMDA_CACHE_SYNC below). On success pmdaCachePurge
158 returns the number of culled entries, else in the case of an error the
159 return value is negative (and suitable for decoding with pmErrStr(3)).
160 pmdaCacheOp may be used to perform additional operations on the cache
162 as follows:
163 PMDA_CACHE_LOAD
165 The cache can optionally be maintained as a persistent external
166 file, so that the mapping of instance names to instance identi‐
167 fiers is persistent across executions of a PMDA. This operation
168 loads the cache from the external file, and then all new cache
169 entries are marked inactive, and the additional data pointer is
170 set to NULL. Entries loaded from the external file are checked
171 against the current cache contents and if the instance name and
172 instance identifiers match then the state in the cache (active
173 or inactive) is not changed. Should a mismatch be found (same
174 instance name and different instance identifier, or same
175 instance identifier and different instance name) then the entry
176 from the external file is ignored and a warning is issued on
177 stderr. Typically a PMDA would only perform this operation once
178 per execution.
179 PMDA_CACHE_SAVE
181 If any instance has been added to, or deleted from, the instance
182 domain since the last PMDA_CACHE_LOAD, PMDA_CACHE_SAVE or
183 PMDA_CACHE_SYNC operation, the entire cache is written to the
184 external file as a bulk operation. This operation is provided
185 for PMDAs that are not interested in using pmdaCachePurge and
186 simply want the external file to reflect the set of known
187 instances without accurate details of when they were last marked
188 active.
189 Returns the number of instances saved to the external file, else
191 0 if the external file was already up to date.
192 PMDA_CACHE_SYNC
194 Within an instance domain, if any instance has been added to, or
195 deleted from, or marked active since the last PMDA_CACHE_LOAD,
196 PMDA_CACHE_SAVE or PMDA_CACHE_SYNC operation, the entire cache
197 is written to the external file as a bulk operation. This oper‐
198 ation is similar to PMDA_CACHE_SAVE, but will save the instance
199 domain more frequently so the timestamps more accurately match
200 the semantics expected by pmdaCachePurge.
201 Returns the number of instances saved to the external file, else
203 0 if the external file was already synchronized.
204 PMDA_CACHE_CHECK
206 Returns 1 if a cache exists for the specified instance domain,
207 else 0.
208 PMDA_CACHE_REUSE
210 When a new instance is added to the cache, the default strategy
211 is to assign instance identifiers in a monotonic increasing man‐
212 ner. Once the maximum possible instance identifier value has
213 been assigned, the strategy changes to one where starting from
214 0, the next available unused instance identifier will be used.
215 Calling pmdaCacheOp with PMDA_CACHE_REUSE forces an irreversible
216 change to the second (reuse) strategy. This may be useful in
217 cases where there is a desire to restrict the allocated instance
218 identifiers to smaller values. The prevailing strategy will be
219 saved and restored across PMDA_CACHE_SAVE and PMDA_CACHE_LOAD
220 operations.
221 PMDA_CACHE_REORG
223 Reorganize the cache to allow faster retrieval of active
224 entries, and the cost of slower retrieval for inactive entries,
225 and reclaim any culled entries. The cache may be internally re-
226 organized as entries are added, so this operation is not
227 required for most PMDAs.
228 PMDA_CACHE_WALK_REWIND
230 Prepares for a traversal of the cache in ascending instance
231 identifier sequence.
232 PMDA_CACHE_WALK_NEXT
234 Fetch the next active instance identifier from the cache.
235 Requires a prior call using PMDA_CACHE_WALK_REWIND and will
236 return -1 when all instances have been processed.
237 Only one cache walk can be active at any given time, nesting
239 calls to PMDA_CACHE_WALK and PMDA_CACHE_REWIND will interfere
240 with each other.
241 PMDA_CACHE_ACTIVE
243 Changes every inactive entry in the cache to be marked active.
244 PMDA_CACHE_INACTIVE
246 Changes every active entry in the cache to be marked inactive.
247 PMDA_CACHE_CULL
249 Remove every entry from the cache.
250 PMDA_CACHE_SIZE
252 Return the number of entries in the cache (includes active,
253 inactive and any culled entries that have not yet been
254 reclaimed).
255 PMDA_CACHE_SIZE_ACTIVE
257 Return the number of active entries in the cache.
258 PMDA_CACHE_SIZE_INACTIVE
260 Return the number of inactive entries in the cache.
261 PMDA_CACHE_DUMP
263 Dump the current state of the cache on stderr.
264 pmdaCacheOp returns a non-negative value on success, and failure is
266 indicated by a negative return value (suitable for decoding with
267 pmErrStr(3)).
268
270 When the pmdaCache routines are used for particular instance domain,
271 pmdaInstance (3) and the instance domain enumeration behind
272 pmdaFetch(3) will attempt to extract instance domain information from
273 the cache, thereby avoiding reference to the pmdaIndom data structures
274 that have historically been used to define instance domains and service
275 instance requests. A PMDA can adopt a hybrid approach and choose to
276 implement some instance domains via the traditional pmdaIndom method,
277 and others via the pmdaCache approach, however attempts to manage the
278 same instance domain by both methods will result in the pmdaCache
279 method silently prevailing.
280 If all instances in a PMDA are to be serviced from a pmdaCache then a
282 pmdaIndom is not required, and the pmdaInit (3) call becomes
283 pmdaInit(dp, NULL, 0, metrictab, nmetrics);
285 However, the PMDA will need to explicitly initialize the indom field of
287 the pmDesc in the metrictab entries, as this cannot be done by
288 pmdaInit(3) if indomtab is missing entries for the instance domains
289 maintained in the cache.
290 Independent of how the instance domain is being maintained, to refresh
292 an instance domain prior to a fetch or an instance domain operation,
293 the standard methods of a ``wrapper'' to the pmdaInstance (3) and
294 pmdaFetch (3) methods should be used.
295 Refer to the simple PMDA source code for an example use of the pmda‐
297 Cache routines.
298
300 The following table summarizes the ``short name'' matching semantics
301 for an instance domain.
302 ┌────────┬─────────────────┬───────────────────────────────────────────┐
304 │name in │ pmdaCacheLookup │ result │
305 │cache │ name │ │
306 ├────────┼─────────────────┼───────────────────────────────────────────┤
307 │foodle │ foo │ no match (PM_ERR_INST) │
308 │foo │ foodle │ no match (PM_ERR_INST) │
309 │foo │ foo │ match │
310 │foo bar │ foo │ match on short name (instance identifier) │
311 │foo bar │ foo bar │ match on full name (instance identifier) │
312 │foo │ foo bar │ bad match (-EDOM) │
313 │foo bar │ foo blah │ bad match (-EDOM) │
314 └────────┴─────────────────┴───────────────────────────────────────────┘
316 Cache persistence uses files with names constructed from the indom
317 within the $PCP_VAR_DIR/config/pmda directory.
318
320 PMAPI(3), PMDA(3), pmdaInit(3), pmdaInstance(3), pmdaFetch(3), pmdaSet‐
321 FetchCallback(3), pmErrStr(3) and pmGetInDom(3).
322Performance Co-Pilot SGI PMDACACHE(3)