Sun Studio Thread Analyzer - Getting Started Guide

Contents

What is the Thread Analyzer?
How to Use the Thread Analyzer to Detect Deadlocks and Data Races
Documentation

What is the Thread Analyzer?

The Thread Analyzer detects multi-threaded programming errors, such as data races and deadlocks, that occur during the execution of a multi-threaded process.

How to Use the Thread Analyzer

The collect-and-analyze model follows these steps:

1. Instrument the source code for data race detection
2. Create an experiment
3. Examine the experiment

1. Instrument the source code for data race detection

In order to enable data race detection, the source files must first be compiled with a special compiler option. This special option for each of C, C++, and Fortran 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 generate data races.

Example compilation commands:

cc -xinstrument=datarace source.c -mt source.c

cc -xinstrument=datarace source.c -xopenmp=noopt source.c

CC -xinstrument=datarace source.cc -mt source.cc

CC -xinstrument=datarace source.cc -xopenmp=noopt source.cc

f90 -xinstrument=datarace source.f90 -mt source.f90

f90 -xinstrument=datarace source.f90 -xopenmp=noopt source.f90

Note: It is recommended that you use -g and no optimization level when compiling your program for error checking by the thread analyzer. Compile an OpenMP program with -g -xopenmp=noopt, and compile a POSIX threads program with just -g. The information reported, such as line numbers and callstacks, may be incorrect when a high optimization level is used.

2. Create an experiment

Use the collect command with the -r all option to run the program and create a data-race-detection and deadlock-detection experiment during the execution of the process.

Note: collect -r all collects all Thread Analyzer data. If you wish to collect data race data only, use collect -r race. If, on the other hand, you wish to collect (potential and actual) deadlock data only, use collect -r deadlock.

Examples:

collect -r all a.out

collect -r race a.out

collect -r deadlock a.out

collect -r race:deadlock a.out

3. Examine the experiment

An experiment can be examined with the Thread Analyzer (tha), the Performance Analyzer (analyzer), or the er_print utility.

Both tha and analyzer present a GUI interface; the former presents a simplified set of default tabs, but is otherwise identical to the analyzer interface.

The er_print utility, on the other hand, presents a command-line interface. The following er_print subcommands are the most generally useful:

races

Report any data races detected in the experiment.

deadlocks

Report any deadlocks detected in the experiment.

rdetail race_id

Display 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.

ddetail deadlock_id

Display detailed information about the deadlock with the specified deadlock_id. If the specified race_id is all, then detailed information about all deadlock swill be displayed.

header

Display descriptive information about the experiment, and report any errors or warnings.

Example commands to examine an experiment:

tha tha.1.er

analyzer tha.1.er

er_print tha.1.er

Documentation

• Tutorial on using the Thread Analyzer for data race detection

• Tutorial on using the Thread Analyzer for deadlock detection

• Frequently Asked Questions (FAQ)

• And the following man pages:
  • analyzer.1 - analyze experiment results
  • collect.1 - collect experiment data
  • collector.1 - subcommands of dbx used for performance data collection
  • er_print.1 - print a report from one or more experiments
  • libtha.3 - API for the Thread Analyzer
  • tha.1 - analyze multi-threaded program experiments