PMDAEVENTQUEUE(3)

✨ PMDAEVENTQUEUE ✨

okay bestie, welcome to the Library Functions Manual section of the PCP docs 💖 this one is about pmdaEventNewQueue, pmdaEventNewActiveQueue, pmdaEventQueueHandle, pmdaEventQueueAppend, pmdaEventQueueShutdown, pmdaEventQueueRecords, pmdaEventQueueClients, pmdaEventQueueCounter, pmdaEventQueueBytes, and pmdaEventQueueMemory — aka the whole utilities-for-PMDAs-managing-event-queues friend group 🫶

---

🎀 NAME 🎀

pmdaEventNewQueue, pmdaEventNewActiveQueue, pmdaEventQueueHandle, pmdaEventQueueAppend, pmdaEventQueueShutdown, pmdaEventQueueRecords, pmdaEventQueueClients, pmdaEventQueueCounter, pmdaEventQueueBytes, pmdaEventQueueMemory — utilities for PMDAs managing event queues, periodt 💅

---

🌸 C SYNOPSIS 🌸

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

int pmdaEventNewQueue(const char *name, size_t maxmem);
int pmdaEventNewActiveQueue(const char *name, size_t maxmem,
                            int nclients);
int pmdaEventQueueHandle(const char *name);
int pmdaEventQueueAppend(int handle, void *buffer, size_t bytes,
                         struct timeval *tv);
int pmdaEventQueueShutdown(int handle);

typedef int (*pmdaEventDecodeCallBack)(int, void *, int,
             struct timeval *, void *);
int pmdaEventQueueRecords(int handle, pmAtomValue *avp, int context,
                          pmdaEventDecodeCallBack decoder, void *data);
int pmdaEventQueueClients(int handle, pmAtomValue *avp);
int pmdaEventQueueCounter(int handle, pmAtomValue *avp);
int pmdaEventQueueBytes(int handle, pmAtomValue *avp);
int pmdaEventQueueMemory(int handle, pmAtomValue *avp);

cc ... -lpcp_pmda -lpcp

---

💖 DESCRIPTION 💖

okay so, a Performance Metrics Domain Agent (PMDA) that exports event records has to basically be an event multiplexer, no cap. Like, events that the PMDA consumes might need to be forwarded on to literally any number of monitoring tools (or "client contexts") 🌈 those tools may be asking for events at different sampling intervals, and they're very unlikely to ask for an event at the exact moment it arrives at the PMDA — so some form of event buffering and queuing scheme is a whole necessity, fr fr. Events must be held by the PMDA until either all registered clients have been sent them, or until a memory limit has been reached by the PMDA — at which point it must discard older events as new ones arrive 😭

The routines described here are designed to help the PMDA developer manage both client contexts and queues of events at a high level 🧚 they fit logically above lower level primitives, like the ones described in pmdaEventNewArray(3), and shield the average PMDA from the details of directly building event record arrays for individual client contexts. it's giving "we handle the chaos, you handle the vibes" 💅

The PMDA registers a new queue of events using either pmdaEventNewQueue or pmdaEventNewActiveQueue. These get passed:

• an identifying name — for diagnostic purposes, and for subsequent lookup by pmdaEventQueueHandle 👑
• maxmem — an upper bound on the memory (in bytes) that can be consumed by events in this queue, before it starts discarding them (which results in "missed" events for any client that has not kept up 💀)

If a queue is dynamically allocated (such that the PMDA may already have clients connected), the pmdaEventNewActiveQueue interface should be used, with the additional nclients parameter indicating the count of active client connections ✨

The return is a negative error code on failure, suitable for decoding by the pmErrStr(3) routine. Any non-negative value indicates success, and provides a handle suitable for passing into the other API routines 🎀

---

For each new event received by the PMDA, the pmdaEventQueueAppend routine should be called, placing that event into the queue identified by handle. The event itself must be contained in the passed in buffer, having bytes length. The timestamp associated with the event (time at which the event occurred) is passed in via the final tv parameter ⭐

---

In the PMDAs specific implementation of its fetch callback, when values for an event metric have been requested, the pmdaEventQueueRecords routine should be used 🔥 It is passed:

• the queue handle
• the avp pmAtomValue structure to fill with event records, for the client making that fetch request (identified by the context parameter)
• and finally, the PMDA must also pass in an event decoding routine (decoder), which is responsible for decoding the fields of a single event into the individual event parameters of that event 🦋

The data parameter is an opaque cookie that can be used to pass situation-specific information into each decoder invocation 🙈

---

Under some situations it is useful for the PMDA to export state about the queues under its control 👀 The accessor routines — pmdaEventQueueClients, pmdaEventQueueCounter, pmdaEventQueueBytes and pmdaEventQueueMemory — provide a mechanism for querying a queue by its handle and filling in a pmAtomValue structure that the pmdaFetchCallBack method should return 💜

---

🌈 SEE ALSO 🌈

• PMAPI(3)
• PMDA(3)
• pmdaEventNewClient(3)
• pmdaEventNewArray(3)

---

k bye bestie, go build that queue 💖 this little manual page came to you from Performance Co-Pilot (PCP), and yeah, the header and footer both said PMDAEVENTQUEUE(3) because that's just how iconic it is 👑 stay hydrated, keep your maxmem honest, and don't let those events get missed ✨💅🎀