NAME

       __pmAFsetup,  __pmAFregister,  __pmAFunregister,  __pmAFblock, __pmAFunblock, __pmAFisempty - event queue
       services for periodic asynchronous callbacks

C SYNOPSIS

       #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(int afid);
       void __pmAFblock(void);
       void __pmAFunblock(void);
       int __pmAFisempty(void);

       cc ... -lpcp

CAVEAT

       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.

DESCRIPTION

       The  routines  implement an event queue and callback framework that supports periodic evaluation of a se‐
       ries of events with varying frequencies for Performance Co-Pilot (PCP) applications.

       The pmlogger(1) application, the pmdatrace(1) PMDA and the pmdahotproc(1) PMDA are the principal users of
       these services.

       An event is created by calling __pmAFsetup or __pmAFregister and on success the return value is an  event
       number  greater  than  zero.   The event has associated event data identified by the opaque pointer data.
       The event will occur with frequency delta and each time the event occurs the function func will be called
       with the event number and the event data as arguments.

       If __pmAFsetup is used then the first event is scheduled  for  the  current  time  plus  start,  else  if
       __pmAFregister is used then the first event is scheduled for the current time plus delta.

       func  is  called  in  a SIGALRM signal handler context and so the routines that may be safely called from
       func are restricted to the so-called async-signal-safe set.  In particular there must be no Standard  I/O
       calls  nor  calls to any of the malloc(3) routines to modify the state of the heap.  Refer to the Pointer
       to   a   Function   Section   of   the    POSIX.1-2013    document    at    http://pubs.opengroup.org/on‐
       linepubs/9699919799/functions/V2_chap02.html for a fuller description.

       The  safest  and  simplest  class  of func 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  application'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 for delta into
       the future, except if all the fields of delta are zero, in which case the event will not  be  rescheduled
       (a ``one trip'' event).

       Internally,  events  are  processed serially so there is no possibility of nested callbacks or re-entrant
       callbacks from the event management routines.

       Given an event number afid, __pmAFunregister will permanently remove the  corresponding  entry  from  the
       event queue.

       To  control the event queue processing, __pmAFblock and __pmAFunblock may 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 __pmAFsetup or __pmAFregister and complete the registration phase before the first event callback oc‐
       curs.

       A call to __pmAFisempty returns 1 or 0 depending on whether the event queue is empty or not.

CAVEATS

       These  routines rely on setitimer(2) and manipulate the handling of SIGALRM signals, and hence are proba‐
       bly ill-suited for applications that require direct and concurrent  access  to  these  services  and  re‐
       sources.

       If  the  callback functions are slow, or delayed, it is possible that the event scheduling could fall be‐
       hind 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
       __pmAFsetup and the value of the start and delta arguments (or  defined  by  the  time  of  the  call  to
       __pmAFregister and the value of the delta 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 restriction is en‐
       forced  at  the  PMAPI(3),  where routines may return the error code PM_ERR_THREAD if the library detects
       calls from more than one thread.

DIAGNOSTICS

       __pmAFsetup, __pmAFregister and __pmAFunregister return values less than zero in the case  of  an  error.
       These values are PCP error codes, and may be used to produce error messages via pmErrStr(3).

       The  routines  support  the  standard PCP debug tracing, and the af option (or -D af on the command line)
       will produce diagnostics on standard error that trace the enqueuing and execution of events.

SEE ALSO

       PMAPI(3)

Performance Co-Pilot                                   PCP                                               PMAF(3)