1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
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).
|
