diff options
Diffstat (limited to 'man/man3/pmdaeventqueue.3')
| -rw-r--r-- | man/man3/pmdaeventqueue.3 | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/man/man3/pmdaeventqueue.3 b/man/man3/pmdaeventqueue.3 new file mode 100644 index 0000000..43f243b --- /dev/null +++ b/man/man3/pmdaeventqueue.3 @@ -0,0 +1,190 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2011-2012 Nathan Scott. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAEVENTQUEUE 3 "PCP" "Performance Co-Pilot" +.SH NAME +.ad l +\f3pmdaEventNewQueue\f1, +\f3pmdaEventNewActiveQueue\f1, +\f3pmdaEventQueueHandle\f1, +\f3pmdaEventQueueAppend\f1, +\f3pmdaEventQueueRecords\f1, +\f3pmdaEventQueueClients\f1, +\f3pmdaEventQueueCounter\f1, +\f3pmdaEventQueueBytes\f1, +\f3pmdaEventQueueMemory\f1 \- utilities for PMDAs managing event queues +.br +.ad +.SH "C SYNOPSIS" +.ft 3 +.nf +#include <pcp/pmapi.h> +#include <pcp/impl.h> +#include <pcp/pmda.h> +.fi +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int pmdaEventNewQueue(const char *\fIname\fP, size_t \fImaxmem\fP); +.br +.ti -8n +int pmdaEventNewActiveQueue(const char *\fIname\fP, size_t \fImaxmem\fP, int \fInclients\fP); +.br +.ti -8n +int pmdaEventQueueHandle(const char *\fIname\fP); +.br +.ti -8n +int pmdaEventQueueAppend(int \fIhandle\fP, void *\fIbuffer\fP, size_t \fIbytes\fP, struct timeval *\fItv\fP); +.br +.sp +.in +.hy +.ad +.in +8n +.ti -8n +typedef int (*pmdaEventDecodeCallBack)(int, void *, int, struct timeval *, void *); +.br +.ti -8n +int pmdaEventQueueRecords(int \fIhandle\fP, pmAtomValue *\fIavp\fP, int \fIcontext\fP, pmdaEventDecodeCallBack \fIdecoder\fP, void *\fIdata\fP); +.br +.ti -8n +int pmdaEventQueueClients(int \fIhandle\fP, pmAtomValue *\fIavp\fP); +.br +.ti -8n +int pmdaEventQueueCounter(int \fIhandle\fP, pmAtomValue *\fIavp\fP); +.br +.ti -8n +int pmdaEventQueueBytes(int \fIhandle\fP, pmAtomValue *\fIavp\fP); +.br +.ti -8n +int pmdaEventQueueMemory(int \fIhandle\fP, pmAtomValue *\fIavp\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +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. +.PP +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 +.BR pmdaEventNewArray (3), +and shield the average PMDA from the details of directly building event +record arrays for individual client contexts. +.PP +The PMDA registers a new queue of events using either +.B pmdaEventNewQueue +or +.BR pmdaEventNewActiveQueue . +These are passed an identifying +.I name +(for diagnostic purposes, and for subsequent lookup by +.BR pmdaEventQueueLookup ) +and +.IR 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 +.B pmdaEventNewActiveQueue +interface should be used, with the additional +.I numclients +parameter indicating the count of active client connections. +The return is a negative error code on failure, suitable for decoding +by the +.BR pmErrStr (3) +routine. +Any non-negative value indicates success, and provides a +.I handle +suitable for passing into the other API routines. +.PP +For each new event received by the PMDA, the +.B pmdaEventQueueAppend +routine should be called, placing that event into the queue identified +by +.IR handle . +The event itself must be contained in the passed in +.IR buffer , +having +.I bytes +length. +The timestamp associated with the event (time at which the event +occurred) is passed in via the final +.I tv +parameter. +.PP +In the PMDAs specific implementation of its fetch callback, when values +for an event metric have been requested, the +.BR pmdaEventQueueRecords +routine should be used. +It is passed the queue +.I handle +and the +.I avp +pmAtomValue structure to fill with event records, for the client making +that fetch request (identified by the +.I 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 +.I data +parameter is an opaque cookie that can be used to pass situation-specific +information into each +.I decoder +invocation. +.PP +Under some situations it is useful for the PMDA to export state about +the queues under its control. +The accessor routines \- +.BR pmdaEventQueueClients , +.BR pmdaEventQueueCounter , +.BR pmdaEventQueueBytes +and +.BR pmdaEventQueueMemory +provide a mechanism for querying a queue by its +.I handle +and filling in a +.B pmAtomValue +structure that the +.B pmdaFetchCallBack +method should return. +.SH SEE ALSO +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaEventNewClient (3) +and +.BR pmdaEventNewArray (3). |