PMDAEVENTQUEUE(3)         Library Functions Manual         PMDAEVENTQUEUE(3)

NAME         top

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

C SYNOPSIS         top

       #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
       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         top

       A Performance Metrics Domain Agent (PMDA) that exports event records
       must effectively act an event multiplexer.  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 queueing 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 pmdaEventQueueLookup) 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 pmdaEventNewActiveQueue
       interface should be used, with the additional numclients parameter
       indicating the count of active client connections.  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
       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 requested, 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 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 -
       pmdaEventQueueClients, 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.

SEE ALSO         top

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

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨⟩.
       If you have a bug report for this manual page, send it to  This page was obtained from the project's upstream
       Git repository ⟨⟩ on
       2017-09-15.  If you discover any rendering problems in this HTML ver‐
       sion of the page, or you believe there is a better or more up-to-date
       source for the page, or you have corrections or improvements to the
       information in this COLOPHON (which is not part of the original man‐
       ual page), send a mail to

Performance Co-Pilot                 PCP                   PMDAEVENTQUEUE(3)

Pages that refer to this page: pmdaeventarray(3)pmdaeventclient(3)