1PMTIME(3)                  Library Functions Manual                  PMTIME(3)
2
3
4

NAME

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

C SYNOPSIS

11       #include <pcp/pmtime.h>
12
13       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
19       cc ... -lpcp_gui
20

DESCRIPTION

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
27       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
42       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
47       pmTimeRecv,  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
51       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
55       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
63       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
67       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
71       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
73       indicated 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
81       The PM_TCTL_VCRMODE command is used by the time control server to indi‐
82       cate the current VCR mode.
83
84       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
88       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
91       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
96       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
105       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

SEE ALSO

111       pmtime(1), PMAPI(3) and pmSetMode(3).
112
113
114
115Performance Co-Pilot                Aconex                           PMTIME(3)
Impressum