QMCINDOM(3)

💖 QMCINDOM(3) — the QmcIndom era 💖

okay bestie, sit down, we're learning the QmcIndom page from the Library Functions Manual and honestly? it's giving backend royalty 👑

---

✨ NAME ✨

QmcIndom — a container for a instance domain description 🎀

---

🌸 C++ SYNOPSIS 🌸

#include <QmcIndom.h>

c++ ... -lpcp_qmc -lpcp

link it, compile it, slay it 💅

---

🦋 DESCRIPTION 🦋

So a QmcIndom object is literally a whole representation of a PMAPI(3) instance domain. And when we say "representation" we mean it's got the full description of every instance in that instance domain. the whole roster, no cap 🫶

And a QmcInstance? That's the structure that describes each individual instance in the instance domain. Here's the tea, it includes:

• internal identifier. And heads up — if this is less than zero, the instance gets treated as a NULL entry in the instance table. so watch out for that 💀
• external name
• reference count, i.e. the number of QmcMetric objects that are referring to this instance
• the likely position of the instance in the pmResult from a pmFetch(3). And fun fact: 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)

And the QmcIndom object itself? It's got a list of QmcInstance structures, plus a bunch of flags and counters, all there to support dynamic instance domains — you know, the ones where instances may come and go with each fetch — and to make profile generation efficient. iconic behavior honestly 🌟

---

🎀 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. it's literally just fetching the whole squad for you 🫶

---

🌈 DYNAMIC INDOMS 🌈

okay this part is highkey complex so stay with me bestie 😭

Supporting dynamic instance domains for live contexts is complicated, because so many metrics may be referencing any of the instances in the domain. So the instance list may end up sparse, since the position of instances in the list has to be maintained. it's a whole thing ✨

Here's how the update goes. 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 are not referenced by any metrics. Then each instance in the new list is compared with the old list to figure out 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. And new instances get inserted into positions of deleted instances first, before being appended to the list. recycling era ♻️

⚠️ heads up: this algorithm is expensive — potentially O(N^2). not the vibe we wanted but it's the vibe we got 💀

• 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). here's the whole flow, verbatim, no edits 💖

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.

---

🔥 DIAGNOSTICS 🔥

Error messages are generated using pmprintf(3) but they are not flushed. so it's your responsibility, bestie — you gotta call pmflush(3) to output any messages. don't leave them hanging 🙈

Additional diagnostics may be activated by adding the options pmc and/or indom to the global debugging specification, as described in pmSetDebug(3). iykyk ✨

---

💀 BUGS 💀

Users have no control over the algorithm used to generate the profile. and 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. not the ending we deserved tbh 😭

---

⭐ SEE ALSO ⭐

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

---

and that's the whole page, bestie!! this one came to you from Performance Co-Pilot, courtesy of SGI, and it's filed under QMCINDOM(3). go forth and manage your instance domains, you absolute icon 🫶👑