************************************************************************
*        Busy Wait Analyser - BWA - http://bwa.sourceforge.net/        *
*                                                                      *
*      (C) 2005  Raul Fechete, Georg Kienesberger, Peter Minarik.      *
************************************************************************


   BWA is a static analysis tool for Java programs that targets the
detection of "Busy Wait". It takes ordinary class files as input, uses
the Soot Framework (http://www.sable.mcgill.ca/) to extract control flow
information, and then runs the analysis proposed by "Johann Blieberger,
Bernd Burgstaller, Bernhard Scholz, Busy Wait Analysis, Ada-Europe'2003,
Toulouse, France, 2003".
   So it basically is a command line tool which outputs class name,
method name, the source line number of the busy wait loop and the busy
wait variable (In order to output line number and variable name, it is
required that debug information was generated during compilation.).


Basic Usage
===========

java bwa.Main [-s] [-l LEVEL] \
[[-v|-vv] [-o FILE] | -e FILE [-t VAL]] [-i FILE] \
[-r|-j| --method METHOD CLASS | CLASS1 CLASS2 ...]

	CLASS	  The only thing you really need to provide is the name
		  of the class(es) you want to analyse. Your $CLASSPATH
		  has to be set correctly, and in case you want to
		  specify more than one class you cannot use -r, -j or
		  --method.
	
	--method  Followed by the name of a method and a single class,
		  only this method is analysed. If the methodname within
		  this class is not unique this option cannot be used.

	-r	  Starting from the given class, analyse all reachable
		  methods in the callgraph. So if the main class of a
		  program is given, the whole program should be
		  considered during the analysis. See the usage notes
		  below.
		
	-j	  Basically the same as -r, but packages starting with
		  java.*, sun.*, org.apache.*, org.xml.* are also
		  included in the callgraph. See the usage notes below.
	
	-l 0	  Only the variables with the highest BW probability are
		  being shown. As candidates, only the variables
		  directly used in a termination statement are taken
		  into consideration. This level also corresponds to a
		  "lite scan" - a heuristic process to skip the
		  counter-like nodes.
		  e.g.: In the for(i=1;i<n;i++) loop, it is very
		  probable that n will not change its value, thus making
		  it a BW suspect. Since i does change, the heuristic
		  assumes that this node cannot be the header of a BW
		  loop, and ignores all the variables used by it. Note
		  that in this process some "true" BW Variables may get
		  lost.
 
	-l 1	  Normal scan. Same as Level 0 but without
		  "lite scanning". Nothing is ignored.

	-l 2	  "Deep" scan. Same as Level 1, but if a variable is
		  being written by other variables, it will be removed,
		  and the "writing" ones automatically become
		  candidates. This level, has the highest chance of
		  finding all the BW Variables, but false alarms are
		  very probable to occur.

	-s	  The algorithm uses by default source aware back-path
		  finding - the non writing path for each variable must
		  begin and end with the node containing the termination
		  predicate using this variable. With -s one can turn
		  off the SABF - the paths begin and end with the loop
		  header.
	
	-o FILE	  Redirect the output to the file FILE.

	-e FILE	  Save the BW candidates to FILE for later input with
		  -i. By editing this file you may suppress repeated
		  output of certain BWs. Lines starting with # are
		  ignored. BW suspects (except "Special BW" suspects)
		  start with a line containing the ID
		  (+BW suspect: [SOMEID]) and are followed by some
		  additional information.
		  If there is a + in front of the ID this BW suspect
		  will be reported again. To ignore a BW suspect in
		  future output simply replace that + with a -.

	-t VAL	  Specify the tolerance used to create the IDs for -e.
		  VAL has to be between 1 and 100, 50 is default. With a
		  lower VAL, changes to the source do not have so much
		  effect on the ID of a BW suspect, however, it is more
		  likely that 2 BW suspects get the same ID.

	-i FILE   Use FILE (that had be generated with -e) as Input.

	-v	  Output gets verbose.

	-vv	  Output gets very verbose.


Usage Notes
===========

1) If you run into problems it is generally a good idea to check your
   $CLASSPATH first.

2) The following message which shows up when -r or -j are used is
   written to stderr directly by Soot:

   "[Call Graph] For information on where the call graph may be
   incomplete, use the verbose option to the cg phase."

   If you want to know where the call graph may be incomplete, ignore
   that message and use our -vv option.  

3) If you get an OutOfMemoryError try using the -Xmx switch to Java. (By
   default the Java VM only allocates 64MB.)
   For example (for 400MB): java -Xmx400m ...

4) If a class cannot be found by Soot, you should get the following
   message:

   "java.lang.RuntimeException: couldn't find class: Foo"

   However, sometimes you will get a more cryptic error:

   "java.lang.NoClassDefFoundError: polyglot/ast/ProcedureDecl"

   In that case check your $CLASSPATH first...

5) -r and -j require that the callgraph is built, which seems to be as
   expensive as the transformation/analysis that follows. There is also
   no chance to recover from an exception that soot throws during that
   task. So the callgraph is either built or not. In addition -r builds
   the same, huge callgraph as -j, because skipping packages during that
   process is currently not supported by soot.
   If you experience those problems, consider to pass all the classes
   directly (java bwa.Main CLASS1 CLASS2 CLASS3...) rather than
   specifying the main class along with -r/-j.
   

License & Warranty
==================

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.

You should have received a copy of the GNU General Public License along
with this program (see the LICENSE file or the --license option); if
not, write to the Free Software Foundation, Inc., 59 Temple Place -
Suite 330, Boston, MA  02111-1307, USA.