# pmdainit

## NAME



           **pmdaInit** , **pmdaRehash** , **pmdaSetData** , **pmdaExtGetData** , **pmdaExtSetData** ,
           **pmdaSetFlags** , **pmdaSetCommFlags** , **pmdaExtSetFlags** - initialize a
           PMDA
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
           **#include <pcp/pmda.h>**
    
           **void pmdaInit(pmdaInterface ***_dispatch_**, pmdaIndom ***_indoms_**,**
                         **int** _nindoms_**, pmdaMetric ***_metrics_**, int** _nmetrics_**);**
    
           **void pmdaRehash(pmdaExt ***_pmda_**, pmdaMetric ***_metrics_**, int** _nmetrics_**);**
    
           **void pmdaSetFlags(pmdaInterface ***_dispatch_**, int** _flags_**);**
           **void pmdaSetCommFlags(pmdaInterface ***_dispatch_**, int** _flags_**);**
           **void pmdaExtSetFlags(pmdaExt ***_pmda_**, int** _flags_**);**
           **void pmdaSetData(pmdaInterface ***_dispatch_**, void ***_data_**);**
           **void pmdaExtSetData(pmdaExt ***_pmda_**, void ***_data_**);**
           **void *pmdaExtGetData(pmdaExt ***_pmda_**);**
    
           **cc ... -lpcp_pmda -lpcp**
    


## DESCRIPTION



           **pmdaInit** initializes  a  PMDA so that it is ready to receive PDUs
           from pmcd(1).  The function expects as arguments the instance  do‐
           main  table  (_indoms_)  and  the metric description table (_metrics_)
           that are initialized  by  the  PMDA.  The  arguments  _nindoms_  and
           _nmetrics_  should  be set to the number of instances and metrics in
           the tables, respectively.
    
           Much of the **pmdaInterface** structure can be automatically  initial‐
           ized  with  pmdaDaemon(3), pmdaGetOpt(3) and pmdaDSO(3).  **pmdaInit**
           completes the PMDA initialization  phase  with  three  operations.
           The  first  operation  adds the domain and instance numbers to the
           instance and metric tables.  Singular metrics (metrics without  an
           instance domain) should have the instance domain **PM_INDOM_NULL** set
           in  the _indom_ field of the **pmDesc** structure (see pmLookupDesc(3)).
           Metrics with an instance domain should set this field  to  be  the
           serial number of the instance domain in the _indoms_ table.
    
           The  instance  domain table may be made empty by setting _indoms_ to
           NULL and _nindoms_ to 0.  This allows the caller to  provide  custom
           Fetch  and  Instance  callback functions.  The metric table may be
           made empty by setting _metrics_ to NULL and _nmetrics_ to 0.  This al‐
           lows the caller to provide custom Fetch  and  Descriptor  callback
           functions.
    


## EXAMPLE



           For  example,  a  PMDA  has three metrics: A, B and C, and two in‐
           stance domains X and Y, with two instances in  each  instance  do‐
           main.  The instance domain and metrics description tables could be
           defined as:
    
                static pmdaInstid _X[] = {
                    { 0, "X1" }, { 1, "X2" }
                };
    
                static pmdaInstid _Y[] = {
                    { 0, "Y1" }, { 1, "Y2" }
                };
    
                static pmdaIndom indomtab[] = {
                #define X_INDOM 0
                    { X_INDOM, 2, _X },
                #define Y_INDOM 3
                    { Y_INDOM, 2, _Y }
                };
    
                static pmdaMetric metrictab[] = {
                /* A */
                    { (void *)0,
                      { PMDA_PMID(0,0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT,
                        { 0,0,0,0,0,0} }, },
                /* B */
                    { (void *)0,
                      { PMDA_PMID(0,1), PM_TYPE_U32, X_INDOM, PM_SEM_INSTANT,
                        { 0,0,0,0,0,0} }, },
                /* C */
                    { (void *)0,
                      { PMDA_PMID(0,2), PM_TYPE_DOUBLE, Y_INDOM, PM_SEM_INSTANT,
                        { 0,1,0,0,PM_TIME_SEC,0} }, }
                };
    
           The metric description table defines metric A with no instance do‐
           main,  metric  B with instance domain X and metric C with instance
           domain Y.  Metric C has units of seconds, while the other  metrics
           have  no units (simple counters).  **pmdaInit** will take these struc‐
           tures and assign the PMDA(3) domain number to the  _it_indom_  field
           of  each instance domain.  This identifier also replaces the _indom_
           field of all metrics which have that instance domain, so that they
           are correctly associated.
    
           The second stage opens the help text file, if  one  was  specified
           with  the **-h** command line option (see pmdaGetOpt(3)) or as a _help‐_
           _text_ argument to pmdaDSO(3) or pmdaDaemon(3).
    
           The final stage involves preparing the metric table lookup strate‐
           gy.
    


## METRIC LOOKUP



           When fetch and descriptor requests are made of the PMDA, each  re‐
           quested  PMID  must  be mapped to a metric table entry.  There are
           currently three strategies for performing this mapping  -  direct,
           linear  and  hashed.  Each has its own set of tradeoffs and an ap‐
           propriate strategy should be selected for each PMDA.
    
           If all of the metric PMID item numbers correspond to the  position
           in  the  _metrics_  table, then direct mapping is used.  This is the
           most efficient of the lookup functions as it involves a direct ar‐
           ray index (no additional memory is  required  nor  any  additional
           processing overhead).  If the PMID numbering requirement is met by
           the  PMDA, it is ideal.  This strategy can be explicitly requested
           by calling **pmdaSetFlags**(_pmda_ , _PMDA_EXT_FLAG_DIRECT_) before calling
           **pmdaInit**.  In this case, if the direct  mapping  is  not  possible
           (e.g.  due  to  an oversight on the part of the PMDA developer), a
           warning is logged and the linear strategy is used instead.
    
           The second strategy (linear search) is the default, when a  direct
           mapping  cannot be established.  This provides greater flexibility
           in the PMID numbering scheme, as the PMDA item numbers do not have
           to be unique (hence, the PMID cluster numbers  can  be  used  more
           freely,  which is often extremely convenient for the PMDA develop‐
           er).  However, lookup involves a linear walk from the start of the
           metric table until a matching PMID is found,  for  each  requested
           PMID in a request.
    
           The  third  strategy (hash lookup) can be requested by calling **pm‐**
           **daSetFlags**(_pmda_ , _PMDA_EXT_FLAG_HASHED_)  before  calling  **pmdaInit**.
           This  strategy is most useful for PMDAs with large numbers of met‐
           rics (many hundreds, or thousands).  Such PMDAs will almost always
           use the cluster numbering scheme, so the direct lookup scheme  be‐
           comes  inappropriate.   They  may  also be prepared to sacrifice a
           small amount of additional memory for a hash table,  mapping  PMID
           to  metric table offsets, to speed up lookups in their vast metric
           tables.
    
           This final strategy can also be used by PMDAs serving  up  dynami‐
           cally  numbered  metrics.   For this case, the **pmdaRehash** function
           should be used to replace the metric table when new metrics become
           available, or existing metrics are removed.  The PMID hash mapping
           will be recomputed at the same time that the new metric  table  is
           installed.
    


## METRIC CHANGES



           It  should be well understood by PMDA authors that metric metadata
           for individual metrics  is  fixed,  and  ideally  would  not  ever
           change.   In  the situation where metadata is incorrect and is up‐
           dated, such a change requires correction to logged  metrics  using
           pmlogrewrite(1), and as a result should be avoided whenever possi‐
           ble.
    
           However, a PMDA may become aware of new domain metrics at runtime,
           and  in  this case it is ideal to export them immediately (without
           any collector system restart).  In this situation,  the  PMDA  can
           inform  all  running  PMAPI clients that may have already explored
           the metric namespace (for example, using pmTraversePMNS(3)) of the
           change to the metric namespace.
    
           This is achieved using  **pmdaSetFlags**(_pmda_ ,  _PMDA_EXT_NAMES_CHANGE_)
           which  will result in the PMCD_NAMES_CHANGE state change notifica‐
           tion being sent to each PMAPI client on next fetch.  If the  newly
           discovered  metrics  have  label metadata associated, then the _PM‐_
           _DA_EXT_LABEL_CHANGE_ flag may also be set, which will result in the
           PMCD_LABEL_CHANGE notification being sent as well.
    
           **pmdaExtSetFlags** is equivalent to **pmdaSetFlags** , and is provided  as
           a  convenience  interface  in situations where the **pmdaExt** is more
           readily available than the **pmdaInterface** structure.
    


## COMMUNICATION ATTRIBUTES



           Agents that make use of  authentication  or  container  attributes
           should  indicate  this using the **pmdaSetCommFlags** interface.  This
           indicates the need for these attributes to be communicated on  the
           channel  between the PMDA and **pmcd** or local context client.  Valid
           flags are PMDA_FLAG_AUTHORIZE (for authentication related  attrib‐
           utes)  and PMDA_FLAG_CONTAINER (for container name related attrib‐
           utes).
    


## PRIVATE DATA



           A facility for associating private  PMDA  data  with  the  **pmdaExt**
           structure  is available.  This allows a PMDA to associate an arbi‐
           trary (and typically not global) pointer  with  the  **pmdaExt** such
           that  it  can  be later obtained during callbacks.  The interfaces
           for setting this pointer are **pmdaSetData** and  **pmdaExtSetData** ,  and
           **pmdaExtGetData** for subsequently retrieving it.
    


## CAVEAT



           The  PMDA must be using **PMDA_INTERFACE_2** or later, as specified in
           the call to pmdaDSO(3) or pmdaDaemon(3) to use **pmdaInit**.
    
           The PMDA must use **PMDA_INTERFACE_7** or later to issue state  change
           notifications using **pmdaSetFlags** or **pmdaExtSetFlags**.
    


## DIAGNOSTICS



           **pmdaInit** will  set  _dispatch- >status_ to a value less than zero if
           there is an error that would prevent the PMDA(3) from successfully
           running.  pmcd(1) will terminate the connection to the PMDA(3)  if
           this occurs.
    
           **pmdaInit** may issue any of these messages:
    
           **PMDA interface version** _interface_ **not supported**
                  The _interface_ version is not supported by **pmdaInit**.
    
           **Using pmdaFetch() but fetch call back not set**
                  The fetch callback, pmdaFetch(3), requires an additional
                  callback to be provided using pmdaSetFetchCallBack(3).
    
           **Illegal instance domain** _inst_ **for metric** _pmid_
                  The instance domain _inst_ that was specified for metric _pmid_
                  is not within the range of the instance domain table.
    
           **No help text path specified**
                  The help text callback, pmdaText(3), requires a help text
                  file for the metrics to have been opened, however no path
                  to the help text was specified as a command line option, or
                  as an argument to pmdaDSO(3) or pmdaDaemon(3).  This mes‐
                  sage is only a warning.
    
           **Direct mapping for metrics disabled @**_num_
                  The unit numbers of the metrics did not correspond to the
                  index in the metric description table.  The direct mapping
                  failed for metric number _num_ in the _metrics_ table.  This is
                  less efficient but is not fatal and the message is only a
                  warning.
    
           **Hashed mapping for metrics disabled @**_num_
                  A memory allocation failure occurred while building the
                  hash table to index the metric description table.  This is
                  a non-fatal warning message - a fallback to linear search‐
                  ing will be automatically performed should this situation
                  arise.
    


* * *