QmcIndom(3)

1QMC_INDOM(3)               Library Functions Manual               QMC_INDOM(3)
2
3
4

NAME

6       QmcIndom - container for a instance domain description
7

C++ SYNOPSIS

9       #include <QmcIndom.h>
10
11       CC ... -lqmc -lpcp
12

DESCRIPTION

14       A QmcIndom object represents a PMAPI(3) instance domain.  This includes
15       a description of all the instances in the instance domain.
16
17       A QmcInstance is a structure used to  describe  each  instance  in  the
18       instance domain.  This includes:
19
20          -  internal  identifier.  If this is less than zero, the instance is
21          treated as a NULL entry in the instance table.
22
23          - external name
24
25          - reference count, ie. the number of QmcMetric objects referring  to
26          this instance.
27
28          -  the  likely  position  of  the  instance  in  the pmResult from a
29          pmFetch(3).  This is also used to indicate the position of the  next
30          NULL instance in the instance table, if this entry is also NULL.
31
32          - a flag indicating if the instance was in the last pmGetInDom(3).
33
34       The  QmcIndom  object has a list of QmcInstance structures, and various
35       flags and counters to support dynamic instance domains where  instances
36       may come and go with each fetch and efficient profile generation.
37

CONSTRUCTORS

39       QmcIndom::QmcIndom(int type, QmcDesc &desc);
40           Calls  pmGetInDom(3)  and pmGetInDomArchive(3) for host and archive
41           contexts to obtain the entire instance list for the instance domain
42           of type and identified in desc.
43

DYNAMIC INDOMS

45       The  support  of  dynamic instance domains for live contexts is complex
46       since many metrics may be referencing  any  of  the  instances  in  the
47       domain.   Therefore  the instance list may be sparse as the position of
48       instances in the list must be maintained.
49
50       When the instance domain is updated, instances may be removed from  the
51       list  if  they  are  not  in  the  new  instance  list  (as returned by
52       pmGetInDom(3)) and is not referenced by any metrics. Each  instance  in
53       the  new  list  is  then  compared with the old list to determine which
54       instances are still active, and any new instances need to be added.  An
55       instance is considered the same if both the internal and external iden‐
56       tifiers are the same.  New instances are first inserted into  positions
57       of deleted instances before being appended to the list.
58
59       This algorithm is expensive (potentially O(N^2)).
60
61       bool changed() const;
62           Returns  true  if  the instance domain may have changed in the last
63           fetch.
64
65       void newFetch();
66           Reset the flags that may have indicated that  the  instance  domain
67           had changed.  This is called by QmcContext::fetch.
68
69       void hasChanged();
70           Set  the  flags  to  indicate  that  the  instance  domain may have
71           changed.  This is called by QmcMetric::extractValues.
72
73       int update();
74           Update the instance domain as described above. On subsequent calls,
75           before  the  next fetch, this method will remove any instances that
76           are no longer referenced without updating the instance list with  a
77           pmGetInDom(3) call.
78
79       uint_t numInsts() const;
80           Returns the number of instances that are not NULL.
81
82       uint_t numActiveInsts() const;
83           Returns  the  number  of instances that are active according to the
84           last QmcIndom::update call.
85
86       uint_t listLen() const;
87           Returns the length of the instance list, including NULL instances.
88

PROFILES

90       The algorithm for determining the most compact profile uses the  number
91       of  instances (_instances.length()), the number of referenced instances
92       (_count), the number of active instances (_numActive) and the number of
93       referenced active instances (_numActiveRef).
94
95               if (all active instances are referenced
96                   or there are no active instances)
97
98                       request all instances implicitly
99
100               else if (the number of referenced instances
101                        is less than the number of active
102                        instances that are not referenced)
103
104                       delete all instances from profile
105                       add all referenced instances
106
107               else
108
109                       add all instances to profile
110                       delete all instances that are not referenced
111
112       bool diffProfile() const;
113           Returns  true if the profile has potentially changed since the last
114           call to QmcIndom::genProfile.
115
116       int genProfile();
117           Generates a new profile for the instance domain. a  PMAPI(3)  error
118           code is returned if the profile failed.
119

DIAGNOSTICS

125       Error messages are generated using pmprintf(3) but are not flushed.  It
126       is the responsibility of the user to call pmflush(3) to output any mes‐
127       sages.
128
129       Additional diagnostics may be activated  by  adding  DBG_TRACE_PMC  and
130       DBG_TRACE_INDOM to the global pmDebug.
131

BUGS

133       User's have no control over the algorithm used to generate the profile.
134       In the case of proc metrics, an implicit profile could be generated  if
135       all  process instances are required, even though this will result in no
136       values being returned in the fetch.
137
138
139
140Performance Co-Pilot                  SGI                         QMC_INDOM(3)