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  includes 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 referring 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  various  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  complex  since many metrics may be
       referencing any of the instances in the domain.  Therefore  the  instance  list  may  be  sparse  as  the
       position 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 domain 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  instances that are no longer referenced without updating the instance 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 instances.

PROFILES

       The  algorithm  for   determining   the   most   compact   profile   uses   the   number   of   instances
       (_instances.length()),  the  number  of  referenced  instances  (_count),  the number of active instances
       (_numActive) and the number of referenced active instances (_numActiveRef).

               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 profile. 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.

SEE ALSO

       PMAPI(3),   QMC(3),  QmcContext(3),  QmcDesc(3),  QmcMetric(3),  pmFetch(3),  pmflush(3),  pmGetInDom(3),
       pmGetInDomArchive(3) and pmprintf(3).

Performance Co-Pilot                                   SGI                                           QMCINDOM(3)