QMCGROUP(3)

💖 NAME 💖

QmcGroup — it's giving container, bestie. Specifically: a container representing a single fetch group of metrics from multiple sources. that's the whole job. slay.

---

🌸 C++ SYNOPSIS 🌸

#include <QmcGroup.h>

c++ ... -lpcp_qmc -lpcp

---

🦋 DESCRIPTION 🦋

okay so picture this: a QmcGroup object is a container for contexts and metrics that should be fetched at the same time. like, they're a friend group, they show up together, no stragglers. 💅

the class manages the QmcContext(3) objects, the timezones, and the bounds for every context you create with QmcGroup::use and QmcGroup::addMetric. she's organized. she's the group chat admin. iconic behavior.

---

✨ CONSTRUCTORS & DESTRUCTOR ✨

• ~QmcGroup(); — the destructor. she destroys all metrics and contexts created by this group. it's giving "closing the group chat forever" 😭
• QmcGroup(bool restrictArchives = false); — construct a brand new fetch group. if you set restrictArchives, it will restrict the creating of multiple archive contexts created from the same host. (yes, that's the actual wording, and yes, it means what it says.)

---

💜 CONTEXTS 💜

so the default context of the group is defined as the first context created with QmcGroup::use before the first call to QmcGroup::addMetric. if no context is created before the first metric is added, the localhost is used as the default context. therefore — and this is the important part, bestie, underline it — if any metrics specifications contain archive sources, an archive source must have been created with QmcGroup::use to avoid an error for mixing context types. mixing context types = drama. we do not want the drama. 🙈

• uint_t numContexts() const; — how many valid contexts got created in this group. the headcount. 👑
• QmcContext const& context(uint_t index) const — hand me a handle to a context (read-only edition).
• QmcContext& context(uint_t index); — hand me a handle to a context, but make it modifiable. touch grass, touch the context.
• int mode() const; — returns the type of context, which is one of PM_CONTEXT_LOCAL, PM_CONTEXT_HOST, or PM_CONTEXT_ARCHIVE.
• QmcContext* which() const; — a handle to the current context of this group. ⚠️ heads up though: this does not call pmUseContext(3), so it may not be the current PMAPI(3) context. they are different things, don't get it twisted.
• uint_t contextIndex() const — the index to the current group context.
• int use(int type, char const* source); — use the context of type from source. if a context to this source already exists in this group, that context becomes the current PMAPI(3) context. otherwise a new context gets created. the result is the PMAPI(3) context handle for the QmcGroup::context, or a PMAPI(3) error code if the context failed. 🫶
• bool defaultDefined() const; — returns true if a default context has been determined. vibe check: passed or not passed.
• int useDefault(); — use the default context. if a default context has not been created, the context to the local host will be attempted. a result less than zero means the method failed, with the PMAPI(3) error encoded in the result. 😭
• void createLocalContext(); — create and use a context to the local host. a result less than zero indicates that the method failed with the PMAPI(3) error encoded in the result.

---

🔥 METRICS 🔥

these addMetric methods are the ones you use to create new metrics, because the QmcMetric constructors are private (not yours to touch, bestie, they're behind the velvet rope). these methods will always return a pointer to a QmcMetric object — however, you should check the QmcMetric::status() field to make sure the metric is actually valid. always check the status. always. 🎀

• QmcMetric* addMetric(char const* str, double theScale = 0.0, bool active = false); — add the metric str to the group, with a scaling factor of scale. if active is set, the metric will use only active instances (see QmcMetric(3)).
• QmcMetric* addMetric(pmMetricSpec* theMetric, double theScale = 0.0, bool active); — add the metric theMetric to the group, with a scaling factor of scale. if active is set, the metric will use only active instances (see QmcMetric(3)).
• int fetch(bool update = true); — fetch all the metrics in all the contexts in this group. if update equals true, all counter metrics will be automatically converted to rates (see QmcMetric(3)). auto-conversion, no manual labor, we love efficiency. ✨
• int setArchiveMode(int mode, const struct timeval *when, int interval); — set the mode and time to access all archive contexts in this group. see pmSetMode(3) for more details.

---

🌈 TIMEZONES 🌈

these methods assist in the management of multiple timezones and help to control the current timezone. timezone girlies, this section is for you. 🌍

• enum TimeZoneFlag { localTZ, userTZ, groupTZ, unknownTZ }; — an enumeration used to describe the origin of the default timezone. localTZ, userTZ and groupTZ indicate that the timezone was set with QmcGroup::useLocalTZ, QmcGroup::useTZ(QString const&) and QmcGroup::useTZ() respectively. unknownTZ indicates that a timezone has not been set. userTZ indicates that the timezone was — and that's where the original manpage literally just stops mid-sentence 💀 the sentence does not finish. we respect the cut-off. we do not invent an ending.
• int useTZ(); — use the timezone of the current group context as the default.
• int useTZ(const QString &tz); — add and use tz as the default timezone of this group.
• int useLocalTZ(); — use the timezone of the localhost as the default for this group.
• void defaultTZ(QString &label, QString &tz); — return the label and tz string of the default timezone of this group.
• TimeZoneFlag defaultTZ() const — return the origin of the default timezone.
• int useDefaultTZ(); — set the timezone to be the default timezone as defined in a previous call to QmcGroup::useTZ or QmcGroup::useLocalTZ.
• struct timeval const& logStart() const; — return the earliest starting time of any archives in this group. ⚠️ assumes that QmcGroup::updateBounds has been called. no bounds update, no accurate answer, no cap.
• struct timeval const& logEnd() const; — return the latest finish time of any archives in this group. ⚠️ also assumes that QmcGroup::updateBounds has been called.
• void updateBounds(); — determine the earliest start and latest finish times of all archives in this group. do this first. it's the pre-game. 🧚

---

💀 DEBUGGING 💀

• void dump(ostream &os); — dump state information about this group to os. spill the tea, girl. 🍓

---

🙈 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. so like… she wrote the message, she did not send it. you have to send it. 🫠

additional diagnostics may be activated by adding the option pmc to the global debugging specification, as described in pmSetDebug(3).

---

💅 SEE ALSO 💅

PMAPI(3), QMC(3), QmcContext(3), QmcMetric(3), pmflush(3), pmprintf(3) and pmSetMode(3). the whole squad, fr fr. 🫶

---

okay bestie that's the whole page, you ate it 💖 this one's from Performance Co-Pilot, brought to you by SGI, and she answers to the name QMCGROUP(3). go forth and fetch. ✨👑