# pmdaeventqueue

## 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  multiplexer.   Events  con‐
           sumed  by  the  PMDA  may have to be forwarded on to any number of
           monitoring tools (or "client contexts").  These tools may  be  re‐
           questing  events at different sampling intervals, and are very un‐
           likely to request an event at the exact moment it arrives  at  the
           PMDA, making some form of event buffering and queuing scheme a ne‐
           cessity.   Events must be held by the PMDA until either all regis‐
           tered 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 devel‐
           oper 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  **pmdaEvent‐**
           **NewQueue** or **pmdaEventNewActiveQueue**.  These are passed an identi‐
           fying _name_ (for diagnostic purposes, and for subsequent lookup  by
           **pmdaEventQueueHandle**) and _maxmem_ , an upper bound on the memory (in
           bytes) that can be consumed by events in this queue, before begin‐
           ning  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 **pmdaEvent‐**
           **NewActiveQueue** interface  should  be  used,  with  the  additional
           _nclients_  parameter  indicating the count of active client connec‐
           tions.  The return is a negative error code on  failure,  suitable
           for  decoding  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 iden‐
           tified 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 requested, the **pmdaEven‐**
           **tQueueRecords** routine should be used.  It is passed the queue _han‐_
           _dle_ and the _avp_ pmAtomValue structure to fill with event  records,
           for  the  client making that fetch request (identified by the _con‐_
           _text_ parameter).  Finally, the PMDA must also pass in an event de‐
           coding routine, which is responsible 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 _decoder_ invocation.
    
           Under  some  situations  it is useful for the PMDA to export state
           about the queues under its control.  The accessor routines  -  **pm‐**
           **daEventQueueClients** ,   **pmdaEventQueueCounter** ,  **pmdaEventQueueBytes**
           and **pmdaEventQueueMemory** provide a mechanism for querying a  queue
           by  its  _handle_  and  filling  in a **pmAtomValue** structure that the
           **pmdaFetchCallBack** method should return.
    


* * *