Man Page rdt.1
NAME
rdt - GUI for analyzing a data-race-detection experiment
SYNOPSIS
rdt args
DESCRIPTION
The rdt command invokes a GUI for analyzing data-races col-
lected by the Collector using the collect(1) command.
The Collector gathers data-race information to create a
data-race-detection experiment during the execution of a
process. The rdt command reads in such an experiment and
displays any data-races detected.
A command-line version of the rdt command is available as
the er_print(1) utility.
To start rdt, type the following on the command line:
rdt[ data-race-detection-experiment]
Both the rdt command and the analyzer(1) command can be used
to read a data-race-detection experiment. The rdt command
has the same functionality and features as the analyzer com-
mand, but shows a simplified set of default tabs that per-
tain to data-race detection.
For more information about data-race detection, see the sec-
tion "DATA-RACE DETECTION" below.
DEFAULTS
rdt 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. See the er_print(1) and
analyzer(1) man pages for more information.
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.
RDT WINDOW -- LEFT HAND TABS
The rdt 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 tabs
that are shown by default are the following three:
o The Races tab
o The Race Source tab
o The Experiments tab
By default, the Races tab is selected.
The Races Tab
The Races tab 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 rdt window (see below). The
frame at the top of the callstack for the first access
is selected by default.
The Race Source Tab
The Race Source tab shows the two source locations
corresponding to the two accesses of a selected data-
race. The source line where a data-race access occurred
will appear highlighted. If the source code was com-
piled with -g, then compiler commentary may appear
interleaved in the source code. The upper pane con-
tains 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 rdt session.
For more information about the Experiments tab, refer
to the analyzer(1) man page.
Selecting the 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.
RDT WINDOW -- RIGHT HAND TABS
The right-hand pane of the rdt window contains tabs for
displaying additional information about a data-race. The
tabs that are shown by default are the following two:
o The Summary tab
o The Race Details tab
By default, the Race Details tab is selected.
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 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 on" flag to run
the program and create a data-race-detection experiment
during the execution of the process:
collect -r option
The allowed values of option are:
Value Meaning
on Turn on data-race-detection data
off Turn off data-race-detection data
Note that the "-r on/off" flag is not available on sys-
tems running the Linux operating system.
Data-race-detection data collected consists of pairs of
data-race 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
the rdt command, with the analyzer command, or with the
er_print utility.
Both the rdt 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.
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),
and the Performance Analyzer manual.
Man(1) output converted with
man2html