2.2 Creating Experiments

The Thread Analyzer follows the same "collect-analyze" model that the Sun Studio Performance Analyzer uses. There are three steps involved in using the Thread Analyzer:

• 2.2.1 Instrument the Source Code

• 2.2.2 Create a Data-Race Detection Experiment

• 2.2.3 Examine the Data-Race Detection Experiment

2.2.1 Instrument the Source Code

In order to enable data-race detection in a program, the source files must first be compiled with a special compiler option. This special option for the C, C++, and Fortran languages is: -xinstrument=datarace

Add the -xinstrument=datarace compiler option to the existing set of options you use to compile your program. You can apply the option to only the source files that you suspect to have data-races.

Be sure to specify -g when you compile your program. Do not specify a high level of optimization when compiling your program for race detection. Compile an OpenMP program with -xopenmp=noopt. The information reported, such as line numbers and callstacks, may be incorrect when a high optimization level is used.

The following are example commands for instrumenting the source code:

• cc -xinstrument=datarace -g -mt pthr_prime.c

• cc -xinstrument=datarace -g -xopenmp=noopt omp_prime.c

2.2.2 Create a Data-Race Detection Experiment

Use the collect command with the -r onflag to run the program and create a data-race-detection experiment during the execution of the process. For OpenMP programs, make sure that the number of threads used is larger than one. The following is an example command that creates a data-race experiment:

• collect -r race./a.out

To increase the likelihood of detecting data-races, it is recommended that you create several data-race-detection experiments using collect with the -r race flag. Use a different number of threads and different input data in the different experiments.

2.2.3 Examine the Data-Race Detection Experiment

You can examine a data-race-detection experiment with the Thread Analyzer, the Performance Analyzer, or the er_print utility. Both the Thread Analyzer and the Performance Analyzer present a GUI interface; the former presents a simplified set of default tabs, but is otherwise identical to the Performance Analyzer.

The Thread Analyzer GUI has a menu bar, a tool bar, and a split pane that contains tabs for the various displays. On the left-hand pane, the following three tabs are shown by default:

• The Races tab shows a list of data-races detected in the program. This tab is selected by default.

• The Dual Source tab shows the two source locations corresponding to the two accesses of a selected data-race. The source line where a data-race access occurred is highlighted.

• The Experiments tab shows the load objects in the experiment, and lists error and warning messages.

On the right-hand pane of the Thread Analyzer display, the following two tabs are shown:

• The Summary tab shows summary information about a data-race access selected from the Races tab.

• The Race Details tab shows detailed information about a data-race trace selected from the Races tab.

The er_print utility, on the other hand, presents a command-line interface. The following subcommands are useful for examining races with the er_print utility:

• -races: This reports any data races revealed in the experiment.

• -rdetail race_id: This displays detailed information about the data-race with the specified race_id. If the specified race_id is "all", then detailed information about all data-races will be displayed.

• -header: This displays descriptive information about the experiment, and reports any errors or warnings.

Refer to the collect.1, tha.1, analyzer.1, and er_print.1 man pages for more information.