projected changes to CFG classes

[John Jorgensen <jorgnsn@lcd.uregina.ca>]

The next release of Soot (and, no, I have no idea when it will
occur) is slated to include extensive changes to the
implementation of Soot's CFG classes.  I'd like to outline the
changes here, to provide fair warning to Soot users who have not
checked out the development version of Soot (available at
http://svn.sable.mcgill.ca), and to solicit your warnings about
flaws in the plan.

(I've worded the description so that it can be incorporated into
future release notes, so it includes references to documentation
that will not be available to you without downloading files from
the Soot repository.)


The CFG classes in soot.toolkits.graph have been reorganized to
provide facilities for pruning exceptional control flow.  In
particular:

BlockGraph is now an abstract class. Code which has instantiated
BlockGraph directly should replace invocations of the BlockGraph
constructor as follows:

 BlockGraph(body, BlockGraph.BRIEF) => BriefBlockGraph(body)
 BlockGraph(body, BlockGraph.ZONED) => ZonedBlockGraph(body)
 BlockGraph(body, BlockGraph.COMPLETE) => CompleteBlockGraph(body)
 BlockGraph(body, BlockGraph.ARRAYREF) => ArrayRefBlockGraph(body)


UnitGraph is now an abstract class.  Code which currently
instantiates UnitGraph directly should replace invocations of the
UnitGraph constructor as follows:

 UnitGraph(body, false, false) => BriefUnitGraph(body)
 UnitGraph(body, false, true) => BriefUnitGraph(body)
 UnitGraph(body, true, false) => CompleteUnitGraph(body)
 UnitGraph(body, true, true) => TrapUnitGraph(body)


[I particularly want to hear from people who are greatly
inconvenienced by BlockGraph and UnitGraph becoming abstract; I
realized today that there is a straightforward mechanism that
would let us retain the current set of public constructors, but I
would prefer to get rid of them.]


CompleteUnitGraph is included for backwards compatibility; new
code should use ExceptionalUnitGraph instead, since it provides
the option to prune unrealizable exceptional control flow from
the CFG, and its interface allows callers to distinguish
exceptional control flow from regular control flow.  See 
ExceptionalUnitGraph's javadoc for details.

There are two differences between the graphs produced by the old
implementation of CompleteUnitGraph and the one provided in this
release:

  this release will include edges from Units that branch into
  the middle of a protected region to the handler protecting the
  region;

  this release will include an exception handler among
  the heads of the graph when the first Unit in the 
  method may throw an exception caught by the handler.

Both differences are bug fixes, but the latter may surprise
client code that assumes CompleteUnitGraph.getHeads() always
returns a single Unit.


soot.util.dot.DotGraph.plot() now takes the output filename as an
argument, rather than deriving it from the method name.


soot.Main now has command line options that specify how to treat
exceptional control flow (the options change the default values
for parameters to the ExceptionalUnitGraph(Body) constructor).
See the documentation for "--throw-analysis",
"--omitExceptingUnitEdges", "--trim-cfgs", and "--phase-help jb.tt".


soot.Main now has options for dumping CFGs and method bodies at
intermediate points during the soot run. The output is voluminous
and likely of use only to people maintaining Soot's internals.
See the documentation for "--dump-body" and "--dump-cfg".


The command line options for soot.tools.CFGViewer have been
completely reworked, with no provision for backwards
compatibility (to allow for a wider variety of graph types,
intermediate representations, and soot transformations).  See the
output of "soot.util.CFGViewer --help" for details.

The new package soot.toolkits.exceptions provides support for
exceptional control flow analysis.

The new package soot.util.cfgcmd provides support for the
reimplementation of soot.util.CFGViewer and the "--dump-cfg"
option.