Provided by: libpcp3-dev_6.3.1-1_amd64 
NAME
pmdaCacheStore, pmdaCacheStoreKey, pmdaCacheLookup, pmdaCacheLookupName,
pmdaCacheLookupKey, pmdaCacheOp, pmdaCachePurge, pmdaCachePurgeCallback, pmdaCacheResize -
manage a cache of instance domain information for a PMDA
C SYNOPSIS
#include <pcp/pmapi.h>
#include <pcp/pmda.h>
int pmdaCacheStore(pmInDom indom, int flags, const char *name, void *private);
int pmdaCacheStoreKey(pmInDom indom, int flags, const char *name, int keylen, const
void *key, void *private);
int pmdaCacheLookup(pmInDom indom, int inst, char **name, void **private);
int pmdaCacheLookupName(pmInDom indom, const char *name, int *inst, void **private);
int pmdaCacheLookupKey(pmInDom indom, const char *name, int keylen, const void *key, char
**oname, int *inst, void **private);
int pmdaCacheOp(pmInDom indom, int op);
int pmdaCachePurge(pmInDom indom, time_t recent);
int pmdaCachePurgeCallback(pmInDom indom, time_t recent, void (*callback)(void *));
int pmdaCacheResize(pmInDom indom, int maximum);
cc ... -lpcp_pmda -lpcp
DESCRIPTION
The pmdaCache family of routines provide services to support the maintenance of complex
instance domains for Performance Co-Pilot PMDAs. There is potentially one cache of
information for each instance domain, and for each instance the cache maintains:
- external instance name (supplied by the PMDA)
- internal instance identifier (assigned by pmdaCacheStore or calculated from a ``hint''
by pmdaCacheStoreKey)
- state, where active instances are visible and part of the current instance domain, and
inactive instances are hidden, but not forgotten; pmdaCacheStore or pmdaCacheStoreKey
may be used to change the state of an instance
- an optional opaque pointer to data that is associated with the instance, but maintained
by the PMDA
- an optional opaque key that is used as a ``hint'' to pmdaCacheStoreKey when guessing the
initial internal instance identifier
- the last time the cache was saved and the instance had been marked as active at some
point since the previous cache load or save operation
The semantics of a PCP instance domain require a number of rules to be followed, namely:
1. Each internal instance identifier must be unique and in the range 0 to 2^31 - 1. This
rule is enforced by the pmdaCache family of routines.
2. The external instance name must be unique. When the instance name contains a space, it
is further constrained such that the name to the left of the first space (the short
name) must also be unique. Refer to the INSTANCE NAME MATCHING section below. The
PMDA must honor this rule, the pmdaCache family of routines will detect attempts to
violate this rule.
3. Where an external instance name corresponds to some object or entity, there is an
expectation that the association between the name and the object is fixed, e.g.
``/dev/hda'' is always the name of the same disk on a particular system. This rule is
perhaps the responsibility of the PMDA, but is often a characteristic of the
environment in which the PMDA runs.
4. It is preferable, although not mandatory, for the association between an external
instance name and an internal instance identifier to be persistent. This rule is
supported by the pmdaCache family of routines.
5. When opaque keys are used, the values of the keys must be unique across all instances
within an instance domain. This rule is enforced by the pmdaCache family of routines.
The visible interface to the cache is oriented towards the PMDA developer who is most
concerned about the names of instances, while the details of how the rest of the PCP
infrastructure expects the internal instance identifiers to be managed is not relevant.
Instances are updated in the cache for instance domain indom by calling pmdaCacheStore or
pmdaCacheStoreKey with the external name of the instance passed via name. The opaque
pointer private may be used to associate additional data with the entry in the cache; if
no such data is required, private should be NULL. Any manipulation of the additional data
(including allocation or freeing) is the responsibility of the PMDA caller, as the cache
simply maintains the pointer to the data (passed via private).
The upper bound for identifiers allocated for any given indom cache can be optionally
reduced from the default (2^31 - 1) to some lesser maximum, using pmdaCacheResize. This
maximum will then be persisted and restored in the usual manner, and can thus be
associated permanently with a cache once set. This has applications when using these
interfaces as general purpose identifier caches, and is less applicable when using them
for instance domain caching.
For cases where the PMDA developer wishes to influence the allocation of internal instance
identifiers, e.g. for instance domains with more than one natural dimension, or where
there is a desire to allocate the same instance identifier each time the PMDA is started,
even on different hosts, pmdaCacheStoreKey may be used. In this case, an initial ``hint''
for the instance identifier is provided as an opaque key via the first keylen bytes in key
(which could be any sort of data, including binary values) else if keylen is less than 1
or key is NULL then name is used as the ``hint''. The ``hint'' is hashed to produce an
initial instance identifier in the range 0 to 2^31 - 1 (or lesser maximum, if set). If
this instance identifier is already allocated, then the value is rehashed. This procedure
is repeated until an unallocated instance identifier is found, or pmdaCacheStoreKey gives
up and returns PM_ERR_GENERIC. For each instance domain, the ``hint'' must be unique
across all instances, else pmdaCacheStoreKey returns PM_ERR_INST.
The flags argument controls how the instance should be processed in the cache as follows:
PMDA_CACHE_ADD
Insert the entry into the cache if it is not already there and mark it active. If
the entry is already in the cache mark it active.
PMDA_CACHE_HIDE
Mark the entry in the cache as inactive, but remember the details of the
association between the external instance name and the internal instance
identifier. Entries that are inactive will be hidden from cache traversal via
PMDA_CACHE_WALK_NEXT operations, but remain visible to pmdaCacheLookup,
pmdaCacheLookupName and pmdaCacheLookupKey requests.
PMDA_CACHE_CULL
Remove the entry from the cache.
On success pmdaCacheStore or pmdaCacheStoreKey will return the internal instance
identifier of the associated cache entry. Valid instance identifiers are guaranteed to be
unique and non-negative. Failure will be indicated by a negative value (suitable for
decoding with pmErrStr(3)) and most likely PM_ERR_INST to indicate the requested instance
is not in the cache, or -EINVAL to indicate a potential violation of the short name
uniqueness property (see the INSTANCE NAME MATCHING section below).
pmdaCacheLookup is used to search the entries in the cache based on the internal instance
identifier inst.
On success the return value will be PMDA_CACHE_ACTIVE or PMDA_CACHE_INACTIVE (depending on
the active or inactive state of the cache entry), name (if not NULL) and private (if not
NULL) will be set to the external instance name and the associate additional data area as
provided when the instance was last activated via pmdaCacheStore or pmdaCacheStoreKey.
pmdaCacheLookup failure is indicated by a negative return value suitable for decoding with
pmErrStr(3).
The pmdaCacheLookup interface is required by the PMDA's fetch callback that is registered
via pmdaSetFetchCallBack(3). Here the internal instance identifier is passed to the fetch
callback to identifier for which instance a value is required. Typical usage is shown in
the code fragment below.
static int
foo_callback(pmdaMetric *mdesc, unsigned int inst, pmAtomValue *atom)
{
mydata *mdp;
char *name;
int sts;
sts = pmdaCacheLookup(mdesc->m_desc.indom, inst, &name, (void **)&mdp);
/*
* expect sts == PMDA_CACHE_ACTIVE except for cataclysmic events
* use mdp as required, name may be useful for diagnostics
*/
...
pmdaCacheLookupName is used to search the entries in the cache based on the external
instance name name.
On success the return value will be PMDA_CACHE_ACTIVE or PMDA_CACHE_INACTIVE (depending on
the active or inactive state of the cache entry), inst (if not NULL) and private (if not
NULL) will be set to the internal instance identifier and the associate additional data
area as provided when the instance was last activated via pmdaCacheStore or
pmdaCacheStoreKey.
pmdaCacheLookupName failure is indicated by a negative return value suitable for decoding
with pmErrStr(3).
The pmdaCacheLookupName interface is useful for PMDAs wishing to update an instance domain
based on the external instance names.
pmdaCacheLookupKey is used to search the entries in the cache based on an opaque key (or
``hint'') previously used in a call to pmdaCacheStoreKey. The ``hint'' is provided via
the first keylen bytes in key. For symmetry with pmdaCacheStoreKey, if keylen is less
than 1 or key is NULL then name is used as the ``hint'' (although the results will be the
same as calling pmdaCacheLookupName in this case).
On success the return value will be PMDA_CACHE_ACTIVE or PMDA_CACHE_INACTIVE (depending on
the active or inactive state of the cache entry), oname (if not NULL), inst (if not NULL)
and private (if not NULL) will be set to the external instance name, the internal instance
identifier and the associate additional data area as provided when the instance was last
activated via pmdaCacheStore or pmdaCacheStoreKey.
pmdaCacheLookupKey failure is indicated by a negative return value suitable for decoding
with pmErrStr(3).
To avoid a persistent cache growing without bound, pmdaCachePurge can be used to cull all
entries that have not been active in the last recent seconds. For performance reasons,
the time accounting is imprecise and the entries are timestamped at the time of the next
cache save operation after the entry has been added or marked active (refer to
PMDA_CACHE_SAVE, PMDA_CACHE_WRITE and PMDA_CACHE_SYNC below). On success pmdaCachePurge
returns the number of culled entries, else in the case of an error the return value is
negative (and suitable for decoding with pmErrStr(3)).
The pmdaCachePurgeCallback function is similar to pmdaCachePurge except that a callback
function will also be called with the private data pointer associated with the cache entry
to be culled. The callback is not made if private is NULL. This would typically be used
to free the private data when the associated entry is purged in PMDAs that do not
separately maintain any references to the private data.
pmdaCacheOp may be used to perform additional operations on the cache as follows:
PMDA_CACHE_LOAD
The cache can optionally be maintained as a persistent external file, so that the
mapping of instance names to instance identifiers is persistent across executions
of a PMDA. This operation loads the cache from the external file, and then all new
cache entries are marked inactive, and the additional data pointer is set to NULL.
Entries loaded from the external file are checked against the current cache
contents and if the instance name and instance identifiers match then the state in
the cache (active or inactive) is not changed. Should a mismatch be found (same
instance name and different instance identifier, or same instance identifier and
different instance name, or some but not all of the instance identifier, the
instance name and the ``hint'' match) then the entry from the external file is
ignored and a warning is issued on stderr. Typically a PMDA would only perform
this operation once per execution.
PMDA_CACHE_SAVE
If any instance has been added to, or deleted from, the instance domain since the
last PMDA_CACHE_LOAD, PMDA_CACHE_SAVE, PMDA_CACHE_WRITE or PMDA_CACHE_SYNC
operation, the entire cache is written to the external file as a bulk operation.
This operation is provided for PMDAs that are not interested in using
pmdaCachePurge and simply want the external file to reflect the set of known
instances without accurate details of when they were last marked active.
Returns the number of instances saved to the external file, else 0 if the external
file was already up to date.
PMDA_CACHE_WRITE
A variant of PMDA_CACHE_SAVE where the entire cache is unconditionally written to
the external file as a bulk operation, independent of any previous cache operations
or the state of the cache.
PMDA_CACHE_STRINGS
Annotates this cache as being a special-purpose cache used for string de-
duplication in PMDAs exporting large numbers of string valued metrics. This can be
used to reduce the memory footprint of the PMDA (duplicate strings hash to the same
bucket, and are stored in memory once only). Key comparisons are not terminated at
the first space but rather the entire string is used for matching. These are
specialised caches not useful for general purpose instance domain handling.
PMDA_CACHE_SYNC
Within an instance domain, if any instance has been added to, or deleted from, or
marked active since the last PMDA_CACHE_LOAD, PMDA_CACHE_SAVE, PMDA_CACHE_WRITE or
PMDA_CACHE_SYNC operation, the entire cache is written to the external file as a
bulk operation. This operation is similar to PMDA_CACHE_SAVE, but will save the
instance domain more frequently so the timestamps more accurately match the
semantics expected by pmdaCachePurge.
Returns the number of instances saved to the external file, else 0 if the external
file was already synchronized.
PMDA_CACHE_CHECK
Returns 1 if a cache exists for the specified instance domain, else 0.
PMDA_CACHE_REUSE
When a new instance is added to the cache, the default strategy is to assign
instance identifiers in a monotonic increasing manner. Once the maximum possible
instance identifier value has been assigned, the strategy changes to one where
starting from 0, the next available unused instance identifier will be used.
Calling pmdaCacheOp with PMDA_CACHE_REUSE forces an irreversible change to a second
(reuse) strategy where the next unallocated instance identifier will be used. This
may be useful in cases where there is a desire to restrict the allocated instance
identifiers to smaller values. The prevailing strategy will be saved and restored
across PMDA_CACHE_SAVE and PMDA_CACHE_LOAD operations. If pmdaCacheStoreKey is
ever used, the associated instance domain will be changed to PMDA_CACHE_REUSE mode.
PMDA_CACHE_REORG
Reorganize the cache to allow faster retrieval of active entries, at the cost of
slower retrieval for inactive entries, and reclaim any culled entries. The cache
may be internally re-organized as entries are added, so this operation is not
required for most PMDAs.
PMDA_CACHE_WALK_REWIND
Prepares for a traversal of the cache in ascending instance identifier sequence.
PMDA_CACHE_WALK_NEXT
Fetch the next active instance identifier from the cache. Requires a prior call
using PMDA_CACHE_WALK_REWIND and will return -1 when all instances have been
processed.
Only one cache walk can be active at any given time, nesting calls to
PMDA_CACHE_WALK_NEXT and PMDA_CACHE_WALK_REWIND will interfere with each other.
PMDA_CACHE_ACTIVE
Changes every inactive entry in the cache to be marked active.
PMDA_CACHE_INACTIVE
Changes every active entry in the cache to be marked inactive.
PMDA_CACHE_CULL
Remove every entry from the cache.
PMDA_CACHE_SIZE
Return the number of entries in the cache (includes active, inactive and any culled
entries that have not yet been reclaimed).
PMDA_CACHE_SIZE_ACTIVE
Return the number of active entries in the cache.
PMDA_CACHE_SIZE_INACTIVE
Return the number of inactive entries in the cache.
PMDA_CACHE_DUMP
Dump the current state of the cache on stderr.
PMDA_CACHE_DUMP_ALL
Like PMDA_CACHE_DUMP, but also dump the internal hashing structures used to support
lookup by instance name, lookup by instance identifier and the collision statistics
for ``hint'' hashing from pmdaCacheStoreKey.
pmdaCacheOp returns a non-negative value on success, and failure is indicated by a
negative return value (suitable for decoding with pmErrStr(3)).
OTHER CONSIDERATIONS
When the pmdaCache routines are used for particular instance domain, pmdaInstance(3) and
the instance domain enumeration behind pmdaFetch(3) will attempt to extract instance
domain information from the cache, thereby avoiding reference to the pmdaIndom data
structures that have historically been used to define instance domains and service
instance requests. A PMDA can adopt a hybrid approach and choose to implement some
instance domains via the traditional pmdaIndom method, and others via the pmdaCache
approach, however attempts to manage the same instance domain by both methods will result
in the pmdaCache method silently prevailing.
If all instances in a PMDA are to be serviced from a pmdaCache then a pmdaIndom is not
required, and the pmdaInit(3) call becomes
pmdaInit(dp, NULL, 0, metrictab, nmetrics);
However, the PMDA will need to explicitly initialize the indom field of the pmDesc in the
metrictab entries, as this cannot be done by pmdaInit(3) if indomtab is missing entries
for the instance domains maintained in the cache.
Independent of how the instance domain is being maintained, to refresh an instance domain
prior to a fetch or an instance domain operation, the standard methods of a ``wrapper'' to
the pmdaInstance(3) and pmdaFetch(3) methods should be used.
Refer to the simple PMDA source code for an example use of the pmdaCache routines.
When using pmdaCacheStoreKey, if there is a desire to ensure the given ``hint'' generates
the same initial instance identifier across all platforms, then the caller should ensure
the endian and word-size issues are considered, e.g. if the natural data structure used
for the key is an array of 32-bit integers, then htonl(3) should be used on each element
of the array before calling pmdaCacheStoreKey or pmdaCacheLookupKey.
INSTANCE NAME MATCHING
The following table summarizes the ``short name'' matching semantics for an instance
domain (caches other than PMDA_CACHE_STRINGS style).
┌────────┬─────────────────┬───────────────────────────────────────────┐
│name in │ pmdaCacheLookup │ result │
│cache │ name │ │
├────────┼─────────────────┼───────────────────────────────────────────┤
│foodle │ foo │ no match (PM_ERR_INST) │
│foo │ foodle │ no match (PM_ERR_INST) │
│foo │ foo │ match │
│foo bar │ foo │ match on short name (instance identifier) │
│foo bar │ foo bar │ match on full name (instance identifier) │
│foo │ foo bar │ bad match (-EINVAL) │
│foo bar │ foo blah │ bad match (-EINVAL) │
└────────┴─────────────────┴───────────────────────────────────────────┘
FILES
Cache persistence uses files with names constructed from the indom within the
$PCP_VAR_DIR/config/pmda directory.
SEE ALSO
BYTEORDER(3), PMAPI(3), PMDA(3), pmdaInit(3), pmdaInstance(3), pmdaFetch(3), pmdaLabel(3),
pmErrStr(3) and pmGetInDom(3).