1PMTIME(3) Library Functions Manual PMTIME(3)
2
6 pmTimeConnect, pmTimeDisconnect, pmTimeRecv, pmTimeSendAck, pmTimeShow‐
7 Dialog - time control functions for synchronizing the archive position
8 and update interval between one or more applications
9
11 #include <pcp/pmtime.h>
12 int pmTimeConnect(int port, pmTime *state);
14 int pmTimeDisconnect(int fd);
15 int pmTimeSendAck(int fd, struct timeval *fetchTime);
16 int pmTimeShowDialog(int fd, int show);
17 int pmTimeRecv(int fd, pmTime *state);
18 cc ... -lpcp_gui
20
22 These functions form part of the Performance Metrics Applications Pro‐
23 gramming Interface (PMAPI) and are intended to provide a uniform mecha‐
24 nism for applications to both replay archive data and report live data
25 in a time synchronized manner.
26 The pmTime structure has the following fields:
28 typedef struct {
29 unsigned int magic;
30 unsigned int length;
31 pm_tctl_command command;
32 pm_tctl_source source;
33 pm_tctl_state state;
34 pm_tctl_mode mode;
35 struct timeval delta;
36 struct timeval position;
37 struct timeval start; /* archive only */
38 struct timeval end; /* archive only */
39 char data[0]; /* arbitrary length info (TZ) */
40 } pmTime;
41 In the simplest case, the application should call pmTimeConnect to con‐
43 nect to the time control server, pmtime(1), and then repeatedly call
44 pmTimeRecv in the main loop of the application. On success, pmTimeCon‐
45 nect returns a non-negative file descriptor. In applications which
46 have multiple threads of control, rather than simply blocking in pm‐
47 TimeRecv, the file descriptor may be used in calls to select(2). In
48 graphical applications, the file descriptor may be used to interface
49 with the event loop.
50 The port parameter to pmTimeConnect is the port number of the socket on
52 which the time control server is (or will be) listening for new connec‐
53 tions.
54 The state parameter to pmTimeConnect is used to initialize a new time
56 control server or to pass additional information to an existing time
57 control server. The start and finish fields indicate the chronological
58 bounds interesting to the application. The showdialog field indicates
59 whether the time control server should initially show or hide the dia‐
60 log. The position, delta, and data fields indicate the initial archive
61 position, update interval, time zone string and time zone label string.
62 pmTimeRecv blocks until the time control server sends a command mes‐
64 sage. It then updates the state parameter and returns one of the
65 PM_TCTL command identifiers.
66 The PM_TCTL_SET command indicates the application should seek to the
68 archive position (see pmSetMode(3)) returned in the position field of
69 the state parameter.
70 The PM_TCTL_STEP command indicates the application should perform an
72 update, i.e. advance (or rewind, if delta is negative) to the time in‐
73 dicated by position and then fetch new metric values, update the dis‐
74 play or whatever. In order for several application to remain synchro‐
75 nized, the time control server will wait until all applications have
76 acknowledged that they have completed the step command. Applications
77 should call pmTimeSendAck when the step command has been processed.
78 Note that PM_TCTL_STEP is the only command that requires an explicit
79 acknowledgement.
80 The PM_TCTL_VCRMODE command is used by the time control server to indi‐
82 cate the current VCR mode.
83 The value is returned in the vcrmode field of the state parameter
85 passed to pmTimeRecv, and remains valid until the next PM_TCTL_VCRMODE
86 command is received.
87 The PM_TCTL_TZ command indicates the application should use a new time-
89 zone, as indicated in the tz and tzlabel fields of the state parameter.
90 The PM_TCTL_BOUNDS command is sent to all applications when the time
92 control server changes its chronological bounds. This may occur when a
93 new application connects to the time control server or the user changes
94 the bounds manually. Most applications will ignore this command.
95 The PM_TCTL_SHOWDIALOG command will be sent to all applications when
97 the visibility of the time control server changes. This allows appli‐
98 cations to alter the text in menus or buttons to reflect this change.
99 Applications may change the visibility of the time control dialog using
100 the pmTimeShowDialog function. The initial visibility is determined
101 when the time control dialog is first created by an application calling
102 pmTimeConnect with the showdialog field in the state parameter set to
103 the desired value.
104 The pmTimeDisconnect function may be used to close the command socket
106 to the time control server. This is useful when applications need to
107 change the connection mode, e.g. to divorce the current time control
108 server and connect to a new one.
109
111 pmtime(1), PMAPI(3) and pmSetMode(3).
112Performance Co-Pilot Aconex PMTIME(3)