1QMCGROUP(3) Library Functions Manual QMCGROUP(3)
2
6 QmcGroup - container representing a single fetch group of metrics from
7 multiple sources
8
10 #include <QmcGroup.h>
11 CC ... -lqmc -lpcp
13
15 A QmcGroup object is a container for contexts and metrics that should
16 be fetched at the same time. The class manages the QmcContext(3) ob‐
17 jects, timezones and bounds for every context created with Qmc‐
18 Group::use and QmcGroup::addMetric.
19
21 ~QmcGroup();
22 Destructor which destroys all metrics and contexts created by this
23 group.
24 QmcGroup(bool restrictArchives = false);
26 Construct a new fetch group. restrictArchives will restrict the
27 creating of multiple archive contexts created from the same host.
28
30 The default context of the group is defined as the first context cre‐
31 ated with QmcGroup::use before the first call to QmcGroup::addMetric.
32 If no context is created before the first metric is added, the local‐
33 host is used as the default context. Therefore, if any metrics speci‐
34 fications contain archive sources, an archive source must have been
35 created with QmcGroup::use to avoid an error for mixing context types.
36 uint_t numContexts() const;
38 The number of valid contexts created in this group.
39 QmcContext const& context(uint_t index) const
41 Return a handle to a context.
42 QmcContext& context(uint_t index);
44 Return a modifiable handle to a context.
45 int mode() const;
47 Return the type of context, either PM_CONTEXT_LOCAL, PM_CON‐
48 TEXT_HOST or PM_CONTEXT_ARCHIVE.
49 QmcContext* which() const;
51 Return a handle to the current context of this group. This does not
52 call pmUseContext(3) so it may not be the current PMAPI(3) context.
53 uint_t whichIndex() const
55 The index to the current group context.
56 int use(int type, char const* source);
58 Use the context of type from source. If a context to this source
59 already exists in this group, that context will become the current
60 PMAPI(3) context. Otherwise a new context will be created. The
61 result is the PMAPI(3) context handle for the QmcGroup::context or
62 a PMAPI(3) error code if the context failed.
63 bool defaultDefined() const;
65 Returns true if a default context has been determined.
66 int useDefault();
68 Use the default context. If a default context has not been created,
69 the context to the local host will be attempted. A result less
70 than zero indicates that the method failed with the PMAPI(3) error
71 encoded in the result.
72 void createLocalContext();
74 Create and use a context to the local host. A result less than
75 zero indicates that the method failed with the PMAPI(3) error en‐
76 coded in the result.
77
79 These addMetric methods should be used to create new metrics as the Qm‐
80 cMetric constructors are private. These methods will always return a
81 pointer to a QmcMetric object, however the QmcMetric::status() field
82 should be checked to ensure the metric is valid.
83 QmcMetric* addMetric(char const* str, double theScale = 0.0,
85 bool active = false);
86 Add the metric str to the group, with a scaling factor of scale.
88 If active is set the metric will use only active instances (see Qm‐
89 cMetric(3)).
90 QmcMetric* addMetric(pmMetricSpec* theMetric, double theScale
92 = 0.0, bool active);
93 Add the metric theMetric to the group, with a scaling factor of
95 scale. If active is set the metric will use only active instances
96 (see QmcMetric(3)).
97 int fetch(bool update = true);
99 Fetch all the metrics in all the contexts in this group. If update
100 is equal to true, all counter metrics will be automatically con‐
101 verted to rates (see QmcMetric(3)).
102 int setArchiveMode(int mode, const struct timeval *when,
104 int interval);
105 Set the mode and time to access all archive contexts in this group.
107 See pmSetmode(3) for more details.
108
110 These methods assist in the management of multiple timezones and help
111 to control the current timezone.
112 enum TimeZoneFlag { localTZ, userTZ, groupTZ, unknownTZ };
114 Enumeration used to describe the origin of the default timezone.
115 localTZ, userTZ and groupTZ indicate that the timezone was set with
116 QmcGroup::useLocalTZ, QmcGroup::useTZ(QString const&) and Qmc‐
117 Group::useTZ() respectively. unknownTZ indicates that a timezone
118 has not been set. userTZ indicates that the timezone was
119 int useTZ();
121 Use the timezone of the current group context as the default.
122 int useTZ(const QString &tz);
124 Add and use tz as the default timezone of this group.
125 int useLocalTZ();
127 Use the timezone of the localhost as the default for this group.
128 void defaultTZ(QString &label, QString &tz);
130 Return the label and tz string of the default timezone of this
131 group.
132 TimeZoneFlag defaultTZ() const
134 Return the origin of the default timezone.
135 int useDefaultTZ();
137 Set the timezone to be the default timezone as defined in a previ‐
138 ous call to QmcGroup::useTZ or QmcGroup::useLocalTZ.
139 struct timeval const& logStart() const;
141 Return the earliest starting time of any archives in this group.
142 Assumes that QmcGroup::updateBounds has been called.
143 struct timeval const& logEnd() const;
145 Return the latest finish time of any archives in this group. As‐
146 sumes that QmcGroup::updateBounds has been called.
147 void updateBounds();
149 Determine the earliest start and latest finish times of all ar‐
150 chives in this group.
151 int sendTimezones();
153 Send the current timezones to kmtime (3).
154
156 void dump(ostream &os);
157 Dump state information about this group to os.
158
160 Error messages are generated using pmprintf(3) but are not flushed. It
161 is the responsibility of the user to call pmflush(3) to output any mes‐
162 sages.
163 Additional diagnostics may be activated by adding the option pmc to the
165 global debugging specification, as described in pmSetDebug(3).
166
168 PMAPI(3), QMC(3), QmcContext(3), QmcMetric(3), pmflush(3), pmprintf(3)
169 and pmSetMode(3).
170Performance Co-Pilot SGI QMCGROUP(3)