trusty (3) __pmAFisempty.3.gz

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.