pmdaeventqueue(3) — Linux manual page

PMDAEVENTQUEUE(3)       Library Functions Manual       PMDAEVENTQUEUE(3)

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  con‐
               text, 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
       necessity.  Events must be held by the PMDA until either all reg‐
       istered  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 de‐
       veloper 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
       beginning  to  discard them (resulting in "missed" events for any
       client that has not kept up).  If a queue is dynamically allocat‐
       ed (such that the PMDA may already have  clients  connected)  the
       pmdaEventNewActiveQueue  interface should be used, with the addi‐
       tional nclients 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-nega‐
       tive  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
       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 in‐
       vocation.

       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.

SEE ALSO

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

COLOPHON

       This page is part of the PCP (Performance Co-Pilot) project.  In‐
       formation about the project can be found at ⟨http://www.pcp.io/⟩.
       If  you  have  a  bug  report  for  this  manual page, send it to
       pcp@groups.io.   This  page  was  obtained  from  the   project's
       upstream                      Git                      repository
       ⟨https://github.com/performancecopilot/pcp.git⟩  on   2024-06-14.
       (At  that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  If you discover any rendering
       problems in this HTML version 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 manual page), send a mail to
       man-pages@man7.org

Performance Co-Pilot               PCP                 PMDAEVENTQUEUE(3)

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

---