Provided by: libpcp-pmda3-dev_3.5.11_amd64 bug

NAME

       pmdaCacheStore,       pmdaCacheStoreKey,       pmdaCacheLookup,       pmdaCacheLookupName,
       pmdaCacheLookupKey, pmdaCacheOp, pmdaCachePurge  -  manage  a  cache  of  instance  domain
       information for a PMDA

C SYNOPSIS

       #include <pcp/pmapi.h>
       #include <pcp/impl.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);

       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  and  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).

       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 opqaue 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.  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  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)).

       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  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_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 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, and 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 and PMDA_CACHE_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.

                ┌────────┬─────────────────┬───────────────────────────────────────────┐
                │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 (-EDOM)                         │
                │foo bar │ foo blah        │ bad match (-EDOM)                         │
                └────────┴─────────────────┴───────────────────────────────────────────┘

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),
       pmdaSetFetchCallback(3), pmErrStr(3) and pmGetInDom(3).