This appendix includes some tips for using Thread Analyzer.
Tips for compiling an application before collecting an experiment:
Use the –g compiler option when building application binaries. This enables Thread Analyzer to report line number information for data races and deadlocks.
Compile with an optimization level less than –xO3 when building application binaries. Compiler transformations might distort line number information and make the results difficult to understand.
Thread Analyzer interposes on the routines shown in Memory Allocation APIs. Linking to archive versions of memory allocation libraries might result in false positive data races being reported.
Tips for instrumenting an application for data race detection before collecting an experiment:
The collect -r race command issues a warning if the binary is not instrumented for data race detection, as shown here:
% collect -r races a.out WARNING: Target `a.out' is not instrumented for datarace detection; reported datarace data may be misleading
You can determine whether a binary is instrumented for data race detection by using the nm command and looking for calls to tha routines. If routines whose names begin with __tha_ are shown, the binary is instrumented. Example output is shown below.
Source-level instrumentation:
% cc -xopenmp -g -xinstrument=datarace source.c % nm a.out | grep __tha_ [71] | 135408| 0|FUNC |GLOB |0 |UNDEF |__tha_get_stack_id [53] | 135468| 0|FUNC |GLOB |0 |UNDEF |__tha_src_read_w_frame [61] | 135444| 0|FUNC |GLOB |0 |UNDEF |__tha_src_write_w_frame
Binary-level instrumentation:
% cc -xopenmp -g source.c % discover -i datarace -o a.out.i a.out % nm a.out.i | grep __tha_ [88] | 0| 0|NOTY |GLOB |0 |UNDEF |__tha_read_w_pc_frame [49] | 0| 0|NOTY |GLOB |0 |UNDEF |__tha_write_w_pc_frame
Tips for running an instrumented application to detect data races and deadlocks.
Make sure that the Oracle Solaris system has all the required patches installed. The collect command lists any missing required patches. For OpenMP applications, the latest version of libmtsk.so is required.
Instrumentation might cause a significant slowdown in execution time, 50 times or more, and an increase in memory consumption. You can try reducing the execution time by using a smaller data set. You can also try reducing the execution time by increasing the number of threads.
To detect data races, make sure that the application is using more than one thread. For OpenMP, the number of threads can be specified by setting the environment variable OMP_NUM_THREADS to the desired number of threads, and setting the environment variable OMP_DYNAMIC to FALSE.
Tips for reporting of data races:
Thread Analyzer detects data races at runtime. The runtime behavior of an application depends on the input data set used and operating system scheduling. Run the application under collect with different numbers of threads and with different input data sets. Also repeat experiments with a single data set to maximize the tool's chance of detecting data races.
Thread Analyzer detects data races between different threads that are spawned from a single process. It does not detect data races between different processes.
Thread Analyzer does not report the name of the variable accessed in a data race. However, you can determine the name of the variable by inspecting the source lines where the two data race accesses occurred, and determining which variables are written to and read from on those source lines.
In some cases, Thread Analyzer might report data races that did not actually occur in the program. These data races are called false positives. This usually happens when a user-implemented synchronization is used or when memory is recycled between threads. For example, if your code includes hand-coded assembly that implements spin locks, Thread Analyzer will not recognize these synchronization points. Insert calls to Thread Analyzer user APIs in your source code to notify Thread Analyzer about user-defined synchronizations. See False Positives and Appendix A, APIs Recognized by Thread Analyzer for more information.
Data races reported using source-level instrumentation and binary-level instrumentation might not be identical. In binary-level instrumentation, shared libraries are instrumented by default as they are opened, whether they are statically linked in the program or opened dynamically by dlopen(). In source-level instrumentation, libraries are instrumented only if their sources are compiled with –xinstrument=datarace.