1PMAF(3) Library Functions Manual PMAF(3)
2
3
4
6 __pmAFregister, __pmAFunregister, __pmAFblock, __pmAFunblock,
7 __pmAFisempty - event queue services for periodic asynchronous call‐
8 backs
9
11 #include <pcp/pmapi.h>
12 #include <pcp/impl.h>
13
14 int __pmAFregister(const struct timeval *delta, void *data, void (*func)(int, void *))
15
16 int __pmAFunregister(int afid)
17
18 void __pmAFblock(void)
19
20 void __pmAFunblock(void)
21
22 int __pmAFisempty(void)
23
24 cc ... -lpcp
25
27 The routines implement an event queue and callback framework that sup‐
28 ports periodic evaluation of a series of events with varying frequen‐
29 cies for Performance Co-Pilot (PCP) applications.
30
31 The pmlogger(1) application, the pmdatrace(1) PMDA and the pmdahot‐
32 proc(1) PMDA are the principal users of these services.
33
34 An event is registered by calling __pmAFregister, and on success the
35 return value is an event number greater than zero. The event has asso‐
36 ciated event data identified by the opaque pointer data. The event
37 will occur with frequency delta (the first instance will be delta after
38 the current time when the event is registered), and each time the event
39 occurs the function func will be called with the event number and the
40 event data as arguments.
41
42 Once the event occurs and the callback has been executed, the event
43 will be rescheduled for delta into the future, except if all the fields
44 of delta are zero, in which case the event will not be rescheduled (a
45 ``one trip'' event).
46
47 Internally, events are processed serially so there is no possibility of
48 nested callbacks or re-entrant callbacks from the event management rou‐
49 tines.
50
51 Given an event number afid, __pmAFunregister will permanently remove
52 the corresponding entry from the event queue.
53
54 To control the event queue processing, __pmAFblock and __pmAFunblock
55 may be used to explicitly block and unblock the dispatch of events.
56 This is most useful when the caller wishes to set up a number of events
57 via __pmAFregister and complete the registration phase before the first
58 event callback occurs.
59
60 A call to __pmAFisempty returns 1 or 0 depending on whether the event
61 queue is empty or not.
62
64 PMAPI(3)
65
67 __pmAFregister and __pmAFunregister return values less than zero in the
68 case of an error. These values are PCP error codes, and may be used to
69 produce error messages via pmErrStr(3).
70
71 The routines support the standard PCP debug tracing, and the value
72 DBG_TRACE_AF (or -D af on the command line) will produce diagnostics on
73 standard error that trace the enqueueing and execution of events.
74
76 These routines rely on setitimer(2) and manipulate the handling of
77 SIGALRM signals, and hence are probably ill-suited for applications
78 that require direct and concurrent access to these services and
79 resources.
80
81 If the callback functions are slow, or delayed, it is possible that the
82 event scheduling could fall behind and never catchup. When this begins
83 to happen, events are silently skipped and rescheduled at the earliest
84 possible time on the future according to the fixed schedule defined by
85 the time of the call to __pmAFregister and the value of the delta argu‐
86 ment to __pmAFregister.
87
88
89
90Performance Co-Pilot SGI PMAF(3)