visi/test/README

   1 directions to incorporate a visualization  (an example is in xtext.C)
   2 -----------------------------------------
   3 in main():
   4 ---------
   5 (1) call visiInit()
   6
   7 (2) register callback routines associated with certain Paradyn events
   8     by calling RegistrationCallback():  these are routines written by the
   9     visualization writer to be called by the visi_callback routine when
  10     the specified event occurs.
  11     the event types (type msgTag) are defined in ../src/error.h
  12
  13     Callback routines should take one integer parameter.  This parameter
  14     is only used for the DATAVALUES event, where it is the bucket number
  15     of the next full set of data across all the valid metrics/resources
  16     of the datagrid.
  17
  18     Most of the work involved in integrating the visualization has to
  19     do with writing these callback routines.  In most cases this will
  20     involve changing a callback routine in the X application that initially
  21     read data from a file descriptor, to get data from the interface's
  22     data structures:  in most cases this involves invoking dataGrid method
  23     functions.  An example of a change to an existing call back routine
  24     is the function "fd_input" in xtext.C.
  25
  26     dataGrid method functions are defined in ~paradyn/core/visi/src/datagrid.h
  27     visualization interface routines and global variables are in
  28       ~paradyn/core/visi/src/visualization.[Ch]
  29
  30 (3) optional: call StartVisi(argc,argv) with the args to main():  each
  31     visualization is started with two command line arguments--a metric
  32     list and a resource list.  For visualizations that do not invoke
  33     the upcalls provided by the visi interface this is the only opportunity
  34     to start data collection.
  35
  36   Steps 3a and 3b: for handling upcalls to Paradyn side:
  37   ------------------------------------------------------
  38 (3a) create a widget associated with the upcall
  39 (3b) use XtAddCallback to register your handler routine for events assoc.
  40      with this widget
  41
  42 (4) register the paradyn file descriptor (returned by VisiInit) and
  43     the paradyn callback routine "visi_callback" with the appropriate
  44     add application routine.  (ie. for Xt use XtAddApp)
  45
  46 (5) call Xt main loop
  47
  48
  49
  50 interface test programs
  51 -----------------------
  52
  53 client2
  54 -------
  55     client2: is a pseudo visi-thread program
  56     client2 is an interactive test which generates its own input values:
  57       data values are generated a bucket at a time across all
  58       metrics/resources: this means that the DATAVALUES callback routine
  59       will be called for each set of data values sent to the server
  60
  61     to run client2 (with default parameters or with user supplied params):
  62     ---------------
  63        client2 server_executable
  64        client2 server_executable numMetrics numResources numBuckets bucketWidth
  65
  66 client1
  67 -------
  68     client1: is a pseudo visi-thread program
  69     client1 is an interactive test that requires user to add input values
  70     sample input for each option is in file "sample.input.client"
  71     (entering the datavalues input choices in the same order that they
  72     appear in the input file will test the triggering of the DATAVALUES
  73     callback routine)
  74
  75     it has one command line argument which is a visualization to fork
  76     the client forks a server process
  77
  78     to run client1 with xtext2:   client1 xtext2
  79     to run client1 with xtext:    client1 xtext
  80     to run client1 with server1:  client1 server1 m r
  81
  82     server and client both print output to stderr
  83     server's output is prefaced by @@@@
  84     upcall output from server to client is preface by ##
  85
  86     a typical session starts with choosing "add m/r" option, followed
  87     by the "data values" option to add send some initial data values
  88
  89     at this point the upcalls are not completely implemented--the call
  90     is made, and a msg that it is made is printed to stderr, but no
  91     action is invoked on the client side
  92
  93     also, options 4, 5 are not fully implemented and option 3 is only
  94     implemented for the initial metric and resource case--adding additional
  95     metrics and resources to an existing data grid is not supported
  96
  97     option 6 is only useful for the server1 test program as a way to get
  98     the server process to print datagrid values to stderr (for test programs
  99     xtext and xtext2 datagrid values are printed to window as a result
 100     of choosing fold and data values options)
 101
 102 xtext
 103 -----
 104     xtext includes examples of adding  callbacks to the Paradyn handler for
 105     certain Paradyn events (DATAVALUES,FOLD,ADDMETRICSRESROURCES).  Also,
 106     it includes an example of adding an upcall to Paradyn by creating a widget
 107     which will invoke an upcall to Paradyn (ex. GetMetricsResources)
 108
 109     code that was added to the original xtext application to add it to Paradyn
 110     is surrounded by "///////////////////////////////" in xtext.C
 111
 112 xtext2
 113 ------
 114     is an extention to xtext that includes callbacks for all Paradyn events
 115     and upcalls.
 116
 117 server1
 118 -------
 119     is a psuedo x application the tests all calls and upcalls in the
 120     visualization--Paradyn interface