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 the
Analyzer customized for examining Thread Analyzer experi-
ments.
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 and deadlock-detection; for
further information on those, see the sections "DATA-RACE
DETECTION" and "DEADLOCK 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 tab will be shown if
data-race data is in one or more of the loaded experiments.
The Deadlocks tab will be shown if deadlock data is in one
or more of the loaded experiments. The Dual Source tab will
be shown if either the Races or Deadlocks tabs are shown.
By default, the Races tab is selected, if available. If it
is not available, the Deadlocks tab is selected, if it is
available. If neither is 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. The tab presents the
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:
(1) A unique id that identifies the data-race
(2) One or more virtual addresses (Vaddr) associated
with the data-race
(3) 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.
(4) 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 Deadlocks Tab
The Deadlocks tab is shown if deadlock data is in one
or more of the experiments loaded. The tab presents the
list of deadlocks detected in the program. By default
the first deadlock in the list of deadlocks is
selected.
For each deadlock, the following information is shown:
(1) A unique id that identifies the deadlock
(2) The type of the deadlock (potential or actual)
(3) The total number of threads involved in the
deadlock. The context of each thread can be displayed
by clicking on the button to the left of the "Total
Threads" label. Each thread context includes the fol-
lowing information:
o The thread id
o The virtual address of a lock being held by the
thread
o The source line number where the thread held the lock
o The virtual address of a lock requested by the thread
o The source line number where the thread requested
that lock
When a thread context is selected, the two callstacks
where the lock hold and lock request took place will be
displayed in the Deadlocks Details tab in the right-
hand pane of the tha window (see below).
The Dual Source Tab
The Dual Source tab is shown if either data-race or
deadlock data is in one or more of the experiments
shown. The Dual Source tab shows the two source loca-
tions, based on the selected data-race or deadlock.
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. For a selected deadlock, it shows the
two accesses corresponding to acquiring a first lock,
and deadlocking attempting to acquire a second lock,
from the thread selected in the Deadlock 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 Deadlock Details tab is shown
if the Deadlocks 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 each
callstack is selected.
The Deadlock Details Tab
The Deadlock Details tab is selected whenever the
Deadlocks tab is raised, and a selection made from the
Deadlocks Tab. It shows detailed information about a
thread context selected from the Deadlocks tab.
For each thread context selected, the deadlock id,
deadlock type, and thread id are shown. In addition,
for each of the two lock operations involved, the type
of lock operation (Lock being held or Lock being
requested) and the callstacks of the thread are shown.
By default, the frame at the top of each 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:
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.
DEADLOCK DETECTION
Deadlock describes a condition where two or more threads are
blocked (hang) forever, waiting for each other. Suppose we
have a process with two or more threads. A deadlock occurs
when the following three conditions hold:
(1) Threads already holding locks request new locks,
(2) The requests are made concurrently, and
(3) Two or more threads form a circular chain where each
thread waits for a lock that the next thread in the chain
holds.
Here is an example of a deadlock condition:
Thread 1: holds lock A, requests lock B
Thread 2: holds lock B, requests lock A
A deadlock can be of two types: A "potential deadlock" or an
"actual deadlock". A potential deadlock is a deadlock that
did not occur in the experiment, but can occur in different
runs of the program depending on the timings of the requests
for locks by the threads. An actual deadlock is one that
actually occured in the experiment. An actual deadlock
causes the threads involved to hang, but it may or may not
cause the whole process to hang.
Deadlock-detection experiments record both potential and
actual deadlocks that are detected during the execution of a
multi-threaded process. Deadlock 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 two steps involved in detecting deadlocks:
Step 1: Create a deadlock-detection experiment
Use the collect command with the -r deadlocks flag to
run the program and create a deadlock-detection experi-
ment during the execution of the process.
Deadlock-detection data collected consists of lock
requests that form a chain. Deadlock-detection data is
converted into the "Deadlocks" metric.
See collect(1) for more information.
Step 2: Examine the deadlock-detection experiment
A deadlock-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.