pmTimeConnect,
pmTimeDisconnect,
pmTimeRecv,
pmTimeSendAck,
pmTimeShowDialog - time control functions for
synchronizing the archive position and update interval between one or more
applications
#include <pcp/pmtime.h>
int pmTimeConnect(int
port, pmTime *
state);
int pmTimeDisconnect(int
fd);
int pmTimeSendAck(int
fd, struct timeval *
fetchTime);
int pmTimeShowDialog(int
fd, int
show);
int pmTimeRecv(int
fd, pmTime *
state);
cc ... -lpcp_gui
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.
The
pmTime structure has the following fields:
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 the simplest case, the application should call
pmTimeConnect to
connect to the time control server,
pmtime(1), and then repeatedly call
pmTimeRecv in the main loop of the application. On success,
pmTimeConnect returns a non-negative file descriptor. In applications
which have multiple threads of control, rather than simply blocking in
pmTimeRecv, the file descriptor may be used in calls to
select(2). In graphical applications, the file descriptor may be used
to interface with the event loop.
The
port parameter to
pmTimeConnect is the port number of the
socket on which the time control server is (or will be) listening for new
connections.
The state parameter to
pmTimeConnect is used to initialize a new time
control server or to pass additional information to an existing time control
server. The
start and
finish fields indicate the chronological
bounds interesting to the application. The
showdialog field indicates
whether the time control server should initially show or hide the dialog. The
position,
delta, and
data fields indicate the initial
archive position, update interval, time zone string and time zone label
string.
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.
The PM_TCTL_SET command indicates the application should seek to the archive
position (see
pmSetMode(3)) returned in the position field of the state
parameter.
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.
The PM_TCTL_VCRMODE command is used by the time control server to indicate the
current VCR mode.
The value is returned in the vcrmode field of the state parameter passed to
pmTimeRecv, and remains valid until the next PM_TCTL_VCRMODE command is
received.
The PM_TCTL_TZ command indicates the application should use a new time- zone, as
indicated in the
tz and
tzlabel fields of the state parameter.
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.
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
pmTimeShowDialog function. The initial visibility is determined when
the time control dialog is first created by an application calling
pmTimeConnect with the showdialog field in the state parameter set to
the desired value.
The
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.
pmtime(1),
PMAPI(3) and
pmSetMode(3).