1PMAF(3)                    Library Functions Manual                    PMAF(3)
2
3
4

NAME

6       __pmAFregister,     __pmAFunregister,    __pmAFblock,    __pmAFunblock,
7       __pmAFisempty - event queue services for  periodic  asynchronous  call‐
8       backs
9

C SYNOPSIS

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

DESCRIPTION

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

SEE ALSO

64       PMAPI(3)
65

DIAGNOSTICS

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

CAVEATS

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)