1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
'\"macro stdmacro
.\" Copyright (c) 2005 Silicon Graphics, Inc. All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
.\" for more details.
.\"
.TH QMC_INDOM 3 "SGI" "Performance Co-Pilot"
.SH NAME
\f3QmcIndom\f1 \- container for a instance domain description
.SH "C++ SYNOPSIS"
.ft 3
#include <QmcIndom.h>
.sp
CC ... \-lqmc \-lpcp
.ft 1
.SH DESCRIPTION
A
.B QmcIndom
object represents a
.BR PMAPI (3)
instance domain. This includes a description of all the instances
in the instance domain.
.PP
A
.B QmcInstance
is a structure used to describe each instance in the instance domain. This
includes:
.PP
.in 1.0i
- 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
.B QmcMetric
objects referring to this instance.
- the likely position of the instance in the
.B pmResult
from a
.BR 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
.BR pmGetInDom (3).
.in
.PP
The
.B QmcIndom
object has a list of
.B 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.
.in
.SH CONSTRUCTORS
.TP 4
.B "QmcIndom::QmcIndom(int type, QmcDesc &desc);"
Calls
.BR pmGetInDom (3)
and
.BR pmGetInDomArchive (3)
for host and archive contexts to obtain the entire instance list for the
instance domain of
.I type
and identified in
.IR desc .
.SH "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.
.PP
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
.BR 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.
.PP
This algorithm is expensive (potentially O(N^2)).
.TP 4
.B "bool changed() const;"
Returns
.B true
if the instance domain may have changed in the last fetch.
.TP
.B "void newFetch();"
Reset the flags that may have indicated that the instance domain had changed.
This is called by
.BR QmcContext::fetch .
.TP
.B "void hasChanged();"
Set the flags to indicate that the instance domain may have changed. This is
called by
.BR QmcMetric::extractValues .
.TP
.B "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
.BR pmGetInDom (3)
call.
.TP
.B "uint_t numInsts() const;"
Returns the number of instances that are not NULL.
.TP
.B "uint_t numActiveInsts() const;"
Returns the number of instances that are active according to the last
.B QmcIndom::update
call.
.TP
.B "uint_t listLen() const;"
Returns the length of the instance list, including NULL instances.
.SH "PROFILES"
The algorithm for determining the most compact profile uses the number of
instances
.RB ( _instances.length() ),
the number of referenced instances
.RB ( _count ),
the number of active instances
.RB ( _numActive )
and the number of referenced active instances
.RB ( _numActiveRef ).
.PP
.in 1.5i
.ft CW
.nf
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
.fi
.ft R
.in
.TP 4
.B "bool diffProfile() const;"
Returns
.B true
if the profile has potentially changed since the last call to
.BR QmcIndom::genProfile .
.TP
.B "int genProfile();"
Generates a new profile for the instance domain. a
.BR PMAPI (3)
error code is returned if the profile failed.
.SH SEE ALSO
.BR PMAPI (3),
.BR QMC (3),
.BR QmcContext (3),
.BR QmcDesc (3),
.BR QmcMetric (3),
.BR pmFetch (3),
.BR pmflush (3),
.BR pmGetInDom (3),
.BR pmGetInDomArchive (3)
and
.BR pmprintf (3).
.SH DIAGNOSTICS
Error messages are generated using
.BR pmprintf (3)
but are not flushed. It is the responsibility of the user to call
.BR pmflush (3)
to output any messages.
.PP
Additional diagnostics may be activated by adding
.B DBG_TRACE_PMC
and
.B DBG_TRACE_INDOM
to the global
.IR pmDebug .
.SH BUGS
User's have no control over the algorithm used to generate the profile. In
the case of
.I 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.
|
