Movatterモバイル変換

pmdacache(3) — Linux manual page

PMDACACHE(3)             Library Functions ManualPMDACACHE(3)

NAME        top

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

C SYNOPSIS        top

#include <pcp/pmapi.h>#include <pcp/pmda.h>int pmdaCacheStore(pmInDomindom, intflags, const char *name,void *private);int pmdaCacheStoreKey(pmInDomindom, intflags, const char *name,intkeylen, const void *key, void *private);int pmdaCacheLookup(pmInDomindom, intinst, char **name,void **private);int pmdaCacheLookupName(pmInDomindom, const char *name,int *inst, void **private);int pmdaCacheLookupKey(pmInDomindom, const char *name,intkeylen, const void *key, char **oname,int *inst, void **private);int pmdaCacheOp(pmInDomindom, intop);int pmdaCachePurge(pmInDomindom, time_trecent);int pmdaCachePurgeCallback(pmInDomindom, time_trecent,void (*callback)(void *));int pmdaCacheResize(pmInDomindom, intmaximum);cc ... -lpcp_pmda -lpcp

DESCRIPTION        top

       ThepmdaCachefamily 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 in‐       stance domain, and for each instance the cache maintains:       - external instance name (supplied by the PMDA)       - internal instance identifier (assigned bypmdaCacheStoreor cal‐         culated from a ``hint'' bypmdaCacheStoreKey)       - state, whereactiveinstances are visible and part of the cur‐         rent instance domain, andinactiveinstances are hidden, but not         forgotten;pmdaCacheStoreorpmdaCacheStoreKeymay 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'' topmdaCache‐StoreKeywhen guessing the initial internal instance identifier       - the last time the cache was saved and the instance had been         marked asactiveat 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 thepmdaCache          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, thepmdaCachefamily 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 charac‐          teristic 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 thepm‐daCachefamily 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 thepmdaCachefamily 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 ex‐       pects the internal instance identifiers to be managed is not rele‐       vant.       Instances are updated in the cache for instance domainindom by       callingpmdaCacheStoreorpmdaCacheStoreKeywith the external name       of the instance passed vianame.  The opaque pointerprivate may       be used to associate additional data with the entry in the cache;       if no such data is required,private should be NULL.  Any manipu‐       lation of the additional data (including allocation or freeing) is       the responsibility of the PMDA caller, as the cache simply main‐       tains the pointer to the data (passed viaprivate).       The upper bound for identifiers allocated for any givenindom       cache can be optionally reduced from the default (2^31 - 1) to       some lessermaximum, usingpmdaCacheResize.  Thismaximum will       then be persisted and restored in the usual manner, and can thus       be associated permanently with a cache once set.  This has appli‐       cations 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 alloca‐       tion 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,pmdaCacheStoreKeymay be used.       In this case, an initial ``hint'' for the instance identifier is       provided as an opaque key via the firstkeylen bytes inkey (which       could be any sort of data, including binary values) else ifkeylen       is less than 1 orkey isNULLthenname is used as the ``hint''.       The ``hint'' is hashed to produce an initial instance identifier       in the range 0 to 2^31 - 1 (or lessermaximum, if set).  If this       instance identifier is already allocated, then the value is re‐       hashed.  This procedure is repeated until an unallocated instance       identifier is found, orpmdaCacheStoreKeygives up and returnsPM_ERR_GENERIC.  For each instance domain, the ``hint'' must be       unique across all instances, elsepmdaCacheStoreKeyreturnsPM_ERR_INST.       Theflags 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 itactive.  If the entry is already in the cache              mark itactive.       PMDA_CACHE_HIDE              Mark the entry in the cache asinactive, but remember the              details of the association between the external instance              name and the internal instance identifier.  Entries that              areinactivewill be hidden from cache traversal via PM‐              DA_CACHE_WALK_NEXT operations, but remain visible topmda‐CacheLookup,pmdaCacheLookupNameandpmdaCacheLookupKeyre‐              quests.       PMDA_CACHE_CULL              Remove the entry from the cache.       On successpmdaCacheStoreorpmdaCacheStoreKeywill return the in‐       ternal 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 decod‐       ing withpmErrStr(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).pmdaCacheLookupis used to search the entries in the cache based       on the internal instance identifierinst.       On success the return value will be PMDA_CACHE_ACTIVE or PM‐       DA_CACHE_INACTIVE (depending on theactiveorinactivestate of       the cache entry),name (if not NULL) andprivate (if not NULL)       will be set to the external instance name and the associate addi‐       tional data area as provided when the instance was last activated       viapmdaCacheStoreorpmdaCacheStoreKey.pmdaCacheLookupfailure is indicated by a negative return value       suitable for decoding withpmErrStr(3).       ThepmdaCacheLookupinterface is required by the PMDA's fetch       callback that is registered viapmdaSetFetchCallBack(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 intfoo_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*/...pmdaCacheLookupNameis used to search the entries in the cache       based on the external instance namename.       On success the return value will be PMDA_CACHE_ACTIVE or PM‐       DA_CACHE_INACTIVE (depending on theactiveorinactivestate of       the cache entry),inst (if not NULL) andprivate (if not NULL)       will be set to the internal instance identifier and the associate       additional data area as provided when the instance was last acti‐       vated viapmdaCacheStoreorpmdaCacheStoreKey.pmdaCacheLookupNamefailure is indicated by a negative return val‐       ue suitable for decoding withpmErrStr(3).       ThepmdaCacheLookupNameinterface is useful for PMDAs wishing to       update an instance domain based on the external instance names.pmdaCacheLookupKeyis used to search the entries in the cache       based on an opaque key (or ``hint'') previously used in a call topmdaCacheStoreKey.  The ``hint'' is provided via the firstkeylen       bytes inkey.  For symmetry withpmdaCacheStoreKey, ifkeylen is       less than 1 orkey isNULLthenname is used as the ``hint'' (al‐       though the results will be the same as callingpmdaCacheLookupName       in this case).       On success the return value will be PMDA_CACHE_ACTIVE or PM‐       DA_CACHE_INACTIVE (depending on theactiveorinactivestate of       the cache entry),oname (if not NULL),inst (if not NULL) andpri‐vate (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 viapmda‐CacheStoreorpmdaCacheStoreKey.pmdaCacheLookupKeyfailure is indicated by a negative return value       suitable for decoding withpmErrStr(3).       To avoid a persistent cache growing without bound,pmdaCachePurge       can be used to cull all entries that havenot beenactivein the       lastrecent seconds.  For performance reasons, the time accounting       is imprecise and the entries are timestamped at the time of the       next cache save operationafter the entry has been added or markedactive(refer to PMDA_CACHE_SAVE, PMDA_CACHE_WRITE and PM‐       DA_CACHE_SYNC below).  On successpmdaCachePurgereturns the num‐       ber of culled entries, else in the case of an error the return       value is negative (and suitable for decoding withpmErrStr(3)).       ThepmdaCachePurgeCallbackfunction is similar topmdaCachePurge       except that acallback function will also be called with thepri‐vate data pointer associated with the cache entry to be culled.       The callback is not made ifprivate isNULL.  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.pmdaCacheOpmay be used to perform additional operations on the       cache as follows:       PMDA_CACHE_LOAD              The cache can optionally be maintained as a persistent ex‐              ternal file, so that the mapping of instance names to in‐              stance identifiers is persistent across executions of a PM‐              DA.  This operation loads the cache from the external file,              and then all new cache entries are markedinactive, 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 iden‐              tifiers match then the state in the cache (activeorinac‐tive) is not changed. Should a mismatch be found (same in‐              stance name and different instance identifier, or same in‐              stance 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 onstderr.  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 in‐              stance domain since the last PMDA_CACHE_LOAD, PM‐              DA_CACHE_SAVE, PMDA_CACHE_WRITE or PMDA_CACHE_SYNC opera‐              tion, theentire cache is written to the external file as a              bulk operation.  This operation is provided for PMDAs that              arenot interested in usingpmdaCachePurgeand simply want              the external file to reflect the set of known instances              without accurate details of when they were last markedac‐tive.              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 theentire cache is un‐              conditionally written to the external file as a bulk opera‐              tion, 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 com‐              parisons are not terminated at the first space but rather              the entire string is used for matching.  These are spe‐              cialised caches not useful for general purpose instance do‐              main handling.       PMDA_CACHE_SYNC              Within an instance domain, if any instance has been added              to, or deleted from, or markedactivesince the last PM‐              DA_CACHE_LOAD, PMDA_CACHE_SAVE, PMDA_CACHE_WRITE or PM‐              DA_CACHE_SYNC operation, theentire cache is written to the              external file as a bulk operation.  This operation is simi‐              lar to PMDA_CACHE_SAVE, but will save the instance domain              more frequently so the timestamps more accurately match the              semantics expected bypmdaCachePurge.              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 do‐              main, 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 in‐              stance identifier will be used.  CallingpmdaCacheOpwith              PMDA_CACHE_REUSE forces an irreversible change to a second              (reuse) strategy where the next unallocated instance iden‐              tifier will be used.  This may be useful in cases where              there is a desire to restrict the allocated instance iden‐              tifiers to smaller values.  The prevailing strategy will be              saved and restored across PMDA_CACHE_SAVE and PM‐              DA_CACHE_LOAD operations.  IfpmdaCacheStoreKeyis ever              used, the associated instance domain will be changed to PM‐              DA_CACHE_REUSE mode.       PMDA_CACHE_REORG              Reorganize the cache to allow faster retrieval ofactive              entries, at the cost of slower retrieval forinactiveen‐              tries, and reclaim any culled entries.  The cache may be              internally re-organized as entries are added, so this oper‐              ation 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 nextactiveinstance 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, nest‐              ing calls to PMDA_CACHE_WALK_NEXT and PM‐              DA_CACHE_WALK_REWIND will interfere with each other.       PMDA_CACHE_ACTIVE              Changesevery inactiveentry in the cache to be markedac‐tive.       PMDA_CACHE_INACTIVE              Changesevery activeentry in the cache to be markedinac‐tive.       PMDA_CACHE_CULL              Removeeveryentry from the cache.       PMDA_CACHE_SIZE              Return the number of entries in the cache (includesactive,inactiveand any culled entries that have not yet been re‐              claimed).       PMDA_CACHE_SIZE_ACTIVE              Return the number ofactiveentries in the cache.       PMDA_CACHE_SIZE_INACTIVE              Return the number ofinactiveentries in the cache.       PMDA_CACHE_DUMP              Dump the current state of the cache onstderr.       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 frompmdaCacheStoreKey.pmdaCacheOpreturns a non-negative value on success, and failure       is indicated by a negative return value (suitable for decoding       withpmErrStr(3)).

OTHER CONSIDERATIONS        top

       When thepmdaCacheroutines are used for particular instance do‐       main,pmdaInstance(3) and the instance domain enumeration behindpmdaFetch(3) will attempt to extract instance domain information       from the cache, thereby avoiding reference to thepmdaIndomdata       structures that have historically been used to define instance do‐       mains and service instance requests.  A PMDA can adopt a hybrid       approach and choose to implement some instance domains via the       traditionalpmdaIndommethod, and others via thepmdaCacheap‐       proach, however attempts to manage thesame instance domain by       both methods will result in thepmdaCachemethod silently prevail‐       ing.       Ifallinstances in a PMDA are to be serviced from apmdaCache       then apmdaIndomis not required, and thepmdaInit(3) call becomespmdaInit(dp, NULL, 0, metrictab, nmetrics);       However, the PMDA will need to explicitly initialize theindom       field of thepmDescin themetrictab entries, as this cannot be       done bypmdaInit(3) ifindomtab is missing entries for the in‐       stance domains maintained in the cache.       Independent of how the instance domain is being maintained, to re‐       fresh an instance domain prior to a fetch or an instance domain       operation, the standard methods of a ``wrapper'' to thepmdaInstance(3) andpmdaFetch(3) methods should be used.       Refer to thesimplePMDA source code for an example use of thepm‐daCacheroutines.       When usingpmdaCacheStoreKey, 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 struc‐       ture used for thekey is an array of 32-bit integers, thenhtonl(3) should be used on each element of the array before call‐       ingpmdaCacheStoreKeyorpmdaCacheLookupKey.

INSTANCE NAME MATCHING        top

       The following table summarizes the ``short name'' matching seman‐       tics 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        top

       Cache persistence uses files with names constructed from theindom       within the$PCP_VAR_DIR/config/pmdadirectory.

SEE ALSO        top

BYTEORDER(3),PMAPI(3),PMDA(3),pmdaInit(3),pmdaInstance(3),pmdaFetch(3),pmdaLabel(3),pmErrStr(3) andpmGetInDom(3).

COLOPHON        top

       This page is part of thePCP (Performance Co-Pilot) project.  In‐       formation about the project can be found at ⟨http://www.pcp.io/⟩.       If you have a bug report for this manual page, send it to       pcp@groups.io.  This page was obtained from the project's upstream       Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on       2025-08-11.  (At that time, the date of the most recent commit       that was found in the repository was 2025-08-11.)  If you discover       any rendering problems in this HTML version of the page, or you       believe there is a better or more up-to-date source for the page,       or you have corrections or improvements to the information in this       COLOPHON (which isnot part of the original manual page), send a       mail to man-pages@man7.orgPerformance Co-Pilot               PCPPMDACACHE(3)

Pages that refer to this page:indomcachectl(1), pmdainstance(3), pmjsonget(3)

HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH.