Sofya User Manual: Event Dispatch: Structural

Using the structural event dispatch framework

Running the Instrumentor

Getting Started

Notice: The sofya tools currently have a bug that requires the use of the [-tag tag] option when using the instrumentation and execution tracing tools described here.

To run the instrumentor to instrument a class for structural event dispatch, use the following command:

The tag parameter can be used to specify a database tag associated with the control flow and map files required by the instrumentor (see information on the CFG builder). If you did not specify a tag to the CFG builder when constructing the control flow graphs for the classes you intend to instrument, you do not need to use this parameter.

The first required parameter specifies either basic block instrumentation or branch instrumentation. To instrument basic blocks, any combination of the characters E, X, C, and B can be specified, where E specifies virtual entry blocks, X specifies virtual exit blocks, C specifies call blocks, and B specifies all other basic blocks. Entry and exit blocks do not correspond to actual code, but rather provide information about entry to and exit from methods. Branch instrumentation is not parameterized, though branch types can be filtered at runtime (this is discussed under running the event dispatcher).

When specifying a single class for instrumentation, the rules regarding inclusion of the .class extension are the same as for the CFG builder. However, the instrumentor exhibits additional behaviors with respect to the format of the class name. If an absolute path is given, the instrumentation will be directly applied to the given classfile, at the classfile's current location. If the class is loaded from the classpath, the resulting instrumented classfile will be placed in the working directory from which the instrumentor is run.

The instrumentor also accepts jar files and program list files to specify the classes to be instrumented. Program list files are automatically found in the database, using the tag if one is specified. Any necessary path information should be provided when passing a jar file as an argument. When a jar file is passed as an argument on the command line, every class in the jar is instrumented. The preferred way to include classes in a jar file is to include the jar file in a program list file and supply the program list file as an argument instead, as a program list file permits you to exclude classes in the jar from processing. Any number of specific classes, jar files, and program list files can be passed to the instrumentor, though supplying a single program list file is the expected typical use.

It should be noted that if you change the type of instrumentation, you should also remove the bootstrap.jar file that is created during the trace generation phase by the event dispatcher framework. See the notes within the StructuralInstrumentor for additional details.

Advanced Instrumentation

Running the instrumentor as described in Getting Started instruments class files for observation of basic block coverage events. The full usage for the instrumentor is the following:

The -t parameter is used to change the inserted instrumentation to target different mechanisms for observing events. Currently, the following values for this parameter are available:

norm: The default, this instrumentation supports dispatch of coverage event streams. Sequence event streams cannot be dispatched using this instrumentation.
seq: This instrumentation enables dispatch of sequence event streams. Coverage event streams can also be collected, but less efficiently.
junit: This instrumentation enables dispatch of event streams through the JUnit framework during execution of a JUnit test suite. Event streams can be dispatched from classes containing this instrumentation only by using the junit.textui.SelectiveTestRunner; regular event dispatchers will not operate on this instrumentation. This value is actually a modifier that can be combined with norm or seq to allow dispatch of either of those respective types of event streams from the execution of a JUnit test suite. When used alone, junit is equivalent to norm,junit, enabling dispatch of coverage event streams from JUnit tests.

If the event dispatcher reports an error about being unable to bind to a socket, the -port parameter can be used to change the socket used by the instrumentation. If you specify a custom port during instrumentation, you must specify the same port to the event dispatcher when you run the instrumented class.

The -so parameter is used to instruct the instrumentor to only insert into a class the instrumentation necessary to establish the connection between a subject and the event dispatcher. If you want to instrument certain classes, but not the class that is the entry point for the application, you will want to use this option on the class that is the entry point (the class containing the main method). This is most often useful for test driver classes that execute instrumented classes, but that are themselves not of interest for instrumentation or event dispatch.

Running the Event Dispatcher

The principle class for dispatching structural event streams is the ProgramEventDispatcher. This class is not directly executable, however the "tracer" classes in the ed package of Σοφία are classes that generate trace files using the ProgramEventDispatcher. For structural tracing, these consist of BBTracer (basic block coverage traces), BBSequenceTracer (basic block sequence traces), BranchTracer (branch coverage traces), and BranchSequenceTracer (branch sequence traces). These classes serve as example implementations using the structural event dispatcher, and, with the assistance of the TraceHandler, can be used without modification to create trace-based analyses.

Getting Started

To use BBTracer to collect a basic block coverage trace of the execution of an instrumented program, make sure the main class of the program can be found on your Java classpath. Then run the following command:

java sofya.ed.BBTracer -<E|X|C|B> <classname> <arguments>

The first parameter functions the same way as described for the instrumentor, where any combination of the given values can be specified. Only blocks of the selected types will be included in the generated trace file, where E specifies virtual entry blocks, X specifies virtual exit blocks, C specifies call blocks, and B specifies all other basic blocks. For performance reasons, the typical usage is to trace all of the block types for which instrumentation was inserted. However, this filtering capability provides the opportunity to instrument a program for multiple types of blocks and then select only the block types of interest to a particular analysis when collecting traces. Note that if a block type is requested that was not specified during instrumentation, information about those blocks will not appear in the generated trace.

The classname argument should be the fully qualified name of the main class for the program, and should not include the .class extension.

By default, the tracer will create a file named "instout.tr" in the database directory which contains the trace information. Each time the tracer is run it will overwrite this file, unless otherwise specified (see below), so it is the responsibility of the user to store the file somewhere permanent, if desired. The trace file can be viewed using the TraceViewer.

The basic usage for the other tracers is essentially the same. In the case of the branch tracers, the branch types that can be selected are as follows:

I: Branches originating at "if" instructions.
S: Branches originating at "switch" instructions.
T: Branches representing control flow possibilities out of "throws" instructions, if any.
C: Branches representing control flow possibilities out of call instructions (caused by exceptional control flow), if any.
E: The "entry" branch into a method. Not really a branch, but useful to some analyses.
O: Branches representing control flow possibilities caused by any other exceptional control flow that cannot be statically determined (e.g. exit from a method caused by undeclared and unhandled unchecked exceptions).

As with the basic block tracers, these options can be combined in any way.

Advanced Tracing

There are additional options available for controlling the behavior of the various tracers. The BBTracer and BBSequenceTracer classes will be used to describe these options. The same options apply to the BranchTracer and BranchSequenceTracer.

BBTracer and BranchTracer

The full usage for BBTracer is the following:

java sofya.ed.BBTracer [-port n] [-cp path]
 [-i] [-tl num_secs] [-at] [-o output_file] [-trname trace_name]
 -<E|X|C|B> <classfileName> <arguments>

-port n

Instructs the tracer to listen for the instrumentation connection on port number n.

-cp path

Causes the tracer to set the CLASSPATH for the subject program to path.

-i

Enables piping of stdin to the subject program. Programs requiring user input will deadlock if this option is not enabled.

-tl num_secs

Instructs the tracer to kill the subject after num_secs if it has not yet terminated. This option should be used instead of sending a kill signal to the tracer, as it enables the tracer to perform cleanup and generate the trace file for the subject program up to the point it was terminated.

-at

Causes the tracer to append the current trace to the existing trace file of the same name, if it already exists.

-trname trace_name

Instructs the tracer to name the trace file trace_name. The .tr extension should be omitted.

-o output_file

Causes the tracer to redirect the subject program's output to output_file. Both stdout and stderr are redirected to the specified file.

-<B|E|X|C>

Specifies the block types to be included in the generated trace. All permutations are allowed.

An explaination of branch tracing report output resulting from using sofya.ed.BranchTracer can be found in the Branch Tracing Interpretation section of the manual.

BBSequenceTracer and BranchSequenceTracer

The sequence tracers are used to collect traces recording the full sequence of program entities executed during a program run, in the order observed. A program must be instrumented for sequence tracing to use this tracer; a program instrumented for coverage tracing will not work. This tracer produces a trace file in the database directory named "instout.seq" that is readable without the use of a viewer. These tracers provide the following additional options:

-pre data

Causes the tracer to insert data at the start of the trace file, before any trace data.

-post data

Causes the tracer to append data at the end of the trace file, after any trace data.

-relay

Instructs the tracer to transmit the trace (including any -pre or -post data) through a socket to the port used by a DAG builder to perform dynamic impact analysis.

Note that by default the BBSequenceTracer writes entry and exit block events to the trace file in a format specifically designed for use in a particular type of DAG construction for impact analysis. New filters can be written to generate trace files in other formats. Finally, be aware that the trace files generated by this tracer can be extremely large.