PMADELTAINDOM(3)

💫 PMADELTAINDOM(3) 💫

okay bestie, gather round, because we're diving into pmaDeltaInDom from the PMADELTAINDOM(3) part of the manual — it's a library functions manual situation, and yes it's giving internal-PCP-developer energy, but we're gonna make it make sense 🫶

---

✨ NAME ✨

pmaDeltaInDom — generate a "delta indom" if two observations of an instance domain are different 💅

---

🎀 C SYNOPSIS 🎀

#include <pcp/pmapi.h>
#include <pcp/libpcp.h>
#include <pcp/archive.h>

int pmaDeltaInDom(__pmLogInDom *old, __pmLogInDom *new,
                   __pmLogInDom *new_delta);

cc ... -lpcp_archive -lpcp

like, that's the whole vibe. three pointers, one int, no cap 💖

---

⚠️ CAVEAT ⚠️

okay so, real talk, no cap: this documentation is intended for internal Performance Co-Pilot (PCP) developer use. bestie, this is backstage access, not the main stage 🎭

These interfaces are not part of the PCP APIs that are guaranteed to remain fixed across releases. So like... they may not work, or they may provide different semantics at some point in the future. literally don't build your whole personality on them 😭

fr fr, this is a "use at your own risk, future-you will not be warned" kind of situation 💀

---

🌸 DESCRIPTION 🌸

So what does it do? It checks if two observations of the same instance domain are identical, and if they are not, it tries to generate a "delta indom" to describe the differences. it's giving detective energy 🔍

The code assumes two things, and bestie, these are non-negotiable:

• (a) old->indom == new->indom
• (b) both the instance domains are sorted in ascending internal instance identifier sequence

and if you're sitting there like "how do I make that second condition true 🥺" — go look at pmaSortInDom(3), that's literally its whole job ✨

The "delta indom" format is only supported for Version 3 archives, and it is the caller's responsibility to determine if calling pmaDeltaInDom is appropriate — rather than calling pmaSameInDom(3), which is the preferred method for V2 archives. so V2 besties, y'all know where to go 👑

Now, the return values. this is the important part, so pay attention 🎯

• 0 — pmaDeltaInDom returns 0 if the old and new instance domains are the same. iconic, nothing to do, we move on 💅
• 1 — the instance domains are different, but the "delta indom" format is not more efficient. In this case new_delta is not modified. like, we tried, it wasn't worth it, we leave it alone 🙈
• 2 — the instance domains are different and new_delta has been set up to describe the "delta indom" encoding of the differences. In this case the caller is responsible for freeing new_delta->instlist and new_delta->namelist. that's your mess now, bestie, go clean it up 🧹

And the instance domains are considered different if any of the following hold:

1. old->numinst != new->numinst
2. For some i, old->instlist[i] != new->instlist[i]
3. For some i, the strings pointed to by old->namelist[i] and new->instlist[i] are not identical

(yes, item 3 really does say new->instlist[i], we're keeping it exactly as written, character for character, no editing the source material here 🫡)

---

🦋 DELTA INDOM FORMAT 🦋

So how does this "delta indom" thing actually lay out? Let's break it down 💜

As for a regular instance domain, new_delta->numinst defines the number of instance specifications. that's the count, the headcount, the attendance sheet 📋

• If new_delta->namelist[i] == NULL then the instance identified by new_delta->instlist[i] has been deleted from the instance domain. bye bestie, you're out 👋
• If new_delta->namelist[i] != NULL then the instance identified by new_delta->instlist[i] has been added to the instance domain. hi new friend, welcome to the group chat 🎉

Because the "delta indom" is only likely to have short-term relevance to the caller, the new_delta->namelist[i] entries that are not NULL will point back into old->namelist[j] or new->namelist[k]. Which means: old and new should not be freed until the caller has finished with new_delta. like, do NOT pull the rug out from under it, the pointers are literally holding hands with the originals 😭🫶

⚠️ free old or new too early and you're pointing at ghosts. the delta indom is borrowing, not owning. periodt.

---

🔥 SEE ALSO 🔥

• PMAPI(3)
• pmaSortInDom(3)
• pmaSameInDom(3)

---

and that's the whole page, bestie 💖 big slay to the Performance Co-Pilot girlies, this one's from PCP, and yeah, the original was filed under PMADELTAINDOM(3) — that's the header, that's the footer, that's the whole glow-up. go generate some deltas responsibly, ily, mwah 💅✨🌈