Thread Analyzer follows the same “collect-analyze” model that the Oracle Developer Studio Performance Analyzer uses.
There are three steps involved in using Thread Analyzer:
In order to enable data race detection in a program, the code must first be instrumented to monitor memory accesses at runtime. The instrumentation can be done on application source code or on the application binary. The tutorial shows how to use both methods of instrumenting the programs.
To instrument the source code, you must compile the application with the special compiler option -xinstrument=datarace. This option instructs the compiler to instrument the generated code for data race detection.
Add the -xinstrument=datarace compiler option to the existing set of options you use to compile your program.
You can use the following commands for instrumenting the source code for the tutorial:
% cc -xinstrument=datarace -g -xopenmp=noopt -o prime_omp_inst prime_omp.c -lm
% cc -xinstrument=datarace -g -o prime_pthr_inst prime_pthr.c -lm
Notice that in the example, the output file is specified with _inst at the end so that you can tell that the binary is the instrumented binary. This is not required.
To instrument a program's binary code instead of the source code, you need to use the discover tool, which is included in Oracle Developer Studio and is documented in the discover(1) man page and Oracle Developer Studio 12.6: Discover and Uncover User’s Guide.
For the tutorial examples, type the following command to compile the code:
% cc -xopenmp=noopt -g -o prime_omp prime_omp.c -lm
% cc -g -O2 -o prime_pthr prime_pthr.c -lm
Then run discover on the prime_omp and prime_pthr optimized binaries that you created:
% discover -i datarace -o prime_omp_disc prime_omp
% discover -i datarace -o prime_pthr_disc prime_pthr
These commands create instrumented binaries, prime_omp_disc and prime_pthr_disc that you can use with collect to create experiments that you can examine with Thread Analyzer.
Use the collect command with the -r race flag to run the program and create a data-race-detection experiment during the execution of the process. For OpenMP programs, make sure that the number of threads used is larger than one. In the tutorial samples, four threads are used.
To create experiments from the binaries that you created by instrumenting the source code:
% collect -r race -o prime_omp_inst.er prime_omp_inst
% collect -r race -o prime_pthr_inst.er prime_pthr_inst
To create experiments from the binaries that you created by using the discover tool:
% collect -r race -o prime_omp_disc.er prime_omp_disc
% collect -r race -o prime_pthr_disc.er prime_pthr_disc
To increase the likelihood of detecting data races, it is recommended that you create several data-race-detection experiments using collect with the -r race flag. Use a different number of threads and different input data for each experiment.
For example, in prime_omp.c, the number of threads is set by the following line:
#define THREADS 4
The number of threads can be changed by changing 4 in the above to some other integer larger than 1, for example 8.
The following line in prime_omp.c limits the program to look for prime numbers between 2 and 3000:
#define N 3000
You can provide different input data by changing the value of N to make the program do more or less work.
You can examine a data-race-detection experiment with Thread Analyzer, Performance Analyzer, or the er_print utility. Both Thread Analyzer and Performance Analyzer present a GUI interface; Thread Analyzer presents a simplified set of default views, but is otherwise identical to Performance Analyzer.
To start Thread Analyzer, type the following command:
% tha
When you first start Thread Analyzer, you see the Welcome screen.
Thread Analyzer has a menu bar, a tool bar, and vertical navigation bar on the left that enables you to select data views.
The following data views are shown by default:
Overview screen shows a metrics overview of the loaded experiments.
Races view shows a list of data races detected in the program, and associated call stack traces. When you select an item in the Races view, the Race Details window shows detailed information about the data race or call stack trace selected.
Dual Source view shows the two source locations corresponding to the two accesses of a selected data race. The source line where a data race access occurred is highlighted.
Experiments view shows the load objects in the experiment, and lists error and warning messages.
You can choose to see other views with the More Views options menu.
The er_print utility presents a command-line interface. You can use the er_print utility in an interactive session and specify sub-commands during the session. You can also use command-line options to specify sub-commands non-interactively.
The following sub-commands are useful for examining races with the er_print utility:
–races
This reports any data races revealed in the experiment. Specify races at the (er_print) prompt or –races on the er_print command line.
–rdetail race_id
This displays detailed information about the data race with the specified race_id. Specify rdetail at the (er_print) prompt or –rdetail on the er_print command line. If the specified race_id is all, then detailed information about all data races will be displayed. Otherwise, specify a single race number such as 1 for the first data race.
–header
This displays descriptive information about the experiment, and reports any errors or warnings. Specify header at the (er_print) prompt or –header on the command line.
Refer to the collect(1), tha(1), analyzer(1), and er_print(1) man pages for more information.