1PMAF(3) Library Functions Manual PMAF(3)
2
6 __pmAFsetup, __pmAFregister, __pmAFunregister, __pmAFblock, __pmAFun‐
7 block, __pmAFisempty - event queue services for periodic asynchronous
8 callbacks
9
11 #include "pmapi.h"
12 #include "libpcp.h"
13 int __pmAFsetup(const struct timeval *start, const struct timeval
15 *delta, void *data, void (*func)(int, void *));
16 int __pmAFregister(const struct timeval *delta, void *data,
17 void (*func)(int, void *));
18 int __pmAFunregister(int afid);
19 void __pmAFblock(void);
20 void __pmAFunblock(void);
21 int __pmAFisempty(void);
22 cc ... -lpcp
24
26 This documentation is intended for internal Performance Co-Pilot (PCP)
27 developer use.
28 These interfaces are not part of the PCP APIs that are guaranteed to
30 remain fixed across releases, and they may not work, or may provide
31 different semantics at some point in the future.
32
34 The routines implement an event queue and callback framework that sup‐
35 ports periodic evaluation of a series of events with varying frequen‐
36 cies for Performance Co-Pilot (PCP) applications.
37 The pmlogger(1) application, the pmdatrace(1) PMDA and the pmdahot‐
39 proc(1) PMDA are the principal users of these services.
40 An event is created by calling __pmAFsetup or __pmAFregister and on
42 success the return value is an event number greater than zero. The
43 event has associated event data identified by the opaque pointer data.
44 The event will occur with frequency delta and each time the event oc‐
45 curs the function func will be called with the event number and the
46 event data as arguments.
47 If __pmAFsetup is used then the first event is scheduled for the cur‐
49 rent time plus start, else if __pmAFregister is used then the first
50 event is scheduled for the current time plus delta.
51 func is called in a SIGALRM signal handler context and so the routines
53 that may be safely called from func are restricted to the so-called
54 async-signal-safe set. In particular there must be no Standard I/O
55 calls nor calls to any of the malloc(3) routines to modify the state of
56 the heap. Refer to the Pointer to a Function Section of the
57 POSIX.1-2013 document at http://pubs.opengroup.org/on‐
58 linepubs/9699919799/functions/V2_chap02.html for a fuller description.
59 The safest and simplest class of func routines are those that do mini‐
61 mal processing, set some global state and return. The real work asso‐
62 ciated with the event is done subsequently from the application's main
63 loop when the global state change is detected.
64 Once the event occurs and the callback has been executed, the event
66 will be rescheduled for delta into the future, except if all the fields
67 of delta are zero, in which case the event will not be rescheduled (a
68 ``one trip'' event).
69 Internally, events are processed serially so there is no possibility of
71 nested callbacks or re-entrant callbacks from the event management rou‐
72 tines.
73 Given an event number afid, __pmAFunregister will permanently remove
75 the corresponding entry from the event queue.
76 To control the event queue processing, __pmAFblock and __pmAFunblock
78 may be used to explicitly block and unblock the dispatch of events.
79 This is most useful when the caller wishes to set up a number of events
80 via __pmAFsetup or __pmAFregister and complete the registration phase
81 before the first event callback occurs.
82 A call to __pmAFisempty returns 1 or 0 depending on whether the event
84 queue is empty or not.
85
87 PMAPI(3)
88
90 __pmAFsetup, __pmAFregister and __pmAFunregister return values less
91 than zero in the case of an error. These values are PCP error codes,
92 and may be used to produce error messages via pmErrStr(3).
93 The routines support the standard PCP debug tracing, and the af option
95 (or -D af on the command line) will produce diagnostics on standard er‐
96 ror that trace the enqueuing and execution of events.
97
99 These routines rely on setitimer(2) and manipulate the handling of
100 SIGALRM signals, and hence are probably ill-suited for applications
101 that require direct and concurrent access to these services and re‐
102 sources.
103 If the callback functions are slow, or delayed, it is possible that the
105 event scheduling could fall behind and never catchup. When this begins
106 to happen, events are silently skipped and rescheduled at the earliest
107 possible time in the future according to the fixed schedule defined by
108 the time of the call to __pmAFsetup and the value of the start and
109 delta arguments (or defined by the time of the call to __pmAFregister
110 and the value of the delta argument).
111 In addition, the semantics of the interval timer(s) and the global
113 state needed to support these services demand that applications calling
114 these routines must do so from a single thread. This restriction is
115 enforced at the PMAPI(3), where routines may return the error code
116 PM_ERR_THREAD if the library detects calls from more than one thread.
117Performance Co-Pilot PCP PMAF(3)