diff options
Diffstat (limited to 'man/man3/pmtime.3')
| -rw-r--r-- | man/man3/pmtime.3 | 181 |
1 files changed, 181 insertions, 0 deletions
diff --git a/man/man3/pmtime.3 b/man/man3/pmtime.3 new file mode 100644 index 0000000..900ea16 --- /dev/null +++ b/man/man3/pmtime.3 @@ -0,0 +1,181 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2009 Aconex. 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 PMTIME 3 "Aconex" "Performance Co-Pilot" +.SH NAME +\f3pmtime\f1, +\f3pmTimeConnect\f1, +\f3pmTimeDisconnect\f1, +\f3pmTimeRecv\f1, +\f3pmTimeSendAck\f1, +\f3pmTimeShowDialog\f1 \- +time control functions for synchronizing the archive position and +update interval between one or more applications +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmtime.h> +.sp +int pmTimeConnect(int \fIport\fP, pmTime *\fIstate\fP); +.br +int pmTimeDisconnect(int \fIfd\fP); +.br +int pmTimeSendAck(int \fIfd\fP, struct timeval *\fIfetchTime\fP); +.br +int pmTimeShowDialog(int \fIfd\fP, int \fIshow\fP); +.br +int pmTimeRecv(int \fIfd\fP, pmTime *\fIstate\fP); +.sp +cc ... \-lpcp_gui +.ft 1 +.SH DESCRIPTION +These functions form part of the Performance Metrics Applications +Programming Interface (PMAPI) and are intended to provide a uniform +mechanism for applications to both replay archive data and report +live data in a time synchronized manner. +.PP +The +.I pmTime +structure has the following fields: +.sp 0.5v +.ft CW +.nf +.in +0.25i +typedef struct { + unsigned int magic; + unsigned int length; + pm_tctl_command command; + pm_tctl_source source; + pm_tctl_state state; + pm_tctl_mode mode; + struct timeval delta; + struct timeval position; + struct timeval start; /* archive only */ + struct timeval end; /* archive only */ + char data[0]; /* arbitrary length info (TZ) */ +} pmTime; +.in -0.25i +.fi +.ft R +.PP +In the simplest case, the application should call +.B pmTimeConnect +to connect to the time control server, +.BR pmtime (1), +and then repeatedly call +.B pmTimeRecv +in the main loop of the application. +On success, +.B pmTimeConnect +returns a non-negative file descriptor. +In applications which have multiple threads of control, rather than +simply blocking in +.BR pmTimeRecv , +the file descriptor may be used in calls to +.BR select (2). +In graphical applications, the file descriptor may be used to interface +with the event loop. +.PP +The +.I port +parameter to +.B pmTimeConnect +is the port number of the socket on which the time control server is +(or will be) listening for new connections. +.PP +The state parameter to +.B pmTimeConnect +is used to initialize a new time control server or to pass additional +information to an existing time control server. +The +.I start +and +.I finish +fields indicate the chronological bounds interesting to the application. +The +.I showdialog +field indicates whether the time control server should initially show +or hide the dialog. +The +.IR position , +.IR delta, +and +.I data +fields indicate the initial archive position, update interval, +time zone string and time zone label string. +.PP +.B pmTimeRecv +blocks until the time control server sends a command message. +It then updates the state parameter and returns one of the PM_TCTL +command identifiers. +.PP +The PM_TCTL_SET command indicates the application should seek to the +archive position (see +.BR pmSetMode (3)) +returned in the position field of the state parameter. +.PP +The PM_TCTL_STEP command indicates the application should perform an +update, i.e. advance (or rewind, if delta is negative) to the time +indicated by position and then fetch new metric values, update the +display or whatever. In order for several application to remain +synchronized, the time control server will wait until all applications +have acknowledged that they have completed the step command. +Applications should call pmTimeSendAck when the step command has been +processed. Note that PM_TCTL_STEP is the only command that requires an +explicit acknowledgement. +.PP +The PM_TCTL_VCRMODE command is used by the time control server to +indicate the current VCR mode. +.PP +The value is returned in the vcrmode field of the state parameter passed +to +.BR pmTimeRecv , +and remains valid until the next PM_TCTL_VCRMODE command is received. +.PP +The PM_TCTL_TZ command indicates the application should use a new time- +zone, as indicated in the +.I tz +and +.I tzlabel +fields of the state parameter. +.PP +The PM_TCTL_BOUNDS command is sent to all applications when the time +control server changes its chronological bounds. +This may occur when a new application connects to the time control +server or the user changes the bounds manually. +Most applications will ignore this command. +.PP +The PM_TCTL_SHOWDIALOG command will be sent to all applications when the +visibility of the time control server changes. +This allows applications to alter the text in menus or buttons to +reflect this change. +Applications may change the visibility of the time control dialog using +the +.B pmTimeShowDialog +function. +The initial visibility is determined when +the time control dialog is first created by an application calling +.B pmTimeConnect +with the showdialog field in the state parameter set to the desired value. +.PP +The +.B pmTimeDisconnect +function may be used to close the command socket to the time control server. +This is useful when applications need to change the connection mode, +e.g. to divorce the current time control server and connect to a new one. +.SH SEE ALSO +.BR pmtime (1), +.BR PMAPI (3) +and +.BR pmSetMode (3). |