# QmcIndom

## NAME



           **QmcIndom** - container for a instance domain description
    


## C++ SYNOPSIS



           **#include <QmcIndom.h>**
    
           **c++ ... -lpcp_qmc -lpcp**
    


## DESCRIPTION



           A **QmcIndom** object represents a PMAPI(3) instance domain.  This in‐
           cludes a description of all the instances in the instance domain.
    
           A **QmcInstance** is a structure used to describe each instance in the
           instance domain.  This includes:
    
              -  internal identifier. If this is less than zero, the instance
              is treated as a NULL entry in the instance table.
    
              - external name
    
              - reference count, i.e. the number of **QmcMetric** objects  refer‐
              ring to this instance.
    
              -  the  likely  position of the instance in the **pmResult** from a
              pmFetch(3).  This is also used to indicate the position of  the
              next NULL instance in the instance table, if this entry is also
              NULL.
    
              -   a   flag  indicating  if  the  instance  was  in  the  last
              pmGetInDom(3).
    
           The **QmcIndom** object has a list of **QmcInstance** structures, and var‐
           ious flags and counters to support dynamic instance domains  where
           instances  may  come  and go with each fetch and efficient profile
           generation.
    


## CONSTRUCTORS



           **QmcIndom::QmcIndom(int type, QmcDesc &desc);**
               Calls pmGetInDom(3) and pmGetInDomArchive(3) for host and
               archive contexts to obtain the entire instance list for the
               instance domain of _type_ and identified in _desc_.
    


## DYNAMIC INDOMS



           The support of dynamic instance domains for live contexts is com‐
           plex since many metrics may be referencing any of the instances in
           the domain.  Therefore the instance list may be sparse as the po‐
           sition of instances in the list must be maintained.
    
           When the instance domain is updated, instances may be removed from
           the list if they are not in the new instance list (as returned by
           pmGetInDom(3)) and is not referenced by any metrics. Each instance
           in the new list is then compared with the old list to determine
           which instances are still active, and any new instances need to be
           added.  An instance is considered the same if both the internal
           and external identifiers are the same.  New instances are first
           inserted into positions of deleted instances before being appended
           to the list.
    
           This algorithm is expensive (potentially O(N^2)).
    
           **bool changed() const;**
               Returns **true** if the instance domain may have changed in the
               last fetch.
    
           **void newFetch();**
               Reset the flags that may have indicated that the instance do‐
               main had changed.  This is called by **QmcContext::fetch**.
    
           **void hasChanged();**
               Set the flags to indicate that the instance domain may have
               changed.  This is called by **QmcMetric::extractValues**.
    
           **int update();**
               Update the instance domain as described above. On subsequent
               calls, before the next fetch, this method will remove any in‐
               stances that are no longer referenced without updating the in‐
               stance list with a pmGetInDom(3) call.
    
           **uint_t numInsts() const;**
               Returns the number of instances that are not NULL.
    
           **uint_t numActiveInsts() const;**
               Returns the number of instances that are active according to
               the last **QmcIndom::update** call.
    
           **uint_t listLen() const;**
               Returns the length of the instance list, including NULL in‐
               stances.
    


## PROFILES



           The algorithm for determining the most compact profile uses the
           number of instances (**_instances.length()**), the number of refer‐
           enced instances (**_count**), the number of active instances (**_numAc‐**
           **tive**) and the number of referenced active instances (**_numAc‐**
           **tiveRef**).
    
                   if (all active instances are referenced
                       or there are no active instances)
    
                           request all instances implicitly
    
                   else if (the number of referenced instances
                            is less than the number of active
                            instances that are not referenced)
    
                           delete all instances from profile
                           add all referenced instances
    
                   else
    
                           add all instances to profile
                           delete all instances that are not referenced
    
           **bool diffProfile() const;**
               Returns **true** if the profile has potentially changed since the
               last call to **QmcIndom::genProfile**.
    
           **int genProfile();**
               Generates a new profile for the instance domain. a PMAPI(3)
               error code is returned if the profile failed.
    


## DIAGNOSTICS



           Error messages are generated using pmprintf(3) but are not
           flushed. It is the responsibility of the user to call pmflush(3)
           to output any messages.
    
           Additional diagnostics may be activated by adding the options **pmc**
           and/or **indom** to the global debugging specification, as described
           in pmSetDebug(3).
    


## BUGS



           Users have no control over the algorithm used to generate the pro‐
           file. In the case of _proc_ metrics, an implicit profile could be
           generated if all process instances are required, even though this
           will result in no values being returned in the fetch.
    


* * *