visiClients/tclVisi/README

   1 #
   2 # $Log: README,v $
   3 # Revision 1.2  1994/07/20 21:48:29  rbi
   4 # Documented Dg commands
   5 #
   6 # Revision 1.1  1994/06/01  17:25:34  rbi
   7 # Initial documentation
   8 #
   9 #
  10
  11 This directory contains the source code for tclVisi, a tcl interface
  12 to the visi library.  The visi library is a C++ interface to paradyn
  13 data (see ../../visi).
  14
  15 To use tclVisi, a programmer writes a tcl application and makes calls
  16 to DataGrid (or Dg) commands.  The Dg commands allow a tcl application
  17 to get information about metrics, resources, and data values.
  18 tclVisi, in turn, makes Dg callback commands to the tcl application to
  19 tell it when configurations have changed and when data is available.
  20
  21 Subdirectories:
  22   src -- source code for tclVisi
  23   tcl -- code for tcl applications
  24   ${PLATFORM} -- platform specific binaries and makefiles
  25
  26 Dg service commands
  27 -------------------
  28
  29   tclVisi provides a tcl command called "Dg" that a visi may call to
  30 get performance information.  "Dg" has several sub-commands, each of
  31 which returns different information to the visi.  This section
  32 describes the commands in detail.  Arguments in angle brackets <>
  33 denote input parameters.
  34
  35   Dg nummetrics -- this command returns the number of currently defined
  36                    metrics.  Metric identifiers (mids) are integers between
  37                    0 and [expr [Dg nummetrics]-1]
  38
  39   Dg metricname <mid> -- returns the name of metric <mid>
  40                      An example metric name might be "procedure_calls"
  41
  42   Dg metricunits <mid> -- returns the units of metric <mid>.
  43                       An example metric unit might be "calls/sec"
  44
  45   Dg numresources -- this command returns the number of currently defined
  46                   resources.  Resource identifiers (rids) are integers
  47                   between 0 and [expr [Dg numresources]-1]
  48
  49   Dg resourcename <rid> -- returns the name of resource <rid>
  50        Resource names are given in the full paradyn naming style.  The
  51        resource name is defined as exactly one representative from each
  52        resource hierarchy.  For example, if the resource hierarchies are
  53        defined to be Machine, Process, and Procedure, then the root (or
  54        top-level) resource is named <Machine,Process,Procedure>.  The
  55        resource indicating procedure "main" on machine "beaufort" would be
  56        named <Machine/beaufort,Process,Procedure/main>
  57
  58   Dg valid <mid> <rid> -- test if a time histogram is valid
  59        returns 1 if a time histogram exists for metric <mid> and
  60        resource <rid>.  returns 0 otherwise
  61
  62   Dg value <mid> <rid> <bucket> -- returns a value from a time histogram
  63        This command returns the value in bucket <buck> of the time histogram
  64        of metric <mid> measured for resource <rid>.  Every valid
  65        <mid>,<rid> corresponds to a different time histogram, and every
  66        time histogram consists of an array of buckets numbered 0 to [Dg
  67        numbuckets <mid> <rid>].  Each bucket in a time histogram corresponds
  68        to a period in time of [Dg binwidth] seconds.  The value in the
  69        bucket is the measured value of the performance metric during the time
  70        period to which the bucket corresponds.  Therefore, if [Dg binwidth]
  71        returns .5 then [Dg value 0 1 20] will return the measured value of
  72        metric 0 for resource 1 for the time period between 10 seconds and
  73        10.5 seconds after the start of execution.
  74
  75   Dg sum <mid> <rid> -- returns sum of a time histogram
  76        This command returns the sum of all buckets of the time
  77        histogram of metric <mid> measured for resource <rid>.
  78
  79   Dg aggregate <mid> <rid> -- average value of a time histogram
  80        This command averages all bucket values in the time histogram
  81        of metric <mid> measured for resource <fid>.
  82
  83   Dg numbins -- number of buckets in time histograms
  84        returns the total number of buckets in time histograms.  Every
  85        time histogram has the same number of buckets.
  86
  87   Dg lastbucket -- last bucket filled in time histograms
  88        returns the index of the last bucket filled in the time histograms.
  89        Every time histogram is filled at the same rate, so the return
  90        value from this command gives the last bucket filled for all
  91        of the time histograms.
  92
  93   Dg start <metricname> <resourcename> -- start a new histogram.
  94      this command asks paradyn starts a new histogram of data
  95      corresponding to metric <metricname> and resource <resourcename>.
  96      Currently, <metricname> and <resourcename> are ignored, so make
  97      the call like this:
  98
  99             Dg start "*" "*"
 100
 101      Paradyn will ask the user to chooe a metric and a focus, and then
 102      will notify the visi with a call to DgConfigCallback after the user
 103      chooses.
 104
 105   Dg stop <mid> <rid> -- stop a histogram.
 106      this command asks paradyn to stop sending data for the histogram
 107      corresponding to <mid> and <rid>.  After paradyn stops the data,
 108      it will notify the visi with a call to DgConfigCallback.
 109
 110 Dg callback commands
 111 --------------------
 112
 113   The Dg callbacks are commands that must be implemented by a visi if
 114 the visi wants to be notified of important events.  Here, we explain
 115 when the commands will be called and what information is passed.  The
 116 behavior of the callback command is left completely to the visi
 117 writer.
 118
 119 DgConfigCallback -- configurations have changed
 120   "Configuration" include the number of resources, the number of
 121   metrics, the names of metrics, and the names of resources.  This
 122   callback is called if and only if any of these values change.  The visi
 123   must call the Dg service routines if it wants to find out exactly
 124   what changed.
 125
 126 DgDataCallback <first> <last> -- new data is available
 127   This command is executed whenever new data is available.  <first>
 128   indicates the first bucket containing new data and <last> indicates
 129   the last bucket that contains new data.  These new data values are
 130   available in all valid time histograms.  The visi must call Dg service
 131   routines if it wants to find the values of the new data.
 132
 133 DgValidCallback <mid> <rid> -- new time histogram is now valid
 134   This command is executed when the time histogram for metric <mid>
 135   measured for the resource <rid> is valid.
 136
 137 DgFoldCallback -- time base has changed
 138   When the last buckets of the time histograms have been filled, the time
 139   histograms are folded so that the bucket widths are doubled and
 140   only the first half of the histogram is used and the second half can be
 141   filled again.  When this happens, the DgFoldCallback command is called
 142   to notify the visi.  When this command is executed the visi must
 143   assume that all bucket values in all time histograms havee changed,
 144   the global bucket width has changed, and the global lastbucket value
 145   has changed.
 146
 147
 148