Observing functions using hat-observe
ART Memo 17, Version 0
Thorsten Brehm, April 4th, 2001


INTRODUCTION

With the program hat-observe it is now possible to observe all
applications of a given (top-level) function directly from the
trace file. No modifications have to be done to the source code,
no extra classes have to be introduced etc. All the tool needs
is the recorded trace file of the program. Unlike Hood,
observations are "introduced" after running the program. There
is no need for a rerun, to observe a different function.


EXAMPLE OF USAGE:

- Compile your program with "hmake -T".
- Run your program.
- use hat-observe to make observations from the recorded trace file.
  e.g.
       hat-observe fibs fibofile
  will observe ALL applications of fibs in the trace file fibofile.hat

- The program accepts the optional setting "-u" (hat-observe -u ...).
  Using the "-u" option (unique) the program will only show unique
  applications. Furthermore, only the most general application is shown.
  An application is considered more general, if atleast one of its
  arguments is less defined than the corresponding argument of the
  second application. Complex datastructures, built by constructors
  are handled correctly, e.g. the argument "TreeNode (TreeNode _) _"
  is more general than "TreeNode (TreeNode NIL) (TreeNode _)".
  Using this option can sometimes reduce the output amount enormously.
  As a drawback, you will have to wait for the output of hat-observe
  until the whole trace file was scanned, whereas it continuosly
  prints any applications found, if you can do without the option. 
  
- The second optional argument is "-v" for the verbose mode.
  (hat-observe -v ... ).
  Normally, unevaluated arguments are not shown by the tool, instead
  the "_" symbol is printed. Using the "-v" option will show all
  unevaluated expressions in full - that is: all remaining function
  applications within the arguments of the application. Mixing the
  "-v" with the "-u" option is possible, but will often result in a
  much higher number of applications found compared to "-u" only.


KNOWN PROBLEMS AND BUGS:

1 There is a major problem with partial applications. Undersaturated
  applications will result in observations where the function
  application is missing arguements. The correct result for
  the application - including the unshown arguments - may sometimes
  be still given => ugly problem...
  Even worse, in some cases an observed function, which was called
  by an partial application may even show a completely wrong
  result. The reason for this is a missing SATC for one of the
  applications parents in the trace file - which should be there -
  but isn't.

2 A performance problem may occur with the "unique" option, when the
  observed function is excessively often applied. The unique
  option will sort and filter the found applications with a
  complexity which is squared to the number of applications found. 
 
3 Printing expressions with infix operators should be syntactically
  correct but does not represent the simplest representation of the
  expression. The pretty printing algorithm does not (yet) make use
  of the associativity information of an infix operator.

4 hat-observe finds all applications of an identifier  - not only
  the toplevel identifier.

SOLUTIONS:

1 Make trace file correct.

2 A more efficient way of filtering a huge number of applications
  is to be found. As the expressions are not totally ordered,
  this problem is not trivial.

3 Invest more time in pretty printing algorithm and make it
  smarter.

4 information about the exact location of an identifier in the
  source code might be passed to the tool


REMARKS:

1 CAFs can now too be observed with this tool. hat-observe searches
  for SATCs, which are directly behind a TRNAM entry which references
  the given identifier. An application node for CAFs does of course
  not exist.

2 Functions defined as lambda functions are NOT a problem. As long as
  all necessary arguments are applied at the same time, the correct
  output is produced. The nature of the lambda expression itself
  is not visible in the output.

3 There is a difference between the observe by Hood and the observe
  by hat, concerning "unevaluated" expressions. Unlike Hood, the
  hat-observe tool cannot really distinguish between arguments, which
  where really needed for the application and arguments, which were
  not evaluated. In hat a (sub-)expression does only show to be
  "unevaluated", if it is still an application of a function. If an
  argument merely consits of constructors (or number values), these
  arguments are shown in full. It cannot be determined from the hat
  file, whether these arguments were really needed by the application
  itself. Hence, a "_" is only printed for remaining application
  nodes in an expression.