Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

__pmafunblock(3) [centos man page]

PMAF(3) 						     Library Functions Manual							   PMAF(3)

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 frequen- cies 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 as- sociated event data identified by the opaque pointer data. The event will occur with frequency delta (the first instance will be delta af- ter 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. Performance Co-Pilot PCP PMAF(3)

Check Out this Related Man Page

PMDAEVENTCLIENT(3)					     Library Functions Manual						PMDAEVENTCLIENT(3)

NAME
pmdaEventNewClient, pmdaEventEndClient, pmdaEventClients - client context tracking interfaces for event queues C SYNOPSIS
#include <pcp/pmapi.h> #include <pcp/impl.h> #include <pcp/pmda.h> int pmdaEventNewClient(int context); int pmdaEventEndClient(int context); int pmdaEventClients(pmAtomValue *avp); cc ... -lpcp_pmda -lpcp DESCRIPTION
A Performance Metrics Domain Agent (PMDA) that exports event records needs to track which clients are connected to it, in order that it can track which events have been sent to which clients so far. Only once an event has been sent to all monitoring tools that registered an in- terest can the event be discarded and any memory reclaimed. The PMDA(3) library provides callback routines for PMDA developers to provide custom handling of client connections and disconnections. If the PMDA is making use of the event queueing mechanism provided by pmdaEventNewQueue(3) and friends, client connections and disconnections must be tracked via calls to pmdaEventNewClient and pmdaEventEndClient respectively. This allows the library to keep track of when events can be discarded from a queue, for example, for the context specified. This parameter is passed into the e_endCallBack function directly, and for other callback functions is available via the e_context field of the pmdaExt structure. Additionally, it can be queried at any time using pmdaGetContext(3). Sometimes it is useful for the PMDA to export a metric indicating the current count of attached clients - this is available using the pm- daEventClients routine, which will fill in the avp pmAtomValue structure on behalf of a PMDA fetch callback routine. SEE ALSO
pmdaEventNewArray(3), pmdaEventNewQueue(3), PMAPI(3), PMDA(3) and pmEventFlagsStr(3). Performance Co-Pilot PCP PMDAEVENTCLIENT(3)
Man Page