# __pmaf

## 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 rou‐
           tines 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 ap‐
           plication'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 possibil‐
           ity of nested callbacks or re-entrant  callbacks  from  the  event
           management routines.
    
           Given  an event number _afid_ , **__pmAFunregister** will permanently re‐
           move the corresponding entry from the event queue.
    
           To control the event queue processing, **__pmAFblock** and  **__pmAFun‐**
           **block** 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 applica‐
           tions 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 **__pmAF‐**
           **setup** 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 re‐
           striction 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 er‐
           ror  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.
    


* * *