Contents
What is the Thread Analyzer?
How to Use the Thread Analyzer
Documentation
The Thread Analyzer detects multi-threaded programming errors that occur
during the execution of a multi-threaded process such as data races.
A data-race occurs when:
- two or more threads in a single process access the same
memory location concurrently, and
- at least one of the accesses is for writing, and
- the threads are not using any exclusive locks to control their
accesses to that memory
When these three conditions hold, the order of accesses is
non-deterministic. Therefore each run can give different results
depending on the order of the accesses. Of course, some data-races may
be benign (for example, when the memory access is used for a busy-wait),
but many data-races are either bugs or caused by bugs in the program.
The Thread Analyzer works on a multi-threaded program which is written
with the POSIX thread API, Solaris thread API, OpenMP API, Sun parallel
directives, Cray parallel directives, or a mix of the above.
Please note that the Thread Analyzer is still in the
development stage. The user model -- including instrumentation
requirements, command names, command options, output formats, and GUI
interface -- may change later in the product-release cycle. Since the
tool is based on a development build, the compilers and tools may
contain bugs, and certain features may not work as described.
The Thread Analyzer follows the same collect-and-analyze model
that the Sun Studio
Performance Analyzer uses.
The collect-and-analyze model follows these steps:
- Instrument the source code
- Create an experiment
- Examine the experiment
In order to enable thread analysis in a program, 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.
It is recommended that you use no optimization level 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.
Example compilation commands:
cc -xinstrument=datarace t.c -mt source.c
cc -xinstrument=datarace t.c -xopenmp=noopt source.c
CC -xinstrument=datarace t.cc -mt source.cc
CC -xinstrument=datarace t.cc -xopenmp=noopt source.cc
f90 -xinstrument=datarace t.f90 -mt source.f90
f90 -xinstrument=datarace t.f90 -xopenmp=noopt source.f90
Use the collect command with the -r on flag to run
the program and create an experiment during the execution of the process.
Example:
collect -r on ./a.out
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.
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.
header
Display descriptive information about the experiment, and report any
errors or warnings.
Example Thread Analyzer, Performance Analyzer, and er_print commands to
examine an experiment:
tha test.1.er
analyzer test.1.er
er_print test.1.er
(Page last modified November 28, 2006)
|
|
Print-friendly Version
