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

NAME

6       __pmAFsetup,  __pmAFregister,  __pmAFunregister, __pmAFblock, __pmAFun‐
7       block, __pmAFisempty - event queue services for  periodic  asynchronous
8       callbacks
9

C SYNOPSIS

11       #include "pmapi.h"
12       #include "libpcp.h"
13
14       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
23       cc ... -lpcp
24

CAVEAT

26       This  documentation is intended for internal Performance Co-Pilot (PCP)
27       developer use.
28
29       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

DESCRIPTION

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
38       The pmlogger(1) application, the pmdatrace(1)  PMDA  and  the  pmdahot‐
39       proc(1) PMDA are the principal users of these services.
40
41       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
48       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
52       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
60       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
65       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
70       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
74       Given an event number afid, __pmAFunregister  will  permanently  remove
75       the corresponding entry from the event queue.
76
77       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
83       A  call  to __pmAFisempty returns 1 or 0 depending on whether the event
84       queue is empty or not.
85

SEE ALSO

87       PMAPI(3)
88

DIAGNOSTICS

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
94       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

CAVEATS

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
104       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
112       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.
117
118
119
120Performance Co-Pilot                  PCP                              PMAF(3)
Impressum