NAME

       __pmAFregister,  __pmAFunregister,  __pmAFblock, __pmAFun­
       block, __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 frame­
       work 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 ser­
       vices.

       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 fre­
       quency 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 perma­
       nently remove  the  corresponding  entry  from  the  event
       queue.

       __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  __pmAFreg­
       ister 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

       On  Irix  these  routines are part of the libpcp_dev.a, so
       your  compile   lines   should   include   -lpcp_dev   and
       -DHAVE_DEV_IN_LIBPCP where necessary.

       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 pos­
       sible  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.


Man(1) output converted with man2html