PMCONVSCALE(3)

💖 NAME 💖

pmConvScale — rescale a performance metric value ✨

---

🫶 C SYNOPSIS 🫶

#include <pcp/pmapi.h>

int pmConvScale(int type, const pmAtomValue *ival, const pmUnits *iunit,
                pmAtomValue *oval, const pmUnits *ounit);

cc ... -lpcp

---

🌸 DESCRIPTION 🌸

okay so first things first, bestie: every single performance metric value out there can be packed into a pmAtomValue union, and it looks exactly like this 👇

typedef union {
    __int32_t    l;     /* 32-bit signed */
    __uint32_t   ul;    /* 32-bit unsigned */
    __int64_t    ll;    /* 64-bit signed */
    __uint64_t   ull;   /* 64-bit unsigned */
    float        f;     /* 32-bit floating point */
    double       d;     /* 64-bit floating point */
    char         *cp;   /* char ptr */
    pmValueBlock *vbp;  /* pmValueBlock ptr */
} pmAtomValue;

and the way a performance metric's dimensionality and scale get encoded? that's a pmUnits structure, no cap. go peek at pmLookupDesc(3) for the whole tea ☕

so here's the vibe: you hand over a performance metric value pointed to by ival, it gets multiplied by a scale factor, and the glow-up lands in oval 💅 the scaling happens from the units defined by iunit into the units defined by ounit.

🚨 real talk: both the input and the output units have to have the same dimensionality. like, each of the fields dimSpace, dimTime, dimCount and extraUnit must have the same value in both iunit and ounit. no matching dimensionality, no conversion. periodt.

the performance metric type for both the input and the output values is determined by type, and that value is typically extracted from a pmDesc structure, following a call to pmLookupDesc(3) for a particular performance metric. so like, you already have it lying around usually 🎀

pmConvScale is most useful when values returned via pmFetch(3), (and possibly extracted using pmExtractValue(3)) need to be normalized into some canonical scale and units for the purposes of computation. it's giving "let's all agree on one unit before we do math" and honestly? iconic.

and now for the special case that lives rent free in my head: if all components of the dimension are zero, then this is treated as synonymous with a count dimension of one, and so the count scale components determine the relative scaling 🔥 this accommodates the case where performance metrics are dimensionless, without special case handling on the part of the caller. meaning you don't have to write that if-branch yourself. you're welcome 🫶

---

💅 DIAGNOSTICS 💅

• PM_ERR_CONV — iunit and ounit have different dimensionality, or have inappropriate type 😭
• PM_ERR_UNIT — Inappropriate iunit or ounit parameter 🙈

---

🔥 SEE ALSO 🔥

PMAPI(3), pmAtomStr(3), pmExtractValue(3), pmFetch(3), pmLookupDesc(3), pmPrintValue(3), pmTypeStr(3) and pmUnitsStr(3).

---

and that's the whole page, bestie!! this lil masterpiece comes to you from Performance Co-Pilot, aka PCP, and it lives its life under the name PMCONVSCALE(3) 💖 go forth and convert those units responsibly, mwah 🎀✨