1PMDAEVENTQUEUE(3) Library Functions Manual PMDAEVENTQUEUE(3)
2
6 pmdaEventNewQueue, pmdaEventNewActiveQueue, pmdaEventQueueHandle, pm‐
7 daEventQueueAppend, pmdaEventQueueShutdown, pmdaEventQueueRecords, pm‐
8 daEventQueueClients, pmdaEventQueueCounter, pmdaEventQueueBytes, pm‐
9 daEventQueueMemory - utilities for PMDAs managing event queues
10
12 #include <pcp/pmapi.h>
13 #include <pcp/pmda.h>
14 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 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 cc ... -lpcp_pmda -lpcp
33
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 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 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 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 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 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
92 PMAPI(3), PMDA(3), pmdaEventNewClient(3) and pmdaEventNewArray(3).
93Performance Co-Pilot PCP PMDAEVENTQUEUE(3)