XAB-POST version 0.1 README
===========================

Purpose:
--------
Often when viewing an XAB trace, you will see "tachyons", violations of
causality.  For example, a message may be received before it has been
sent, or a process may enroll before it has been initiated, due to the
clocks being out of synch or the events arriving out of order.  This can
be kind of disconcerting when debugging a parallel program.

xab-post is a postprocessor for XAB traces that will eliminate tachyons by
correcting the timestamps.  Basically, it constructs the causality dag for
a program, then traverses the dag in a topological order, setting the time
at each node to be the maximum of the times of its predecessors (similar
to Lamport's logical timestamps.)  The result should be a tachyon-free trace
of your program, with most of the times a somewhat decent approximation of the
"real" time at which that event occurred.

The output of xab-post can be used by xab or topg just like a normal xab 
trace.



Compiling XAB-POST:
-------------------

A simple "make" should work.  The result should be an executable: xab-post.



Using XAB-POST:
---------------

To postprocess a trace file source.xab and put the result in dest.xab,
any of the following will work:

xab-post source.xab dest.xab
xab-post source.xab >dest.xab
xab-post <source.xab >dest.xab


Known limitations of current version:
-------------------------------

Right now, the only event types examined for tachyon-correction purposes
are snd, rcv, vsnd, vrcv, initiate, and enroll.

The io routines (see xab-post-io.c) only accept a limited number of event
types.  It is pretty easy to modify them to tolerate other events in your
file, though-- xab-post-io.c should be the only file you need to touch.  

The .c files contain a number of "hard" upper limits (see the #defines at
the top of each one); you may want to reduce or increase these, depending
or your memory limitations or tracefile properties.

While the output of xab-post is in standard xab format modulo some
whitespace, the output is not exactly the same as that produced by abmon.
This shouldn't hurt your ability to view the trace with xab or ParaGraph,
though.  


Bugs/Comments:
--------------

If you have any bug reports, requests, suggestions, flames, etc. relating
to xab-post, please send them to 

	Erik.Seligman@cs.cmu.edu

Also, if you find it useful, I'd like to hear about that as well;
perhaps an expanded version will appear with the next release of xab...

Good luck!   



 





