NAME

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

C SYNOPSIS

       #include <pcp/pmapi.h>
       #include <pcp/impl.h>

       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

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  registered by calling __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 (the first instance will
       be delta after the current time when the event is registered), and  each  time  the  event
       occurs  the  function  func  will  be  called  with the event number and the event data as
       arguments.

       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 __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.

SEE ALSO

       PMAPI(3)

DIAGNOSTICS

       __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 value DBG_TRACE_AF (or -D  af
       on  the command line) will produce diagnostics on standard error that trace the enqueueing
       and execution of events.

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 on the future according to the fixed
       schedule  defined  by  the  time  of the call to __pmAFregister and the value of the delta
       argument to __pmAFregister.

       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.