Man Page tha.1
NAME
tha - GUI for analyzing a Thread Analyzer experiment
SYNOPSIS
tha args
DESCRIPTION
The tha command invokes a GUI for analyzing the various
Thread Analyzer experiments collected by the Collector using
the collect(1) command. The GUI is a version of Analyzer
customized for examining Thread Analyzer experiments.
The Collector gathers Thread Analyzer information to create
a thread-analyzer experiment during the execution of a pro-
cess. The tha command reads in such an experiment and
displays any errors detected. The current Thread Analyzer
supports data-race detection; for further information on it,
see the section "DATA-RACE DETECTION", below.
A command-line version of the tha command is available as
the er_print(1) utility.
To start tha, type the following on the command line:
tha[ thread-analyzer-experiment]
Both the tha command and the analyzer(1) command can be used
to read a thread-analyzer experiment. The tha command has
the same functionality and features as the analyzer command,
but shows a simplified set of default tabs that pertain to
Thread Analyzer experiments.
OPTIONS
Option Meaning
-j|--jdkhome jvmpath
Specify the path to the Java[TM] virtual machine
(JVM) software for running the analyzer. The
default path is taken first by examining environ-
ment variables for a path to the JVM, in the order
JDK_HOME, and then JAVA_PATH. If neither environ-
ment variable is set, the default path is where
the Java[TM] 2 Platform, Standard Edition technol-
ogy was installed with the Sun Studio release, and
if it was not installed, as set in the user's
PATH. (The terms "Java virtual machine" and "JVM"
mean a virtual machine for the Java(TM) platform.)
-J jvm-option
Specify JVM(TM) software options.
-f|--fontsize size
Specify the font size to be used in the analyzer.
-v|--verbose
Print version information and Java runtime argu-
ments before starting.
-V|--version
Print version information and exit.
-?|-h|--help
Print usage information and exit.
THA WINDOW -- LEFT HAND TABS
The tha window has a menu bar, a tool bar, and a split pane
that contains tabs for the various displays.
The left-hand pane contains tabs for the principal displays.
The tabs that are actually present in the pane are con-
trolled by a rtabs directive in a .er.rc file. The Experi-
ments tab is always shown. The Races and Dual Source tabs
will be shown if data-race data is in one or more of the
loaded experiments.
By default, the Races tab is selected, if available. If it
is not available, only the Experiments tab will be visible.
The Races Tab
The Races tab is shown if data-race data is in one or
more of the experiments loaded; it shows a list of
data-races detected in the program. By default, the
first data-race in the list of data-races is selected.
For each data-race, the following information is shown:
(a) A unique id that identifies the data-race.
(b) One or more virtual addresses (Vaddr) associated
with the data-race.
(c) The two accesses by two different threads that con-
stitute the data-race. For each access, the type of
the access (Read or Write) is shown, as well as the
function, offset, and line number in the source code
where the access occurred.
(d) The total number of traces associated with the
data-race. The individual traces can be displayed by
clicking on the button to the left of the "Total
Traces" label. Each trace refers to the pair of thread
callstacks at the time the two data-race accesses
occurred. When a trace is selected, the two callstacks
will be displayed in the Race Details tab in the
right-hand pane of the tha window (see below). The
frame at the top of the callstack for the first access
is selected by default.
The Dual Source Tab
The Dual Source tab is shown if data-race data is in
one or more of the experiments shown. The Dual Source
tab shows the two source locations, based on the
selected data-race.
For a selected data-race, it shows the source locations
for the two accesses of the data-race, as shown in the
Race Detail tab.
The source line where the access occurred will appear
highlighted. If the source code was compiled with -g,
then compiler commentary may appear interleaved in the
source code. The upper pane contains the source
corresponding to Access 1 of the selected data-race,
and the lower pane contains the source corresponding to
Access 2.
To the left of each source line, metrics that relate to
that source line are shown. The default metric shown is
the exclusive number of data-race accesses that
occurred at that source line. The number shown is
actually a lower bound of the number of data-race
accesses that occurred at that line
The metrics that are shown can be changed using the Set
Data Presentation dialog box (see "Selecting the Data
Presentation Options" below).
Exclusive metrics relate to the source line at which
they appear only. Inclusive metrics relate to the
source line at which they appear and to any functions
that have been called from that source line. Count
metrics are shown as an integer count. Percentages are
shown to a precision of 0.01 %. Because of rounding,
percentages may not sum to exactly 100 %.
To reorder the columns of metrics in the source
display, drag the column header to the place you want
it to appear.
The Experiments Tab
The Experiments tab is divided into two panels. The top
panel shows a tree that contains nodes for the load
objects in the experiment loaded. The bottom panel
lists error and warning messages from the tha session.
For more information about the Experiments tab, refer
to the analyzer(1) man page.
THA WINDOW -- RIGHT HAND TABS
The right-hand pane of the tha window contains tabs for
displaying additional information about a data-race. The
Summary tab is always shown. The Race Details tab is shown
if the Races tab is shown.
The Summary Tab
The Summary tab shows summary information about a
data-race access selected from the Races tab. This
information includes the object file name, source file
name, and PC (program counter) address.
The Race Details Tab
The Race Details tab is selected whenever the Races tab
is raised, and a selection made from the Races tab. It
shows detailed information about a data-race trace
selected from the Races tab. For each data-race trace
selected, the data-race id is shown. In addition, for
each of the two data-race accesses that constitute that
data-race, the type of access (Read or Write) and the
callstack of a thread when the access occurred are
shown. By default, the frame at the top of the
callstack is selected.
DATA-RACE DETECTION
A data-race occurs when two or more threads in a single pro-
cess access the same memory location concurrently, 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. In such situations, the order of accesses is non-
deterministic, and the computation may give different
results depending on that order. Some data-races may be
benign (for example, when the memory access is used for a
busy-wait), but many data-races are bugs in the program.
Data-race-detection experiments record data-races that are
detected during the execution of a multi-threaded process.
Data-race detection works on multi-threaded programs written
using POSIX thread APIs, Solaris thread APIs, OpenMP, Sun
parallel directives, Cray parallel directives, or a mix of
the above.
There are three steps involved in detecting data-races:
o Instrument the source code.
o Create a data-race-detection experiment.
o Examine the data-race-detection experiment.
These three steps are described below.
Step 1: Instrument the source code
In order to enable data-race detection in a program,
the source files must be compiled with a special com-
piler option. This special option for each of C, C++,
and Fortan 90 is:
-xinstrument=datarace
For data race detection in a program parallelized using
OpenMP directives, Sun directives, or Cray directives,
a new version of libmtsk is needed. At product release
time, a patch for that version will be issued; but
prior to that, a copy of that library is installed with
the bits, and will be automatically picked up by col-
lect.
Step 2: Create a data-race-detection experiment
Use the collect command with the -r races flag to run
the program and create a data-race-detection experiment
during the execution of the process:
Data-race-detection data collected consists of pairs of
data-accesses that constitute a race.
Data-race-detection data is converted into the "Race
Accesses" metric.
See collect(1) for more information.
Step 3: Examine the data-race-detection experiment
A data-race-detection experiment can be examined with
either the tha or analyzer commands (GUI), or with the
er_print utility (command-line).
Both the tha and the analyzer commands present a GUI
interface; the former presents a simplified set of
default tabs, but is otherwise identical to the
analyzer. The er_print utility, on the other hand,
presents a command-line interface.
SELECTING DATA PRESENTATION OPTIONS
You can control the presentation of data from the Set Data
Presentation dialog box. To open this dialog box, click on
the Set Data Presentation button in the tool bar, or choose
Set Data Presentation from the View menu.
The Set Data Presentation dialog box has a tabbed pane with
seven tabs. Refer to the analyzer(1) man page for more
information.
DEFAULTS
The Thread Analyzer processes directives from a .er.rc file
in the current directory, if present; from a .er.rc file in
the user's home directory, if present; and from a system
er.rc file installed with the product.
These .er.rc files can contain default settings for which
tabs are visible (rtabs), when the Thread Analyzer is
brought up. The tabs are named by the er_print command for
the corresponding report, except for the Experiments Tab,
named headers, the Timeline Tab, named timeline, the Dual
Source Tab, named dsrc, and the Source/Disassembly tab,
named srcdis.
The .er.rc files can also contain default settings for
metrics, sorting, and for specifying compiler commentary
options and highlighting thresholds for source and disassem-
bly output. The files also specify a path for C++ name
demangling for other compilers, as well as default settings
for the Timeline tab, and for name formatting, and setting
View Mode (viewmode).
The .er.rc files can also contain a setting, en_desc
{on|off} to control whether or not descendant experiments
are selected and read when the founder experiment is read.
The .er.rc files can also contain directives to control the
search path for source and object files. In the Thread
Analyzer, an .er.rc file can be saved by clicking on the
Save button in the Set Data Presentation dialog box, which
you can open from the View menu. Saving an .er.rc file from
the Set Data Presentation dialog box not only affects subse-
quent invocations of the Thread Analyzer, but also the
er_print utility and er_src utility. See the description of
these directives and files, and their processing, in the
er_print(1) man page.
The Thread Analyzer puts a message into its Errors/Warning
logs areas naming the user .er.rc files it processed,
including any processing message generated when any tab is
loaded.
SEE ALSO
analyzer(1), collect(1), er_archive(1), er_cp(1),
er_export(1), er_mv(1), er_print(1), er_rm(1), er_src(1),
tha(1), and the Performance Analyzer manual.