Sun Studio Express - Thread Analyzer README

Contents

About the Thread Analyzer
Platforms
How to Download
Features
Thread Analyzer Documentation
Limitations and Incompatibilities
Questions and Feedback

About the Thread Analyzer

This is a preliminary release of the Thread Analyzer. The Thread Analyzer is a tool that analyzes the execution of a multi-threaded program and checks for a variety of multi-threaded programming errors such as data races.

The tool can detect errors in code that is written using the POSIX thread API, the Solaris Operating System(R) thread API, OpenMP API, Sun parallel directives, Cray(R) parallel directives, or a mix of these.

A data-race occurs under the following conditions:

• Two or more threads in a process concurrently access the same memory location,
• At least one of the threads is accessing the memory location 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. 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.

See the Getting Started Guide for instructions on to use the Thread Analyzer.

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.

Platforms

The Thread Analyzer supports the following hardware and operating systems:

• The SPARC(R) v8plus, v8plusa, v8plusb, v9, v9a, and v9b architectures
• The Intel(R) x86 and AMD(R) x64 platforms
• The Solaris 9, Solaris 10, and Linux operating systems
• The SuSE Linux Enterprise Server 9 and Red Hat Enterprise Linux 4 operating systems

How to Download

The Thread Analyzer is part of the Sun Studio software. To download and install the Sun Studio Express build which includes the Thread Analyzer, follow the instructions on the Sun Studio Express page.

Features

This release of the Thread Analyzer includes the following features:

• The new C, C++, and Fortran compiler option -xinstrument=datarace which instruments the source code during compilation. See tha(1) for more information.
• User APIs to notify the Thread Analyzer of user-implemented custom synchronization schemes.
• Command line and GUI tools interfaces to create an experiment and examine the results.

Documentation

This preliminary release is supported by the following documentation:

• An FAQ answers a number of immediate questions.
• The Getting Started Guide offers a quick introduction to the tool.
• The tutorial on Using the Thread Analyzer gives a working example of how to use the Thread Analyzer.
• The following man pages are also available:
  • analyzer.1 - analyze experiment results
  • collect.1 - collect experiment data
  • collector.1 - dbx subcommands 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 a Thread Analyzer experiment
• You can access online help for the new Races, Dual Source, and Race Details tabs from the Help menu in the Sun Studio Performance Analyzer or Thread Analyzer GUI.

Limitations and Incompatibilities

The following are known limitations in the Thread Analyzer.

• The Thread Analyzer can only detect data races in code that is instrumented at compile-time. You must recompile you code according to the instructions provided in the Getting Started Guide in order to be instrumented.
• The Thread Analyzer is not able to recognize user-implemented synchronizations. It may report false positive data-races if your code contains such synchronizations. For example, the Thread Analyzer does not recognize hand-coded assembly that implements spin locks as a synchronization point. Use the APIs described in tha.1 to notify the Thread Analyzer of user-implemented synchronizations and thus avoid false positives.
• Running programs under the Thread Analyzer can incur significant overhead depending on the nature of the application.
• Asynchronous signal handling is not fully supported. Programs that use asynchronous signals may stall under the Thread Analyzer.

Known bugs in the Sun Studio Express December build:

• 6430080: Thread Analyzer may report the same data race multiple times on the Linux operating system.
• 6396659: The Thread Analyzer may miss potential data races between OpenMP threads from different inner parallel regions in nested parallel regions.
• 6496290: The Thread Analyzer may report erroneous data races on omp-overhead for OpenMP applications using nested parallel regions on Linux.

Questions and Feedback

Sign on to the Sun Studio Tools Forum to post questions to Sun engineering and the community. You might find that your problem has already been solved. Be sure to state that you're using a Sun Studio Express build.

(Page last modified December 8, 2006)