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     Most of the work involved in integrating the visualization has to
  14     do with writing these callback routines.  In most cases this will
  15     involve changing a callback routine in the X application that initially
  16     read data from a file descriptor, to get data from the interface's
  17     data structures:  in most cases this involves invoking dataGrid method
  18     functions.  An example of a change to an existing call back routine
  19     is the function "fd_input" in xtext.C.
  20
  21     dataGrid method functions are defined in ~paradyn/core/visi/src/datagrid.h
  22     visualization interface routines and global variables are in
  23       ~paradyn/core/visi/src/visualization.[Ch]
  24
  25 (3) optional: call StartVisi(argc,argv) with the args to main():  each
  26     visualization is started with two command line arguments--a metric
  27     list and a resource list.  For visualizations that do not invoke
  28     the upcalls provided by the visi interface this is the only opportunity
  29     to start data collection.
  30
  31   Steps 3a and 3b: for handling upcalls to Paradyn side:
  32   ------------------------------------------------------
  33 (3a) create a widget associated with the upcall
  34 (3b) use XtAddCallback to register your handler routine for events assoc.
  35      with this widget
  36
  37 (4) register the paradyn file descriptor (returned by VisiInit) and
  38     the paradyn callback routine "visi_callback" with the appropriate
  39     add application routine.  (ie. for Xt use XtAddApp)
  40
  41 (5) call Xt main loop
  42
  43
  44
  45 interface test programs
  46 -----------------------
  47
  48     client1: is a pseudo visi-thread program
  49     it has one command line argument which is a visualization to fork
  50     the client forks a server process
  51
  52     to run client1 with xtext2:   client1 xtext2
  53     to run client1 with xtext:    client1 xtext
  54     to run client1 with server1:  client1 server1 m r
  55
  56     client1 is an interactive test
  57     sample input for each option is in file "sample.input.client"
  58
  59     server and client both print output to stderr
  60     server's output is prefaced by @@@@
  61     upcall output from server to client is preface by ##
  62
  63     a typical session starts with choosing "add m/r" option, followed
  64     by the "data values" option to add send some initial data values
  65
  66     at this point the upcalls are not completely implemented--the call
  67     is made, and a msg that it is made is printed to stderr, but no
  68     action is invoked on the client side
  69
  70     also, options 4, 5 are not fully implemented and option 3 is only
  71     implemented for the initial metric and resource case--adding additional
  72     metrics and resources to an existing data grid is not supported
  73
  74     option 6 is only useful for the server1 test program as a way to get
  75     the server process to print datagrid values to stderr (for test programs
  76     xtext and xtext2 datagrid values are printed to window as a result
  77     of choosing fold and data values options)
  78
  79 xtext
  80 -----
  81     xtext includes examples of adding  callbacks to the Paradyn handler for
  82     certain Paradyn events (DATAVALUES,FOLD,ADDMETRICSRESROURCES).  Also,
  83     it includes an example of adding an upcall to Paradyn by creating a widget
  84     which will invoke an upcall to Paradyn (ex. GetMetricsResources)
  85
  86     code that was added to the original xtext application to add it to Paradyn
  87     is surrounded by "///////////////////////////////" in xtext.C
  88
  89 xtext2
  90 ------
  91     is an extention to xtext that includes callbacks for all Paradyn events
  92     and upcalls.
  93
  94 server1
  95 -------
  96     is a psuedo x application the tests all calls and upcalls in the
  97     visualization--Paradyn interface