PMAF(3)

✨ PMAF(3) — the event queue girlies ✨

okay so bestie, welcome to PMAF(3), aka the library functions manual page for the periodic asynchronous callback squad 🎀 this is the PCP manual, and it is genuinely giving internal-dev-tools energy, so buckle up 🦋

---

💖 NAME 💖

__pmAFsetup, __pmAFregister, __pmAFunregister, __pmAFblock, __pmAFunblock, __pmAFisempty — event queue services for periodic asynchronous callbacks 🫶

---

🌸 C SYNOPSIS 🌸

like, copy this exactly bestie, no typos, we don't do that here 💅

#include "pmapi.h"
#include "libpcp.h"

int __pmAFsetup(const struct timeval *start,
                const struct timeval *delta, void *data,
                void (*func)(int, void *));
int __pmAFregister(const struct timeval *delta, void *data,
                   void (*func)(int, void *));
int __pmAFunregister(int afid);
void __pmAFblock(void);
void __pmAFunblock(void);
int __pmAFisempty(void);

cc ... -lpcp

---

👑 CAVEAT 👑

this documentation is for internal Performance Co-Pilot (PCP) developer use. it's giving "staff only" door, no cap 🚪✨

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, they might ghost you. 🙈

---

🌈 DESCRIPTION 🌈

so these routines implement an event queue and callback framework that supports periodic evaluation of a series of events with varying frequencies for Performance Co-Pilot (PCP) applications. it's the girl who keeps everyone's schedules straight. 💅

the pmlogger(1) application, the pmdatrace(1) PMDA and the pmdahotproc(1) PMDA are the principal users of these services. main character apps only 👑

an event is created by calling __pmAFsetup or __pmAFregister and on success the return value is an event number greater than zero. the event has associated event data identified by the opaque pointer data. the event will occur with frequency delta and each time the event occurs the function func will be called with the event number and the event data as arguments. iconic behaviour honestly ✨

if __pmAFsetup is used then the first event is scheduled for the current time plus start, else if __pmAFregister is used then the first event is scheduled for the current time plus delta. two entry points, same slay, slightly different first move 💖

⚠️ func is called in a SIGALRM signal handler context and so the routines that may be safely called from func are restricted to the so-called async-signal-safe set. in particular there must be no Standard I/O calls nor calls to any of the malloc(3) routines to modify the state of the heap. refer to the Pointer to a Function Section of the POSIX.1-2013 document at https://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html for a more complete description. do not be messy in there bestie 😭

the safest and simplest class of func routines are those that do minimal processing, set some global state and return. the real work associated with the event is done subsequently from the application's main loop when the global state change is detected. so like, func is the girl who just drops the location pin and leaves, and the main loop actually shows up 🎀

once the event occurs and the callback has been executed, the event will be rescheduled for delta into the future, except if all the fields of delta are zero, in which case the event will not be rescheduled (a ``one trip'' event). one and done, a true icon of commitment issues 💀

internally, events are processed serially so there is no possibility of nested callbacks or re-entrant callbacks from the event management routines. no chaos, only queue 🧚

given an event number afid, __pmAFunregister will permanently remove the corresponding entry from the event queue. it's not coming back, periodt. 🫶

to control the event queue processing, __pmAFblock and __pmAFunblock may be used to explicitly block and unblock the dispatch of events. this is most useful when the caller wishes to set up a number of events via __pmAFsetup or __pmAFregister and complete the registration phase before the first event callback occurs. like getting ready before the party starts, we love a pre-game 🎀✨

a call to __pmAFisempty returns 1 or 0 depending on whether the event queue is empty or not. yes bestie, it's a vibe check 🦋

---

💜 CAVEATS 💜

these routines rely on setitimer(2) and manipulate the handling of SIGALRM signals, and hence are probably ill-suited for applications that require direct and concurrent access to these services and resources. sharing is not caring here, sorry 💀

if the callback functions are slow, or delayed, it is possible that the event scheduling could fall behind and never catchup. when this begins to happen, events are silently skipped and rescheduled at the earliest possible time in the future according to the fixed schedule defined by the time of the call to __pmAFsetup and the value of the start and delta arguments (or defined by the time of the call to __pmAFregister and the value of the delta argument). the schedule does not care about your feelings or your slow callback 😭

in addition, the semantics of the interval timer(s) and the global state needed to support these services demand that applications calling these routines must do so from a single thread. this restriction is enforced at the PMAPI(3), where routines may return the error code PM_ERR_THREAD if the library detects calls from more than one thread. one thread only, no polyamory 🚫🧵

---

🔥 DIAGNOSTICS 🔥

__pmAFsetup, __pmAFregister and __pmAFunregister return values less than zero in the case of an error. these values are PCP error codes, and may be used to produce error messages via pmErrStr(3). so when it goes wrong you can actually find out why, we love transparency 💖

the routines support the standard PCP debug tracing, and the af option (or -D af on the command line) will produce diagnostics on standard error that trace the enqueuing and execution of events. it's giving commentary track on your own life 🎧✨

---

🌟 SEE ALSO 🌟

PMAPI(3)

---

and that's the whole page bestie!! this one came from Performance Co-Pilot (PCP), filed under PMAF(3) — go forth and schedule your events responsibly, and remember: async-signal-safe only, single thread only, no cap 💅💖🦋