NAME

       QmcIndom - container for a instance domain description

C++ SYNOPSIS

       #include <QmcIndom.h>

       CC ... -lqmc -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, ie. 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.

SEE ALSO

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

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 DBG_TRACE_PMC and DBG_TRACE_INDOM to the
       global pmDebug.

BUGS

       User's  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.