PMWEBTIMERREGISTER(3)

PMWEBTIMERREGISTER 💖 bestie edition

okay so this is a page from the PCP library manual, section 3 (that's the "library functions" shelf of the man-page library, iykyk), and it's about three lil besties that work together: pmWebTimerRegister, pmWebTimerRelease and pmWebTimerSetMetricRegistry — aka thread-safe timer list management. slay. ✨

---

🌸 NAME 🌸

pmWebTimerRegister, pmWebTimerRelease, pmWebTimerSetMetricRegistry — thread-safe timer list management 🕰️💅

---

🎀 C SYNOPSIS 🎀

like, include the header first, obviously:

#include <pcp/pmwebapi.h>

typedef void (*pmWebTimerCallBack)(void *data);
int pmWebTimerRegister(pmWebTimerCallBack callback, void *data);

int pmWebTimerRelease(int seq);
int pmWebTimerSetMetricRegistry(struct mmv_registry *registry);

cc ... -lpcp_web

and don't forget to link the library bestie, cc ... -lpcp_web 🤝

---

💜 DESCRIPTION 💜

so pmWebTimerRegister and its lil friend group give you a convenient, thread-safe API for managing a whole list of timer-driven callbacks. no cap. 🧚

the way it works: on the first call to either pmWebTimerRegister or pmWebTimerSetMetricRegistry, an internal timer gets set up and initialized to fire every 1.0 seconds. literally. ⏰

and every single time that timer fires, all currently registered callback functions get called serially — one after the other, no cutting the line — each one handed the opaque data pointer that was supplied back when that specific function was registered. the pmWebTimerCallBack typedef is right there giving you a suitable callback function prototype, so use it. 🫶

⚠️ real talk: all registered callback functions should be non-blocking and should execute quickly and synchronously. don't be the one holding up the group chat. 😭

typical callback functions include:

• refreshing instrumentation 🔄
• calculating and updating performance metric values 📊
• periodic garbage collection 🗑️
• and honestly, any other local function that requires regular execution ✨

---

🦋 the metric registry one 🦋

pmWebTimerSetMetricRegistry is the convenient way for an app to pass in a pointer to a libpcp_mmv(3) registry that the calling application has suitably initialized already. (yes, you initialize it. it's not doing it for you. main character responsibilities. 👑)

that registry then gets used to dynamically create six server resource metrics, and here they are, exactly:

• NAME.mem.datasz
• NAME.mem.maxrss
• NAME.cpu.total
• NAME.cpu.sys
• NAME.cpu.user
• NAME.pid

where NAME is the root PCP PMNS(5) name that got set up by the calling application. 📛

these metrics should be reasonably self explanatory ngl — they provide resource usage metrics from the calling application / server, and under the hood they use getrusage(2), times(2) and getpid(2). iconic trio fr fr. 💅

---

💖 RETURN VALUE 💖

pmWebTimerRegister returns a positive integer handle — keep it safe bestie, you'll need it later — which may subsequently be used in a call to pmWebTimerRelease to remove a timer from the internal timer list. 🎟️

when a timer gets removed with a call to pmWebTimerRelease, the internal data structures are freed. 🧹

🙈 BUT — and this is the part everyone forgets — the caller is responsible for freeing the associated data, since it may or may not be dynamically allocated. so like, we can't know. that's on you. 😭

---

💀 DIAGNOSTICS 💀

on failure, a negative PMAPI error code is returned in all cases. every single one. no exceptions. 💀

---

🌈 SEE ALSO 🌈

• pmproxy(1)
• mmv_stats_registry(3)
• PMAPI(3)
• and PMWEBAPI(3)

go read those next, you're doing amazing. 🫶✨

---

Performance Co-Pilot · PCP · PMWEBTIMERREGISTER(3) — that's the whole vibe check, thanks for coming to my TED talk, ily, now go free your data pointer 💖🎀🦋