Menus

Configuration Files

menu File showing four items: Open, Save, Save as, Exit

The options used to configure a particular session of Ladybug can be saved for future use.

Instrumentation

menu Instrumentation showing three items: On the fly, Rewrite 
now, Options

You can instrument the files as they are loaded (On-the-fly instrumentation, the default) or rewrite an instrumented version before the execution. On-the-fly instrumentation is easier, but it will not work if:

Execution Options

Algorithms

Radio buttons: Dinning-Schonberg, Vanilla Eraser, Fast Eraser,
    GC Eraser; Checkboxes: Ignore class initialization, AWT dispatch
    thread starts when first window appears

There are two algorithms: Dinning-Schonberg and Eraser. The three options for Eraser differ only in their implementation: Vanilla Eraser and Fast Eraser are faster (but more memory consuming) implementations, while GC Eraser is more economical with the memory (but slower).

Eraser refers to the algorithm proposed by Stefan Savage, Michael Burrows, Greg Nelson, Patrick Sobalvarro and Thomas Anderson in Eraser: A Dynamic Data Race Detector for Multithreaded Programs. For each (potentially) shared variable, Eraser checks if there is a monitor that protects all accesses to it (the initialization of variables, however, is not taken into account).

Dinning-Schonberg refers to the algorithm for race condition detection proposed by Anne Dinning and Edith Schonberg in Detecting Access Anomalies in Programs with Critical Sections. This algorithm is more general than Eraser, but slower; it should be used if:

The Dinning-Schonberg algorithm may issue false alarms due to "complex" initialization of static fields (complex, here, means that the static field refers to an object, and a field of this object is written when the class is initialized). If your program is a victim of these alarms, you may want to check the option Ignore class initialization. And you can follow this link to know more about class initialization and how it affects Ladybug.

Finally, unless you interact with the the Event Dispatch Thread before showing any window, the option AWT dispatch thread starts when first window appears should be left on (in most cases you may assume that the Event Dispatch Thread starts only when the first window appears).

When a race condition is detected

Radio buttons: Halt, Throw exception, Display warning; Checkbox: Warn 
about the same variable only once

The program can be halted, a message can be displayed or an exception can be thrown when a race condition is detected. By checking the option Warn about the same variable only once, warnings/exceptions about a field of an object are not issued more than once.

Output

Radio buttons: New window, File, Standard; Checkbox: Verbose; A text 
field to input the file name, a text box to input a filter for 
verbose output

The output of the monitored program can be sent to the standard output (System.out and System.err), a new window or a file. If you choose to send the output to a file, you must set a file name as well.

If verbose is checked, the monitoring algorithm runs in verbose mode, printing messages about what it is doing to the standard error stream. If a filter is specified, messages referring to fields that are not in the filter will not be printed. The filter is a colon-separeted list with field names. For instance:
apple:Tree.banana:@12efcc.watermelon:@a1009b.101 says that messages about accesses to fields must be printed only if they refer to:

Command line

A text box to input the command line

You just need to type the command line to run your program; Ladybug is responsible for changing it as needed. Nevertheless:

Run

a button with a ladybug and the label 'Run'

Start the execution of the instrumented version of your program.

Instrumentation options

Instrumentation Options dialog; it contains an area to insert field 
names, another area to insert class and package names, an area to insert 
names of files to instrument, a button with the text 'Add', a text box to 
input the directory the instrumented files must be written to, a checkbox 
with the text 'Recursively process subdirectories', and a checkbox with 
the text 'Do not forget binary compatibility'

Ignore fields

You can inform name of fields whose access must not be instrumented. Field names may be fully qualified (to avoid ambiguities) but this is not required (e.g.: org.rk.Foo.myField is a fully qualified name).

Ignore classes and packages

Names of classes and packages that must not be instrumented may also be informed. Package names accept a star at the end, which works as a wild card. For instance, a name like com.foo.* causes Ladybug to ignore all classes in package com.foo when instrumenting your application.

Files to instrument

You need to inform the files to instrument, but only if you are not using on-the-fly instrumentation. If you do not specify an output directory to write the instrumented class files, the original class files are overwritten by the instrumented version. Directories found in the list of files to instrument are processed recursively if the checkbox Recursively process subdirectories is selected.

Binary compatibility

This checkbox must be checked if binary compatibility is to be considered when instrumenting the class files. This is important only if, in your application, these three conditions are simultaneously true: