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