HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |C SYNOPSIS |CAVEAT |DESCRIPTION |CAVEATS |DIAGNOSTICS |SEE ALSO |COLOPHON | |
PMAF(3) Library Functions ManualPMAF(3)__pmAFsetup,__pmAFregister,__pmAFunregister,__pmAFblock,__pmAFunblock,__pmAFisempty- event queue services for periodic asynchronous callbacks
#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(intafid);void __pmAFblock(void);void __pmAFunblock(void);int __pmAFisempty(void);cc ... -lpcp
This documentation is intended for internal Performance Co-Pilot (PCP) developer use. 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.
The 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. Thepmlogger(1) application, thepmdatrace(1) PMDA and thepmdahotproc(1) PMDA are the principal users of these services. An event is created by calling__pmAFsetupor__pmAFregisterand on success the return value is an event number greater than zero. The event has associated event data identified by the opaque pointerdata. The event will occur with frequencydelta and each time the event occurs the functionfunc will be called with the event number and the event data as arguments. If__pmAFsetupis used then the first event is scheduled for the current time plusstart, else if__pmAFregisteris used then the first event is scheduled for the current time plusdelta.func is called in a SIGALRM signal handler context and so the rou‐ tines that may be safely called fromfunc are restricted to the so-calledasync-signal-safe set. In particular there must be no Standard I/O calls nor calls to any of themalloc(3) routines to modify the state of the heap. Refer to thePointer to a Function Section of the POSIX.1-2013 document athttp://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html for a fuller description. The safest and simplest class offunc 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 ap‐ plication's main loop when the global state change is detected. Once the event occurs and the callback has been executed, the event will be rescheduled fordelta into the future, except if all the fields ofdelta are zero, in which case the event will not be rescheduled (a ``one trip'' event). Internally, events are processed serially so there is no possibil‐ ity of nested callbacks or re-entrant callbacks from the event management routines. Given an event numberafid,__pmAFunregisterwill permanently re‐ move the corresponding entry from the event queue. To control the event queue processing,__pmAFblockand__pmAFun‐blockmay 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__pmAFsetupor__pmAFregisterand complete the registration phase before the first event callback occurs. A call to__pmAFisemptyreturns 1 or 0 depending on whether the event queue is empty or not.
These routines rely onsetitimer(2) and manipulate the handling ofSIGALRMsignals, and hence are probably ill-suited for applica‐ tions that require direct and concurrent access to these services and resources. 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__pmAF‐setupand the value of thestart anddelta arguments (or defined by the time of the call to__pmAFregisterand the value of thedelta argument). 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 re‐ striction is enforced at thePMAPI(3), where routines may return the error codePM_ERR_THREADif the library detects calls from more than one thread.
__pmAFsetup,__pmAFregisterand__pmAFunregisterreturn values less than zero in the case of an error. These values are PCP er‐ ror codes, and may be used to produce error messages viapmErrStr(3). The routines support the standard PCP debug tracing, and theaf option (or-D afon the command line) will produce diagnostics on standard error that trace the enqueuing and execution of events.
PMAPI(3)
This page is part of thePCP (Performance Co-Pilot) project. In‐ formation about the project can be found at ⟨http://www.pcp.io/⟩. If you have a bug report for this manual page, send it to pcp@groups.io. This page was obtained from the project's upstream Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-08-11.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgPerformance Co-Pilot PCPPMAF(3)Pages that refer to this page:pmapi_internal(3)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |