PMNOTIFYTHROTTLE(3)

🎀 PMNOTIFYTHROTTLE 🎀

okay bestie, welcome to PMNOTIFYTHROTTLE(3), a page straight outta the Library Functions Manual 💖 this one's about __pmNotifyThrottle and __pmResetNotifyThrottle — the two functions that stop your diagnostic output messages from flooding the whole place. no cap.

---

✨ NAME ✨

__pmNotifyThrottle, __pmResetNotifyThrottle — control diagnostic output message `flooding''

---

🌸 C SYNOPSIS 🌸

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

int __pmNotifyThrottle(char *key, int subkey);
int __pmResetNotifyThrottle(char *key, int subkey);

cc ... -lpcp

---

💀 CAVEAT 💀

this documentation is for internal Performance Co-Pilot (PCP) developer use. periodt.

these interfaces are not part of the PCP APIs that are guaranteed to remain fixed across releases, and they may not work, or may provide different semantics at some point in the future. so like, don't build your whole personality on them, okay? 🙈

---

🦋 DESCRIPTION 🦋

so here's the vibe: when the same error condition keeps happening over and over — think a DoS attack, or a catastrophic networking failure, or bad system configuration, or just a software botch — there's a real risk that a PCP application could generate a large number of identical diagnostic messages, filling up a log file and hence a filesystem. it's giving chaos. 😭

__pmNotifyThrottle is meant to be used as a guard that can detect repeated calls for the same error condition and let the caller stop issuing messages when repeated badness happens. iconic behavior, honestly.

the error condition is identified by key and subkey, and the most common use case would be for these to be __FILE__ and __LINE__ at the point where __pmNotifyThrottle is called. iykyk.

for each unique key and subkey pair, __pmNotifyThrottle maintains a count of the number of times it has been called in the life of the calling process. it's literally keeping receipts. 📝

the return values are:

• 0 — if the throttle limit for key and subkey has not been reached
• 1 — if the throttle limit has been reached
• 2 — if the throttle limit has been exceeded

the same throttle limit is applied across all error conditions and is set by the environment variable PCP_NOTIFY_THROTTLE, else a default of 10 if the environment variable is not set — although this can be subsequently modified by calling __pmResetNotifyThrottle. slay, configurable 💅

__pmResetNotifyThrottle may be used to reset the counter for an error condition to zero, so that diagnostic output can be resumed if the caller determines it is safe to do so. if limit is greater than zero then the limit for the error condition is also reset, otherwise the limit is unchanged. 🫶

calling __pmResetNotifyThrottle with a key value of NULL will reset the counters (and possibly limits) for all error conditions — and in this case if limit is greater than zero the default limit for any new error conditions is also set (over-riding the default setting or the value initialized from the PCP_NOTIFY_THROTTLE environment variable). full reset energy ✨

__pmResetNotifyThrottle will return -ENOENT if key and subkey does not match an existing error condition, else the return value is the sum of the number of times the limit has been exceeded across all selected error conditions. math girlies rise 👑

---

🔥 EXAMPLE 🔥

the following is a simple throttle that stops reporting errors after 10 trips:

if ((sts = __pmNotifyThrottle(__FILE__, __LINE__)) < 2) {
    fprintf(stderr, "Some error message\n");
    if (sts == 1)
     fprintf(stderr, "[further messages will be suppressed]\n");
}

the more sophisticated example below throttles messages, but enables them again after 10 minutes. main character energy fr fr:

int    lineno;
time_t first_throttle;
...
lineno = __LINE__ + 1;
if ((sts = __pmNotifyThrottle(__FILE__, lineno)) < 2) {
    pmNotifyErr(LOG_INFO, "Some error message");
    if (sts == 1) {
     first_throttle = time(NULL);
     pmNotifyErr(LOG_INFO, "[further messages will be suppressed]");
    }
}
else if (sts == 2) {
    if (time(NULL) - first_throttle >= 600) {
     sts = __pmResetNotifyThrottle(__FILE__, lineno, -1);
     pmNotifyErr(LOG_INFO, "[%d messages were suppressed]", sts);
    }
}

---

🌈 SEE ALSO 🌈

PMAPI(3) and pmOpenLog(3). go read those next bestie, they ate 💖

---

and that's the whole page! this little baddie comes to you from Performance Co-Pilot, aka PCP — the PMNOTIFYTHROTTLE(3) page, no cap. stay throttled, stay slaying 💅✨🦋