Man Linux: Main Page and Category List

NAME

       pmdaCacheStore,   pmdaCacheLookup,   pmdaCacheLookupName,  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  pmdaCacheLookup(pmInDom  indom,  int  inst,  char   **name,   void
       **private)
       int  pmdaCacheLookupName(pmInDom  indom,  const  char *name, 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)
       - state,  where  active  instances  are visible and part of the current
         instance  domain,  and  inactive  instances  are  hidden,   but   not
         forgotten;  pmdaCacheStore  may  be  used  to  change the state of an
         instance
       - an opaque pointer to data that is associated with the  instance,  but
         maintained by the PMDA
       - 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.

       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 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 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   and
              pmdaCacheLookupName requests.

       PMDA_CACHE_CULL
              Remove the entry from the cache.

       On  success pmdaCacheStore 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.

       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.

       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.

       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)  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  the  second (reuse) strategy.  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.

       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.

       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.

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

       PMAPI(3),    PMDA(3),   pmdaInit(3),   pmdaInstance(3),   pmdaFetch(3),
       pmdaSetFetchCallback(3), pmErrStr(3) and pmGetInDom(3).