NAME

       pmdaEventNewQueue, pmdaEventNewActiveQueue, pmdaEventQueueHandle, pmdaEventQueueAppend,
       pmdaEventQueueShutdown, pmdaEventQueueRecords, pmdaEventQueueClients, pmdaEventQueueCounter,
       pmdaEventQueueBytes, pmdaEventQueueMemory - utilities for PMDAs managing event queues

C SYNOPSIS

       #include <pcp/pmapi.h>
       #include <pcp/pmda.h>

       int pmdaEventNewQueue(const char *name, size_t maxmem);
       int pmdaEventNewActiveQueue(const char *name, size_t maxmem, int nclients);
       int pmdaEventQueueHandle(const char *name);
       int pmdaEventQueueAppend(int handle, void *buffer, size_t bytes, struct timeval *tv);
       int pmdaEventQueueShutdown(int handle);

       typedef int (*pmdaEventDecodeCallBack)(int, void *, int, struct timeval *, void *);
       int pmdaEventQueueRecords(int handle, pmAtomValue *avp, int context, pmdaEventDecodeCallBack decoder,
                                 void *data);
       int pmdaEventQueueClients(int handle, pmAtomValue *avp);
       int pmdaEventQueueCounter(int handle, pmAtomValue *avp);
       int pmdaEventQueueBytes(int handle, pmAtomValue *avp);
       int pmdaEventQueueMemory(int handle, pmAtomValue *avp);

       cc ... -lpcp_pmda -lpcp

DESCRIPTION

       A Performance Metrics Domain Agent (PMDA) that exports event records must effectively act an event multi‐
       plexer.   Events  consumed  by the PMDA may have to be forwarded on to any number of monitoring tools (or
       "client contexts").  These tools may be requesting events at different sampling intervals, and  are  very
       unlikely  to  request  an  event  at  the  exact moment it arrives at the PMDA, making some form of event
       buffering and queuing scheme a necessity.  Events must be held by the PMDA until  either  all  registered
       clients  have been sent them, or until a memory limit has been reached by the PMDA at which point it must
       discard older events as new ones arrive.

       The routines described here are designed to assist the PMDA developer in managing  both  client  contexts
       and  queues  of  events at a high level.  These fit logically above lower level primitives, such as those
       described in pmdaEventNewArray(3), and shield the average PMDA from  the  details  of  directly  building
       event record arrays for individual client contexts.

       The  PMDA  registers  a  new  queue  of events using either pmdaEventNewQueue or pmdaEventNewActiveQueue.
       These are passed an identifying name (for diagnostic purposes, and for  subsequent  lookup  by  pmdaEven‐
       tQueueHandle)  and maxmem, an upper bound on the memory (in bytes) that can be consumed by events in this
       queue, before beginning to discard them (resulting in "missed" events for any client that  has  not  kept
       up).  If a queue is dynamically allocated (such that the PMDA may already have clients connected) the pm‐
       daEventNewActiveQueue  interface  should  be  used, with the additional nclients parameter indicating the
       count of active client connections.  The return is a negative error code on failure, suitable for  decod‐
       ing by the pmErrStr(3) routine.  Any non-negative value indicates success, and provides a handle suitable
       for passing into the other API routines.

       For  each new event received by the PMDA, the pmdaEventQueueAppend routine should be called, placing that
       event into the queue identified by handle.  The event itself must be contained in the passed  in  buffer,
       having  bytes  length.   The  timestamp  associated  with the event (time at which the event occurred) is
       passed in via the final tv parameter.

       In the PMDAs specific implementation of its fetch callback, when values for an event metric have been re‐
       quested, the pmdaEventQueueRecords routine should be used.  It is passed the queue  handle  and  the  avp
       pmAtomValue structure to fill with event records, for the client making that fetch request (identified by
       the  context parameter).  Finally, the PMDA must also pass in an event decoding routine, which is respon‐
       sible for decoding the fields of a single event into the individual event parameters of that event.   The
       data  parameter is an opaque cookie that can be used to pass situation-specific information into each de‐
       coder invocation.

       Under some situations it is useful for the PMDA to export state about the queues under its control.   The
       accessor routines - pmdaEventQueueClients, pmdaEventQueueCounter, pmdaEventQueueBytes and pmdaEventQueue‐
       Memory provide a mechanism for querying a queue by its handle and filling in a pmAtomValue structure that
       the pmdaFetchCallBack method should return.

SEE ALSO

       PMAPI(3), PMDA(3), pmdaEventNewClient(3) and pmdaEventNewArray(3).

Performance Co-Pilot                                   PCP                                     PMDAEVENTQUEUE(3)