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 series 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/onlinepubs/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 occurs.

       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 probably ill-suited for applications that require direct and  concurrent  access
       to these services and resources.

       If  the  callback functions are slow, or delayed, it is possible that the event scheduling
       could fall behind 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 enforced 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)