1PMDAEVENTQUEUE(3)          Library Functions Manual          PMDAEVENTQUEUE(3)
2
3
4

NAME

6       pmdaEventNewQueue, pmdaEventNewActiveQueue, pmdaEventQueueHandle, pm‐
7       daEventQueueAppend, pmdaEventQueueShutdown, pmdaEventQueueRecords, pm‐
8       daEventQueueClients, pmdaEventQueueCounter, pmdaEventQueueBytes, pm‐
9       daEventQueueMemory - utilities for PMDAs managing event queues
10

C SYNOPSIS

12       #include <pcp/pmapi.h>
13       #include <pcp/pmda.h>
14
15       int pmdaEventNewQueue(const char *name, size_t maxmem);
16       int pmdaEventNewActiveQueue(const char *name, size_t maxmem,  int
17               nclients);
18       int pmdaEventQueueHandle(const char *name);
19       int pmdaEventQueueAppend(int handle, void *buffer, size_t bytes, struct
20               timeval *tv);
21       int pmdaEventQueueShutdown(int handle);
22
23       typedef int (*pmdaEventDecodeCallBack)(int, void *, int, struct timeval
24               *, void *);
25       int  pmdaEventQueueRecords(int  handle,  pmAtomValue *avp, int context,
26               pmdaEventDecodeCallBack decoder, void *data);
27       int pmdaEventQueueClients(int handle, pmAtomValue *avp);
28       int pmdaEventQueueCounter(int handle, pmAtomValue *avp);
29       int pmdaEventQueueBytes(int handle, pmAtomValue *avp);
30       int pmdaEventQueueMemory(int handle, pmAtomValue *avp);
31
32       cc ... -lpcp_pmda -lpcp
33

DESCRIPTION

35       A Performance Metrics Domain Agent (PMDA) that  exports  event  records
36       must effectively act an event multiplexer.  Events consumed by the PMDA
37       may have to be forwarded on to  any  number  of  monitoring  tools  (or
38       "client  contexts").  These tools may be requesting events at different
39       sampling intervals, and are very unlikely to request an  event  at  the
40       exact  moment it arrives at the PMDA, making some form of event buffer‐
41       ing and queueing scheme a necessity.  Events must be held by  the  PMDA
42       until  either  all  registered  clients have been sent them, or until a
43       memory limit has been reached by the PMDA at which point it  must  dis‐
44       card older events as new ones arrive.
45
46       The  routines  described here are designed to assist the PMDA developer
47       in managing both client contexts and queues of events at a high  level.
48       These  fit  logically  above  lower level primitives, such as those de‐
49       scribed in pmdaEventNewArray(3), and shield the average PMDA  from  the
50       details  of directly building event record arrays for individual client
51       contexts.
52
53       The PMDA registers a new queue of events using either pmdaEventNewQueue
54       or  pmdaEventNewActiveQueue.  These are passed an identifying name (for
55       diagnostic purposes, and for subsequent lookup by pmdaEventQueueLookup)
56       and  maxmem,  an  upper bound on the memory (in bytes) that can be con‐
57       sumed by events in this queue, before beginning to  discard  them  (re‐
58       sulting  in "missed" events for any client that has not kept up).  If a
59       queue is dynamically allocated (such that the  PMDA  may  already  have
60       clients  connected)  the  pmdaEventNewActiveQueue  interface  should be
61       used, with the additional numclients parameter indicating the count  of
62       active  client  connections.   The  return  is a negative error code on
63       failure, suitable for decoding by the pmErrStr(3)  routine.   Any  non-
64       negative  value  indicates  success, and provides a handle suitable for
65       passing into the other API routines.
66
67       For each new event received by the PMDA, the pmdaEventQueueAppend  rou‐
68       tine  should be called, placing that event into the queue identified by
69       handle.  The event itself must be contained in the  passed  in  buffer,
70       having  bytes length.  The timestamp associated with the event (time at
71       which the event occurred) is passed in via the final tv parameter.
72
73       In the PMDAs specific implementation of its fetch callback, when values
74       for an event metric have been requested, the pmdaEventQueueRecords rou‐
75       tine should be used.  It is passed the queue handle and the avp pmAtom‐
76       Value  structure to fill with event records, for the client making that
77       fetch request (identified by the context parameter).  Finally, the PMDA
78       must  also  pass in an event decoding routine, which is responsible for
79       decoding the fields of a single event into the individual event parame‐
80       ters of that event.  The data parameter is an opaque cookie that can be
81       used to pass situation-specific information into each  decoder  invoca‐
82       tion.
83
84       Under  some  situations it is useful for the PMDA to export state about
85       the queues under its control.  The accessor routines -  pmdaEventQueue‐
86       Clients, pmdaEventQueueCounter, pmdaEventQueueBytes and pmdaEventQueue‐
87       Memory provide a mechanism for querying a queue by its handle and fill‐
88       ing in a pmAtomValue structure that the pmdaFetchCallBack method should
89       return.
90

SEE ALSO

92       PMAPI(3), PMDA(3), pmdaEventNewClient(3) and pmdaEventNewArray(3).
93
94
95
96Performance Co-Pilot                  PCP                    PMDAEVENTQUEUE(3)
Impressum