bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 1 | <?xml version="1.0"?> <!-- -*- sgml -*- --> |
| 2 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| 3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
| 4 | [ <!ENTITY % vg-entities SYSTEM "../../docs/xml/vg-entities.xml"> %vg-entities; ]> |
| 5 | |
| 6 | |
| 7 | <chapter id="drd-manual" xreflabel="DRD: a thread error detector"> |
| 8 | <title>DRD: a thread error detector</title> |
| 9 | |
| 10 | <para>To use this tool, you must specify |
njn | 7e5d4ed | 2009-07-30 02:57:52 +0000 | [diff] [blame] | 11 | <option>--tool=drd</option> |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 12 | on the Valgrind command line.</para> |
| 13 | |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 14 | |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 15 | <sect1 id="drd-manual.overview" xreflabel="Overview"> |
njn | 05a8917 | 2009-07-29 02:36:21 +0000 | [diff] [blame] | 16 | <title>Overview</title> |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 17 | |
| 18 | <para> |
| 19 | DRD is a Valgrind tool for detecting errors in multithreaded C and C++ |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 20 | programs. The tool works for any program that uses the POSIX threading |
| 21 | primitives or that uses threading concepts built on top of the POSIX threading |
| 22 | primitives. |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 23 | </para> |
| 24 | |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 25 | <sect2 id="drd-manual.mt-progr-models" xreflabel="MT-progr-models"> |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 26 | <title>Multithreaded Programming Paradigms</title> |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 27 | |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 28 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 29 | There are two possible reasons for using multithreading in a program: |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 30 | <itemizedlist> |
| 31 | <listitem> |
| 32 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 33 | To model concurrent activities. Assigning one thread to each activity |
| 34 | can be a great simplification compared to multiplexing the states of |
| 35 | multiple activities in a single thread. This is why most server software |
| 36 | and embedded software is multithreaded. |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 37 | </para> |
| 38 | </listitem> |
| 39 | <listitem> |
| 40 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 41 | To use multiple CPU cores simultaneously for speeding up |
| 42 | computations. This is why many High Performance Computing (HPC) |
| 43 | applications are multithreaded. |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 44 | </para> |
| 45 | </listitem> |
| 46 | </itemizedlist> |
| 47 | </para> |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 48 | |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 49 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 50 | Multithreaded programs can use one or more of the following programming |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 51 | paradigms. Which paradigm is appropriate depends e.g. on the application type. |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 52 | Some examples of multithreaded programming paradigms are: |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 53 | <itemizedlist> |
| 54 | <listitem> |
| 55 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 56 | Locking. Data that is shared over threads is protected from concurrent |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 57 | accesses via locking. E.g. the POSIX threads library, the Qt library |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 58 | and the Boost.Thread library support this paradigm directly. |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 59 | </para> |
| 60 | </listitem> |
| 61 | <listitem> |
| 62 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 63 | Message passing. No data is shared between threads, but threads exchange |
| 64 | data by passing messages to each other. Examples of implementations of |
| 65 | the message passing paradigm are MPI and CORBA. |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 66 | </para> |
| 67 | </listitem> |
| 68 | <listitem> |
| 69 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 70 | Automatic parallelization. A compiler converts a sequential program into |
| 71 | a multithreaded program. The original program may or may not contain |
| 72 | parallelization hints. One example of such parallelization hints is the |
| 73 | OpenMP standard. In this standard a set of directives are defined which |
| 74 | tell a compiler how to parallelize a C, C++ or Fortran program. OpenMP |
| 75 | is well suited for computational intensive applications. As an example, |
| 76 | an open source image processing software package is using OpenMP to |
| 77 | maximize performance on systems with multiple CPU |
njn | 7316df2 | 2009-08-04 01:16:01 +0000 | [diff] [blame] | 78 | cores. GCC supports the |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 79 | OpenMP standard from version 4.2.0 on. |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 80 | </para> |
| 81 | </listitem> |
| 82 | <listitem> |
| 83 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 84 | Software Transactional Memory (STM). Any data that is shared between |
| 85 | threads is updated via transactions. After each transaction it is |
| 86 | verified whether there were any conflicting transactions. If there were |
| 87 | conflicts, the transaction is aborted, otherwise it is committed. This |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 88 | is a so-called optimistic approach. There is a prototype of the Intel C++ |
| 89 | Compiler available that supports STM. Research about the addition of |
| 90 | STM support to GCC is ongoing. |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 91 | </para> |
| 92 | </listitem> |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 93 | </itemizedlist> |
| 94 | </para> |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 95 | |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 96 | <para> |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 97 | DRD supports any combination of multithreaded programming paradigms as |
| 98 | long as the implementation of these paradigms is based on the POSIX |
| 99 | threads primitives. DRD however does not support programs that use |
| 100 | e.g. Linux' futexes directly. Attempts to analyze such programs with |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 101 | DRD will cause DRD to report many false positives. |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 102 | </para> |
| 103 | |
| 104 | </sect2> |
| 105 | |
| 106 | |
| 107 | <sect2 id="drd-manual.pthreads-model" xreflabel="Pthreads-model"> |
| 108 | <title>POSIX Threads Programming Model</title> |
| 109 | |
| 110 | <para> |
| 111 | POSIX threads, also known as Pthreads, is the most widely available |
| 112 | threading library on Unix systems. |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 113 | </para> |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 114 | |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 115 | <para> |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 116 | The POSIX threads programming model is based on the following abstractions: |
| 117 | <itemizedlist> |
| 118 | <listitem> |
| 119 | <para> |
| 120 | A shared address space. All threads running within the same |
| 121 | process share the same address space. All data, whether shared or |
| 122 | not, is identified by its address. |
| 123 | </para> |
| 124 | </listitem> |
| 125 | <listitem> |
| 126 | <para> |
| 127 | Regular load and store operations, which allow to read values |
| 128 | from or to write values to the memory shared by all threads |
| 129 | running in the same process. |
| 130 | </para> |
| 131 | </listitem> |
| 132 | <listitem> |
| 133 | <para> |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 134 | Atomic store and load-modify-store operations. While these are |
| 135 | not mentioned in the POSIX threads standard, most |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 136 | microprocessors support atomic memory operations. |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 137 | </para> |
| 138 | </listitem> |
| 139 | <listitem> |
| 140 | <para> |
| 141 | Threads. Each thread represents a concurrent activity. |
| 142 | </para> |
| 143 | </listitem> |
| 144 | <listitem> |
| 145 | <para> |
| 146 | Synchronization objects and operations on these synchronization |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 147 | objects. The following types of synchronization objects have been |
| 148 | defined in the POSIX threads standard: mutexes, condition variables, |
bart | a617d11 | 2009-07-27 17:43:39 +0000 | [diff] [blame] | 149 | semaphores, reader-writer synchronization objects, barriers and |
| 150 | spinlocks. |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 151 | </para> |
| 152 | </listitem> |
| 153 | </itemizedlist> |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 154 | </para> |
| 155 | |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 156 | <para> |
| 157 | Which source code statements generate which memory accesses depends on |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 158 | the <emphasis>memory model</emphasis> of the programming language being |
| 159 | used. There is not yet a definitive memory model for the C and C++ |
| 160 | languages. For a draft memory model, see also the document |
| 161 | <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2338.html"> |
| 162 | WG21/N2338: Concurrency memory model compiler consequences</ulink>. |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 163 | </para> |
| 164 | |
| 165 | <para> |
| 166 | For more information about POSIX threads, see also the Single UNIX |
| 167 | Specification version 3, also known as |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 168 | <ulink url="http://www.opengroup.org/onlinepubs/000095399/idx/threads.html"> |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 169 | IEEE Std 1003.1</ulink>. |
| 170 | </para> |
| 171 | |
| 172 | </sect2> |
| 173 | |
| 174 | |
| 175 | <sect2 id="drd-manual.mt-problems" xreflabel="MT-Problems"> |
| 176 | <title>Multithreaded Programming Problems</title> |
| 177 | |
| 178 | <para> |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 179 | Depending on which multithreading paradigm is being used in a program, |
| 180 | one or more of the following problems can occur: |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 181 | <itemizedlist> |
| 182 | <listitem> |
| 183 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 184 | Data races. One or more threads access the same memory location without |
| 185 | sufficient locking. Most but not all data races are programming errors |
| 186 | and are the cause of subtle and hard-to-find bugs. |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 187 | </para> |
| 188 | </listitem> |
| 189 | <listitem> |
| 190 | <para> |
| 191 | Lock contention. One thread blocks the progress of one or more other |
| 192 | threads by holding a lock too long. |
| 193 | </para> |
| 194 | </listitem> |
| 195 | <listitem> |
| 196 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 197 | Improper use of the POSIX threads API. Most implementations of the POSIX |
| 198 | threads API have been optimized for runtime speed. Such implementations |
| 199 | will not complain on certain errors, e.g. when a mutex is being unlocked |
| 200 | by another thread than the thread that obtained a lock on the mutex. |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 201 | </para> |
| 202 | </listitem> |
| 203 | <listitem> |
| 204 | <para> |
| 205 | Deadlock. A deadlock occurs when two or more threads wait for |
| 206 | each other indefinitely. |
| 207 | </para> |
| 208 | </listitem> |
| 209 | <listitem> |
| 210 | <para> |
| 211 | False sharing. If threads that run on different processor cores |
| 212 | access different variables located in the same cache line |
| 213 | frequently, this will slow down the involved threads a lot due |
| 214 | to frequent exchange of cache lines. |
| 215 | </para> |
| 216 | </listitem> |
| 217 | </itemizedlist> |
| 218 | </para> |
| 219 | |
| 220 | <para> |
| 221 | Although the likelihood of the occurrence of data races can be reduced |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 222 | through a disciplined programming style, a tool for automatic |
| 223 | detection of data races is a necessity when developing multithreaded |
| 224 | software. DRD can detect these, as well as lock contention and |
| 225 | improper use of the POSIX threads API. |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 226 | </para> |
| 227 | |
| 228 | </sect2> |
| 229 | |
| 230 | |
bart | e8cdb36 | 2008-12-22 07:10:44 +0000 | [diff] [blame] | 231 | <sect2 id="drd-manual.data-race-detection" xreflabel="data-race-detection"> |
| 232 | <title>Data Race Detection</title> |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 233 | |
| 234 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 235 | The result of load and store operations performed by a multithreaded program |
| 236 | depends on the order in which memory operations are performed. This order is |
| 237 | determined by: |
| 238 | <orderedlist> |
| 239 | <listitem> |
| 240 | <para> |
| 241 | All memory operations performed by the same thread are performed in |
| 242 | <emphasis>program order</emphasis>, that is, the order determined by the |
| 243 | program source code and the results of previous load operations. |
| 244 | </para> |
| 245 | </listitem> |
| 246 | <listitem> |
| 247 | <para> |
| 248 | Synchronization operations determine certain ordering constraints on |
| 249 | memory operations performed by different threads. These ordering |
| 250 | constraints are called the <emphasis>synchronization order</emphasis>. |
| 251 | </para> |
| 252 | </listitem> |
| 253 | </orderedlist> |
| 254 | The combination of program order and synchronization order is called the |
| 255 | <emphasis>happens-before relationship</emphasis>. This concept was first |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 256 | defined by S. Adve et al in the paper <emphasis>Detecting data races on weak |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 257 | memory systems</emphasis>, ACM SIGARCH Computer Architecture News, v.19 n.3, |
| 258 | p.234-243, May 1991. |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 259 | </para> |
| 260 | |
| 261 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 262 | Two memory operations <emphasis>conflict</emphasis> if both operations are |
| 263 | performed by different threads, refer to the same memory location and at least |
| 264 | one of them is a store operation. |
| 265 | </para> |
| 266 | |
| 267 | <para> |
| 268 | A multithreaded program is <emphasis>data-race free</emphasis> if all |
| 269 | conflicting memory accesses are ordered by synchronization |
| 270 | operations. |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 271 | </para> |
| 272 | |
| 273 | <para> |
| 274 | A well known way to ensure that a multithreaded program is data-race |
| 275 | free is to ensure that a locking discipline is followed. It is e.g. |
| 276 | possible to associate a mutex with each shared data item, and to hold |
| 277 | a lock on the associated mutex while the shared data is accessed. |
| 278 | </para> |
| 279 | |
| 280 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 281 | All programs that follow a locking discipline are data-race free, but not all |
| 282 | data-race free programs follow a locking discipline. There exist multithreaded |
| 283 | programs where access to shared data is arbitrated via condition variables, |
| 284 | semaphores or barriers. As an example, a certain class of HPC applications |
| 285 | consists of a sequence of computation steps separated in time by barriers, and |
| 286 | where these barriers are the only means of synchronization. Although there are |
| 287 | many conflicting memory accesses in such applications and although such |
| 288 | applications do not make use mutexes, most of these applications do not |
| 289 | contain data races. |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 290 | </para> |
| 291 | |
| 292 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 293 | There exist two different approaches for verifying the correctness of |
| 294 | multithreaded programs at runtime. The approach of the so-called Eraser |
| 295 | algorithm is to verify whether all shared memory accesses follow a consistent |
| 296 | locking strategy. And the happens-before data race detectors verify directly |
| 297 | whether all interthread memory accesses are ordered by synchronization |
| 298 | operations. While the last approach is more complex to implement, and while it |
| 299 | is more sensitive to OS scheduling, it is a general approach that works for |
| 300 | all classes of multithreaded programs. An important advantage of |
| 301 | happens-before data race detectors is that these do not report any false |
| 302 | positives. |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 303 | </para> |
| 304 | |
| 305 | <para> |
bart | e8cdb36 | 2008-12-22 07:10:44 +0000 | [diff] [blame] | 306 | DRD is based on the happens-before algorithm. |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 307 | </para> |
| 308 | |
| 309 | </sect2> |
| 310 | |
| 311 | |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 312 | </sect1> |
| 313 | |
| 314 | |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 315 | <sect1 id="drd-manual.using-drd" xreflabel="Using DRD"> |
| 316 | <title>Using DRD</title> |
| 317 | |
njn | a331164 | 2009-08-10 01:29:14 +0000 | [diff] [blame] | 318 | <sect2 id="drd-manual.options" xreflabel="DRD Command-line Options"> |
| 319 | <title>DRD Command-line Options</title> |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 320 | |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 321 | <para>The following command-line options are available for controlling the |
| 322 | behavior of the DRD tool itself:</para> |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 323 | |
| 324 | <!-- start of xi:include in the manpage --> |
| 325 | <variablelist id="drd.opts.list"> |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 326 | <varlistentry> |
| 327 | <term> |
| 328 | <option><![CDATA[--check-stack-var=<yes|no> [default: no]]]></option> |
| 329 | </term> |
| 330 | <listitem> |
| 331 | <para> |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 332 | Controls whether DRD detects data races on stack |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 333 | variables. Verifying stack variables is disabled by default because |
| 334 | most programs do not share stack variables over threads. |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 335 | </para> |
| 336 | </listitem> |
| 337 | </varlistentry> |
| 338 | <varlistentry> |
| 339 | <term> |
| 340 | <option><![CDATA[--exclusive-threshold=<n> [default: off]]]></option> |
| 341 | </term> |
| 342 | <listitem> |
| 343 | <para> |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 344 | Print an error message if any mutex or writer lock has been |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 345 | held longer than the time specified in milliseconds. This |
| 346 | option enables the detection of lock contention. |
| 347 | </para> |
| 348 | </listitem> |
| 349 | </varlistentry> |
| 350 | <varlistentry> |
| 351 | <term> |
bart | 282e337 | 2011-10-13 18:50:15 +0000 | [diff] [blame] | 352 | <option><![CDATA[--join-list-vol=<n> [default: 10]]]></option> |
| 353 | </term> |
| 354 | <listitem> |
| 355 | <para> |
| 356 | Data races that occur between a statement at the end of one thread |
| 357 | and another thread can be missed if memory access information is |
| 358 | discarded immediately after a thread has been joined. This option |
| 359 | allows to specify for how many joined threads memory access information |
| 360 | should be retained. |
| 361 | </para> |
| 362 | </listitem> |
| 363 | </varlistentry> |
| 364 | <varlistentry> |
| 365 | <term> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 366 | <option> |
| 367 | <![CDATA[--first-race-only=<yes|no> [default: no]]]> |
| 368 | </option> |
| 369 | </term> |
| 370 | <listitem> |
| 371 | <para> |
| 372 | Whether to report only the first data race that has been detected on a |
| 373 | memory location or all data races that have been detected on a memory |
| 374 | location. |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 375 | </para> |
| 376 | </listitem> |
| 377 | </varlistentry> |
| 378 | <varlistentry> |
| 379 | <term> |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 380 | <option> |
bart | 639d0ad | 2011-03-12 14:26:01 +0000 | [diff] [blame] | 381 | <![CDATA[--free-is-write=<yes|no> [default: no]]]> |
| 382 | </option> |
| 383 | </term> |
| 384 | <listitem> |
| 385 | <para> |
| 386 | Whether to report races between accessing memory and freeing |
| 387 | memory. Enabling this option may cause DRD to run slightly |
philippe | e52e445 | 2013-12-12 23:19:13 +0000 | [diff] [blame] | 388 | slower. Notes:</para> |
| 389 | <itemizedlist> |
| 390 | <listitem> |
| 391 | <para> |
| 392 | Don't enable this option when using custom memory allocators |
| 393 | that use |
| 394 | the <computeroutput>VG_USERREQ__MALLOCLIKE_BLOCK</computeroutput> |
| 395 | and <computeroutput>VG_USERREQ__FREELIKE_BLOCK</computeroutput> |
| 396 | because that would result in false positives. |
| 397 | </para> |
| 398 | </listitem> |
| 399 | <listitem> |
| 400 | <para>Don't enable this option when using reference-counted |
| 401 | objects because that will result in false positives, even when |
| 402 | that code has been annotated properly with |
| 403 | <computeroutput>ANNOTATE_HAPPENS_BEFORE</computeroutput> |
| 404 | and <computeroutput>ANNOTATE_HAPPENS_AFTER</computeroutput>. See |
| 405 | e.g. the output of the following command for an example: |
| 406 | <computeroutput>valgrind --tool=drd --free-is-write=yes |
| 407 | drd/tests/annotate_smart_pointer</computeroutput>. |
| 408 | </para> |
| 409 | </listitem> |
| 410 | </itemizedlist> |
bart | 639d0ad | 2011-03-12 14:26:01 +0000 | [diff] [blame] | 411 | </listitem> |
| 412 | </varlistentry> |
| 413 | <varlistentry> |
| 414 | <term> |
| 415 | <option> |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 416 | <![CDATA[--report-signal-unlocked=<yes|no> [default: yes]]]> |
| 417 | </option> |
| 418 | </term> |
| 419 | <listitem> |
| 420 | <para> |
| 421 | Whether to report calls to |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 422 | <function>pthread_cond_signal</function> and |
| 423 | <function>pthread_cond_broadcast</function> where the mutex |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 424 | associated with the signal through |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 425 | <function>pthread_cond_wait</function> or |
| 426 | <function>pthread_cond_timed_wait</function>is not locked at |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 427 | the time the signal is sent. Sending a signal without holding |
| 428 | a lock on the associated mutex is a common programming error |
| 429 | which can cause subtle race conditions and unpredictable |
| 430 | behavior. There exist some uncommon synchronization patterns |
| 431 | however where it is safe to send a signal without holding a |
| 432 | lock on the associated mutex. |
| 433 | </para> |
| 434 | </listitem> |
| 435 | </varlistentry> |
| 436 | <varlistentry> |
| 437 | <term> |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 438 | <option><![CDATA[--segment-merging=<yes|no> [default: yes]]]></option> |
| 439 | </term> |
| 440 | <listitem> |
| 441 | <para> |
| 442 | Controls segment merging. Segment merging is an algorithm to |
| 443 | limit memory usage of the data race detection |
| 444 | algorithm. Disabling segment merging may improve the accuracy |
| 445 | of the so-called 'other segments' displayed in race reports |
| 446 | but can also trigger an out of memory error. |
| 447 | </para> |
| 448 | </listitem> |
| 449 | </varlistentry> |
| 450 | <varlistentry> |
| 451 | <term> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 452 | <option><![CDATA[--segment-merging-interval=<n> [default: 10]]]></option> |
| 453 | </term> |
| 454 | <listitem> |
| 455 | <para> |
| 456 | Perform segment merging only after the specified number of new |
| 457 | segments have been created. This is an advanced configuration option |
| 458 | that allows to choose whether to minimize DRD's memory usage by |
| 459 | choosing a low value or to let DRD run faster by choosing a slightly |
| 460 | higher value. The optimal value for this parameter depends on the |
| 461 | program being analyzed. The default value works well for most programs. |
| 462 | </para> |
| 463 | </listitem> |
| 464 | </varlistentry> |
| 465 | <varlistentry> |
| 466 | <term> |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 467 | <option><![CDATA[--shared-threshold=<n> [default: off]]]></option> |
| 468 | </term> |
| 469 | <listitem> |
| 470 | <para> |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 471 | Print an error message if a reader lock has been held longer |
| 472 | than the specified time (in milliseconds). This option enables |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 473 | the detection of lock contention. |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 474 | </para> |
| 475 | </listitem> |
| 476 | </varlistentry> |
| 477 | <varlistentry> |
| 478 | <term> |
| 479 | <option><![CDATA[--show-confl-seg=<yes|no> [default: yes]]]></option> |
| 480 | </term> |
| 481 | <listitem> |
| 482 | <para> |
| 483 | Show conflicting segments in race reports. Since this |
| 484 | information can help to find the cause of a data race, this |
| 485 | option is enabled by default. Disabling this option makes the |
| 486 | output of DRD more compact. |
| 487 | </para> |
| 488 | </listitem> |
| 489 | </varlistentry> |
| 490 | <varlistentry> |
| 491 | <term> |
| 492 | <option><![CDATA[--show-stack-usage=<yes|no> [default: no]]]></option> |
| 493 | </term> |
| 494 | <listitem> |
| 495 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 496 | Print stack usage at thread exit time. When a program creates a large |
| 497 | number of threads it becomes important to limit the amount of virtual |
| 498 | memory allocated for thread stacks. This option makes it possible to |
mjw | 2be5122 | 2013-04-05 13:19:12 +0000 | [diff] [blame] | 499 | observe how much stack memory has been used by each thread of the |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 500 | client program. Note: the DRD tool itself allocates some temporary |
| 501 | data on the client thread stack. The space necessary for this |
| 502 | temporary data must be allocated by the client program when it |
| 503 | allocates stack memory, but is not included in stack usage reported by |
| 504 | DRD. |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 505 | </para> |
| 506 | </listitem> |
| 507 | </varlistentry> |
sewardj | 8eb8bab | 2015-07-21 14:44:28 +0000 | [diff] [blame] | 508 | <varlistentry> |
| 509 | <term> |
| 510 | <option><![CDATA[--ignore-thread-creation=<yes|no> [default: no]]]></option> |
| 511 | </term> |
| 512 | <listitem> |
| 513 | <para> |
| 514 | Controls whether all activities during thread creation should be |
| 515 | ignored. By default enabled only on Solaris. |
| 516 | Solaris provides higher throughput, parallelism and scalability than |
| 517 | other operating systems, at the cost of more fine-grained locking |
| 518 | activity. This means for example that when a thread is created under |
| 519 | glibc, just one big lock is used for all thread setup. Solaris libc |
| 520 | uses several fine-grained locks and the creator thread resumes its |
| 521 | activities as soon as possible, leaving for example stack and TLS setup |
| 522 | sequence to the created thread. |
| 523 | This situation confuses DRD as it assumes there is some false ordering |
| 524 | in place between creator and created thread; and therefore many types |
| 525 | of race conditions in the application would not be reported. To prevent |
| 526 | such false ordering, this command line option is set to |
| 527 | <computeroutput>yes</computeroutput> by default on Solaris. |
| 528 | All activity (loads, stores, client requests) is therefore ignored |
| 529 | during:</para> |
| 530 | <itemizedlist> |
| 531 | <listitem> |
| 532 | <para> |
| 533 | pthread_create() call in the creator thread |
| 534 | </para> |
| 535 | </listitem> |
| 536 | <listitem> |
| 537 | <para> |
| 538 | thread creation phase (stack and TLS setup) in the created thread |
| 539 | </para> |
| 540 | </listitem> |
| 541 | </itemizedlist> |
| 542 | </listitem> |
| 543 | </varlistentry> |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 544 | </variablelist> |
| 545 | <!-- end of xi:include in the manpage --> |
| 546 | |
| 547 | <!-- start of xi:include in the manpage --> |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 548 | <para> |
| 549 | The following options are available for monitoring the behavior of the |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 550 | client program: |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 551 | </para> |
| 552 | |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 553 | <variablelist id="drd.debugopts.list"> |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 554 | <varlistentry> |
| 555 | <term> |
| 556 | <option><![CDATA[--trace-addr=<address> [default: none]]]></option> |
| 557 | </term> |
| 558 | <listitem> |
| 559 | <para> |
| 560 | Trace all load and store activity for the specified |
| 561 | address. This option may be specified more than once. |
| 562 | </para> |
| 563 | </listitem> |
| 564 | </varlistentry> |
| 565 | <varlistentry> |
| 566 | <term> |
bart | 858c2d7 | 2012-06-16 18:51:16 +0000 | [diff] [blame] | 567 | <option><![CDATA[--ptrace-addr=<address> [default: none]]]></option> |
| 568 | </term> |
| 569 | <listitem> |
| 570 | <para> |
| 571 | Trace all load and store activity for the specified address and keep |
| 572 | doing that even after the memory at that address has been freed and |
| 573 | reallocated. |
| 574 | </para> |
| 575 | </listitem> |
| 576 | </varlistentry> |
| 577 | <varlistentry> |
| 578 | <term> |
bart | f9427fd | 2010-08-29 09:19:07 +0000 | [diff] [blame] | 579 | <option><![CDATA[--trace-alloc=<yes|no> [default: no]]]></option> |
| 580 | </term> |
| 581 | <listitem> |
| 582 | <para> |
| 583 | Trace all memory allocations and deallocations. May produce a huge |
| 584 | amount of output. |
| 585 | </para> |
| 586 | </listitem> |
| 587 | </varlistentry> |
| 588 | <varlistentry> |
| 589 | <term> |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 590 | <option><![CDATA[--trace-barrier=<yes|no> [default: no]]]></option> |
| 591 | </term> |
| 592 | <listitem> |
| 593 | <para> |
| 594 | Trace all barrier activity. |
| 595 | </para> |
| 596 | </listitem> |
| 597 | </varlistentry> |
| 598 | <varlistentry> |
| 599 | <term> |
| 600 | <option><![CDATA[--trace-cond=<yes|no> [default: no]]]></option> |
| 601 | </term> |
| 602 | <listitem> |
| 603 | <para> |
| 604 | Trace all condition variable activity. |
| 605 | </para> |
| 606 | </listitem> |
| 607 | </varlistentry> |
| 608 | <varlistentry> |
| 609 | <term> |
| 610 | <option><![CDATA[--trace-fork-join=<yes|no> [default: no]]]></option> |
| 611 | </term> |
| 612 | <listitem> |
| 613 | <para> |
| 614 | Trace all thread creation and all thread termination events. |
| 615 | </para> |
| 616 | </listitem> |
| 617 | </varlistentry> |
| 618 | <varlistentry> |
| 619 | <term> |
bart | 282e337 | 2011-10-13 18:50:15 +0000 | [diff] [blame] | 620 | <option><![CDATA[--trace-hb=<yes|no> [default: no]]]></option> |
| 621 | </term> |
| 622 | <listitem> |
| 623 | <para> |
| 624 | Trace execution of the <literal>ANNOTATE_HAPPENS_BEFORE()</literal>, |
| 625 | <literal>ANNOTATE_HAPPENS_AFTER()</literal> and |
| 626 | <literal>ANNOTATE_HAPPENS_DONE()</literal> client requests. |
| 627 | </para> |
| 628 | </listitem> |
| 629 | </varlistentry> |
| 630 | <varlistentry> |
| 631 | <term> |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 632 | <option><![CDATA[--trace-mutex=<yes|no> [default: no]]]></option> |
| 633 | </term> |
| 634 | <listitem> |
| 635 | <para> |
| 636 | Trace all mutex activity. |
| 637 | </para> |
| 638 | </listitem> |
| 639 | </varlistentry> |
| 640 | <varlistentry> |
| 641 | <term> |
| 642 | <option><![CDATA[--trace-rwlock=<yes|no> [default: no]]]></option> |
| 643 | </term> |
| 644 | <listitem> |
| 645 | <para> |
| 646 | Trace all reader-writer lock activity. |
| 647 | </para> |
| 648 | </listitem> |
| 649 | </varlistentry> |
| 650 | <varlistentry> |
| 651 | <term> |
| 652 | <option><![CDATA[--trace-semaphore=<yes|no> [default: no]]]></option> |
| 653 | </term> |
| 654 | <listitem> |
| 655 | <para> |
| 656 | Trace all semaphore activity. |
| 657 | </para> |
| 658 | </listitem> |
| 659 | </varlistentry> |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 660 | </variablelist> |
| 661 | <!-- end of xi:include in the manpage --> |
| 662 | |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 663 | </sect2> |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 664 | |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 665 | |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 666 | <sect2 id="drd-manual.data-races" xreflabel="Data Races"> |
bart | 88f1141 | 2008-07-03 07:08:04 +0000 | [diff] [blame] | 667 | <title>Detected Errors: Data Races</title> |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 668 | |
| 669 | <para> |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 670 | DRD prints a message every time it detects a data race. Please keep |
| 671 | the following in mind when interpreting DRD's output: |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 672 | <itemizedlist> |
| 673 | <listitem> |
| 674 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 675 | Every thread is assigned a <emphasis>thread ID</emphasis> by the DRD |
| 676 | tool. A thread ID is a number. Thread ID's start at one and are never |
| 677 | recycled. |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 678 | </para> |
| 679 | </listitem> |
| 680 | <listitem> |
| 681 | <para> |
| 682 | The term <emphasis>segment</emphasis> refers to a consecutive |
| 683 | sequence of load, store and synchronization operations, all |
| 684 | issued by the same thread. A segment always starts and ends at a |
| 685 | synchronization operation. Data race analysis is performed |
| 686 | between segments instead of between individual load and store |
| 687 | operations because of performance reasons. |
| 688 | </para> |
| 689 | </listitem> |
| 690 | <listitem> |
| 691 | <para> |
| 692 | There are always at least two memory accesses involved in a data |
| 693 | race. Memory accesses involved in a data race are called |
| 694 | <emphasis>conflicting memory accesses</emphasis>. DRD prints a |
| 695 | report for each memory access that conflicts with a past memory |
| 696 | access. |
| 697 | </para> |
| 698 | </listitem> |
| 699 | </itemizedlist> |
| 700 | </para> |
| 701 | |
| 702 | <para> |
| 703 | Below you can find an example of a message printed by DRD when it |
| 704 | detects a data race: |
| 705 | </para> |
| 706 | <programlisting><![CDATA[ |
bart | e2b9823 | 2009-07-22 18:13:21 +0000 | [diff] [blame] | 707 | $ valgrind --tool=drd --read-var-info=yes drd/tests/rwlock_race |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 708 | ... |
| 709 | ==9466== Thread 3: |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 710 | ==9466== Conflicting load by thread 3 at 0x006020b8 size 4 |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 711 | ==9466== at 0x400B6C: thread_func (rwlock_race.c:29) |
| 712 | ==9466== by 0x4C291DF: vg_thread_wrapper (drd_pthread_intercepts.c:186) |
| 713 | ==9466== by 0x4E3403F: start_thread (in /lib64/libpthread-2.8.so) |
| 714 | ==9466== by 0x53250CC: clone (in /lib64/libc-2.8.so) |
| 715 | ==9466== Location 0x6020b8 is 0 bytes inside local var "s_racy" |
| 716 | ==9466== declared at rwlock_race.c:18, in frame #0 of thread 3 |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 717 | ==9466== Other segment start (thread 2) |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 718 | ==9466== at 0x4C2847D: pthread_rwlock_rdlock* (drd_pthread_intercepts.c:813) |
| 719 | ==9466== by 0x400B6B: thread_func (rwlock_race.c:28) |
| 720 | ==9466== by 0x4C291DF: vg_thread_wrapper (drd_pthread_intercepts.c:186) |
| 721 | ==9466== by 0x4E3403F: start_thread (in /lib64/libpthread-2.8.so) |
| 722 | ==9466== by 0x53250CC: clone (in /lib64/libc-2.8.so) |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 723 | ==9466== Other segment end (thread 2) |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 724 | ==9466== at 0x4C28B54: pthread_rwlock_unlock* (drd_pthread_intercepts.c:912) |
| 725 | ==9466== by 0x400B84: thread_func (rwlock_race.c:30) |
| 726 | ==9466== by 0x4C291DF: vg_thread_wrapper (drd_pthread_intercepts.c:186) |
| 727 | ==9466== by 0x4E3403F: start_thread (in /lib64/libpthread-2.8.so) |
| 728 | ==9466== by 0x53250CC: clone (in /lib64/libc-2.8.so) |
| 729 | ... |
| 730 | ]]></programlisting> |
| 731 | |
| 732 | <para> |
| 733 | The above report has the following meaning: |
| 734 | <itemizedlist> |
| 735 | <listitem> |
| 736 | <para> |
| 737 | The number in the column on the left is the process ID of the |
| 738 | process being analyzed by DRD. |
| 739 | </para> |
| 740 | </listitem> |
| 741 | <listitem> |
| 742 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 743 | The first line ("Thread 3") tells you the thread ID for |
| 744 | the thread in which context the data race has been detected. |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 745 | </para> |
| 746 | </listitem> |
| 747 | <listitem> |
| 748 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 749 | The next line tells which kind of operation was performed (load or |
| 750 | store) and by which thread. On the same line the start address and the |
| 751 | number of bytes involved in the conflicting access are also displayed. |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 752 | </para> |
| 753 | </listitem> |
| 754 | <listitem> |
| 755 | <para> |
| 756 | Next, the call stack of the conflicting access is displayed. If |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 757 | your program has been compiled with debug information |
| 758 | (<option>-g</option>), this call stack will include file names and |
| 759 | line numbers. The two |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 760 | bottommost frames in this call stack (<function>clone</function> |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 761 | and <function>start_thread</function>) show how the NPTL starts |
| 762 | a thread. The third frame |
| 763 | (<function>vg_thread_wrapper</function>) is added by DRD. The |
| 764 | fourth frame (<function>thread_func</function>) is the first |
| 765 | interesting line because it shows the thread entry point, that |
| 766 | is the function that has been passed as the third argument to |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 767 | <function>pthread_create</function>. |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 768 | </para> |
| 769 | </listitem> |
| 770 | <listitem> |
| 771 | <para> |
| 772 | Next, the allocation context for the conflicting address is |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 773 | displayed. For dynamically allocated data the allocation call |
| 774 | stack is shown. For static variables and stack variables the |
| 775 | allocation context is only shown when the option |
njn | 7e5d4ed | 2009-07-30 02:57:52 +0000 | [diff] [blame] | 776 | <option>--read-var-info=yes</option> has been |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 777 | specified. Otherwise DRD will print <computeroutput>Allocation |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 778 | context: unknown</computeroutput>. |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 779 | </para> |
| 780 | </listitem> |
| 781 | <listitem> |
| 782 | <para> |
| 783 | A conflicting access involves at least two memory accesses. For |
| 784 | one of these accesses an exact call stack is displayed, and for |
| 785 | the other accesses an approximate call stack is displayed, |
| 786 | namely the start and the end of the segments of the other |
| 787 | accesses. This information can be interpreted as follows: |
| 788 | <orderedlist> |
| 789 | <listitem> |
| 790 | <para> |
| 791 | Start at the bottom of both call stacks, and count the |
| 792 | number stack frames with identical function name, file |
| 793 | name and line number. In the above example the three |
| 794 | bottommost frames are identical |
| 795 | (<function>clone</function>, |
| 796 | <function>start_thread</function> and |
| 797 | <function>vg_thread_wrapper</function>). |
| 798 | </para> |
| 799 | </listitem> |
| 800 | <listitem> |
| 801 | <para> |
| 802 | The next higher stack frame in both call stacks now tells |
| 803 | you between in which source code region the other memory |
| 804 | access happened. The above output tells that the other |
| 805 | memory access involved in the data race happened between |
| 806 | source code lines 28 and 30 in file |
| 807 | <computeroutput>rwlock_race.c</computeroutput>. |
| 808 | </para> |
| 809 | </listitem> |
| 810 | </orderedlist> |
| 811 | </para> |
| 812 | </listitem> |
| 813 | </itemizedlist> |
| 814 | </para> |
| 815 | |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 816 | </sect2> |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 817 | |
| 818 | |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 819 | <sect2 id="drd-manual.lock-contention" xreflabel="Lock Contention"> |
bart | 88f1141 | 2008-07-03 07:08:04 +0000 | [diff] [blame] | 820 | <title>Detected Errors: Lock Contention</title> |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 821 | |
| 822 | <para> |
bart | a617d11 | 2009-07-27 17:43:39 +0000 | [diff] [blame] | 823 | Threads must be able to make progress without being blocked for too long by |
| 824 | other threads. Sometimes a thread has to wait until a mutex or reader-writer |
| 825 | synchronization object is unlocked by another thread. This is called |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 826 | <emphasis>lock contention</emphasis>. |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 827 | </para> |
| 828 | |
| 829 | <para> |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 830 | Lock contention causes delays. Such delays should be as short as |
| 831 | possible. The two command line options |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 832 | <literal>--exclusive-threshold=<n></literal> and |
| 833 | <literal>--shared-threshold=<n></literal> make it possible to |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 834 | detect excessive lock contention by making DRD report any lock that |
| 835 | has been held longer than the specified threshold. An example: |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 836 | </para> |
| 837 | <programlisting><![CDATA[ |
bart | ef1b972 | 2008-07-04 15:34:23 +0000 | [diff] [blame] | 838 | $ valgrind --tool=drd --exclusive-threshold=10 drd/tests/hold_lock -i 500 |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 839 | ... |
| 840 | ==10668== Acquired at: |
| 841 | ==10668== at 0x4C267C8: pthread_mutex_lock (drd_pthread_intercepts.c:395) |
| 842 | ==10668== by 0x400D92: main (hold_lock.c:51) |
| 843 | ==10668== Lock on mutex 0x7fefffd50 was held during 503 ms (threshold: 10 ms). |
| 844 | ==10668== at 0x4C26ADA: pthread_mutex_unlock (drd_pthread_intercepts.c:441) |
| 845 | ==10668== by 0x400DB5: main (hold_lock.c:55) |
| 846 | ... |
| 847 | ]]></programlisting> |
| 848 | |
| 849 | <para> |
| 850 | The <literal>hold_lock</literal> test program holds a lock as long as |
| 851 | specified by the <literal>-i</literal> (interval) argument. The DRD |
| 852 | output reports that the lock acquired at line 51 in source file |
| 853 | <literal>hold_lock.c</literal> and released at line 55 was held during |
| 854 | 503 ms, while a threshold of 10 ms was specified to DRD. |
| 855 | </para> |
| 856 | |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 857 | </sect2> |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 858 | |
| 859 | |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 860 | <sect2 id="drd-manual.api-checks" xreflabel="API Checks"> |
bart | 88f1141 | 2008-07-03 07:08:04 +0000 | [diff] [blame] | 861 | <title>Detected Errors: Misuse of the POSIX threads API</title> |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 862 | |
| 863 | <para> |
| 864 | DRD is able to detect and report the following misuses of the POSIX |
| 865 | threads API: |
| 866 | <itemizedlist> |
| 867 | <listitem> |
| 868 | <para> |
| 869 | Passing the address of one type of synchronization object |
| 870 | (e.g. a mutex) to a POSIX API call that expects a pointer to |
| 871 | another type of synchronization object (e.g. a condition |
| 872 | variable). |
| 873 | </para> |
| 874 | </listitem> |
| 875 | <listitem> |
| 876 | <para> |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 877 | Attempts to unlock a mutex that has not been locked. |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 878 | </para> |
| 879 | </listitem> |
| 880 | <listitem> |
| 881 | <para> |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 882 | Attempts to unlock a mutex that was locked by another thread. |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 883 | </para> |
| 884 | </listitem> |
| 885 | <listitem> |
| 886 | <para> |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 887 | Attempts to lock a mutex of type |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 888 | <literal>PTHREAD_MUTEX_NORMAL</literal> or a spinlock |
| 889 | recursively. |
| 890 | </para> |
| 891 | </listitem> |
| 892 | <listitem> |
| 893 | <para> |
| 894 | Destruction or deallocation of a locked mutex. |
| 895 | </para> |
| 896 | </listitem> |
| 897 | <listitem> |
| 898 | <para> |
| 899 | Sending a signal to a condition variable while no lock is held |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 900 | on the mutex associated with the condition variable. |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 901 | </para> |
| 902 | </listitem> |
| 903 | <listitem> |
| 904 | <para> |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 905 | Calling <function>pthread_cond_wait</function> on a mutex |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 906 | that is not locked, that is locked by another thread or that |
| 907 | has been locked recursively. |
| 908 | </para> |
| 909 | </listitem> |
| 910 | <listitem> |
| 911 | <para> |
| 912 | Associating two different mutexes with a condition variable |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 913 | through <function>pthread_cond_wait</function>. |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 914 | </para> |
| 915 | </listitem> |
| 916 | <listitem> |
| 917 | <para> |
| 918 | Destruction or deallocation of a condition variable that is |
| 919 | being waited upon. |
| 920 | </para> |
| 921 | </listitem> |
| 922 | <listitem> |
| 923 | <para> |
bart | a617d11 | 2009-07-27 17:43:39 +0000 | [diff] [blame] | 924 | Destruction or deallocation of a locked reader-writer synchronization |
| 925 | object. |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 926 | </para> |
| 927 | </listitem> |
| 928 | <listitem> |
| 929 | <para> |
bart | a617d11 | 2009-07-27 17:43:39 +0000 | [diff] [blame] | 930 | Attempts to unlock a reader-writer synchronization object that was not |
| 931 | locked by the calling thread. |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 932 | </para> |
| 933 | </listitem> |
| 934 | <listitem> |
| 935 | <para> |
bart | a617d11 | 2009-07-27 17:43:39 +0000 | [diff] [blame] | 936 | Attempts to recursively lock a reader-writer synchronization object |
| 937 | exclusively. |
| 938 | </para> |
| 939 | </listitem> |
| 940 | <listitem> |
| 941 | <para> |
| 942 | Attempts to pass the address of a user-defined reader-writer |
| 943 | synchronization object to a POSIX threads function. |
| 944 | </para> |
| 945 | </listitem> |
| 946 | <listitem> |
| 947 | <para> |
| 948 | Attempts to pass the address of a POSIX reader-writer synchronization |
| 949 | object to one of the annotations for user-defined reader-writer |
| 950 | synchronization objects. |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 951 | </para> |
| 952 | </listitem> |
| 953 | <listitem> |
| 954 | <para> |
| 955 | Reinitialization of a mutex, condition variable, reader-writer |
| 956 | lock, semaphore or barrier. |
| 957 | </para> |
| 958 | </listitem> |
| 959 | <listitem> |
| 960 | <para> |
| 961 | Destruction or deallocation of a semaphore or barrier that is |
| 962 | being waited upon. |
| 963 | </para> |
| 964 | </listitem> |
| 965 | <listitem> |
| 966 | <para> |
bart | 776a91e | 2009-02-22 09:29:07 +0000 | [diff] [blame] | 967 | Missing synchronization between barrier wait and barrier destruction. |
| 968 | </para> |
| 969 | </listitem> |
| 970 | <listitem> |
| 971 | <para> |
bart | a617d11 | 2009-07-27 17:43:39 +0000 | [diff] [blame] | 972 | Exiting a thread without first unlocking the spinlocks, mutexes or |
| 973 | reader-writer synchronization objects that were locked by that thread. |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 974 | </para> |
| 975 | </listitem> |
bart | 291bb5e | 2009-08-15 13:31:41 +0000 | [diff] [blame] | 976 | <listitem> |
| 977 | <para> |
| 978 | Passing an invalid thread ID to <function>pthread_join</function> |
| 979 | or <function>pthread_cancel</function>. |
| 980 | </para> |
| 981 | </listitem> |
bart | 8f0b0d7 | 2008-06-28 16:47:22 +0000 | [diff] [blame] | 982 | </itemizedlist> |
| 983 | </para> |
| 984 | |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 985 | </sect2> |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 986 | |
| 987 | |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 988 | <sect2 id="drd-manual.clientreqs" xreflabel="Client requests"> |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 989 | <title>Client Requests</title> |
| 990 | |
| 991 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 992 | Just as for other Valgrind tools it is possible to let a client program |
| 993 | interact with the DRD tool through client requests. In addition to the |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 994 | client requests several macros have been defined that allow to use the |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 995 | client requests in a convenient way. |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 996 | </para> |
| 997 | |
| 998 | <para> |
| 999 | The interface between client programs and the DRD tool is defined in |
| 1000 | the header file <literal><valgrind/drd.h></literal>. The |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 1001 | available macros and client requests are: |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1002 | <itemizedlist> |
| 1003 | <listitem> |
| 1004 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1005 | The macro <literal>DRD_GET_VALGRIND_THREADID</literal> and the |
| 1006 | corresponding client |
| 1007 | request <varname>VG_USERREQ__DRD_GET_VALGRIND_THREAD_ID</varname>. |
| 1008 | Query the thread ID that has been assigned by the Valgrind core to the |
| 1009 | thread executing this client request. Valgrind's thread ID's start at |
| 1010 | one and are recycled in case a thread stops. |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1011 | </para> |
| 1012 | </listitem> |
| 1013 | <listitem> |
| 1014 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1015 | The macro <literal>DRD_GET_DRD_THREADID</literal> and the corresponding |
| 1016 | client request <varname>VG_USERREQ__DRD_GET_DRD_THREAD_ID</varname>. |
| 1017 | Query the thread ID that has been assigned by DRD to the thread |
| 1018 | executing this client request. These are the thread ID's reported by DRD |
| 1019 | in data race reports and in trace messages. DRD's thread ID's start at |
| 1020 | one and are never recycled. |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1021 | </para> |
| 1022 | </listitem> |
| 1023 | <listitem> |
| 1024 | <para> |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 1025 | The macros <literal>DRD_IGNORE_VAR(x)</literal>, |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1026 | <literal>ANNOTATE_TRACE_MEMORY(&x)</literal> and the corresponding |
| 1027 | client request <varname>VG_USERREQ__DRD_START_SUPPRESSION</varname>. Some |
| 1028 | applications contain intentional races. There exist e.g. applications |
| 1029 | where the same value is assigned to a shared variable from two different |
| 1030 | threads. It may be more convenient to suppress such races than to solve |
| 1031 | these. This client request allows to suppress such races. |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1032 | </para> |
| 1033 | </listitem> |
| 1034 | <listitem> |
| 1035 | <para> |
bart | 07ec593 | 2009-07-26 15:58:25 +0000 | [diff] [blame] | 1036 | The macro <literal>DRD_STOP_IGNORING_VAR(x)</literal> and the |
| 1037 | corresponding client request |
| 1038 | <varname>VG_USERREQ__DRD_FINISH_SUPPRESSION</varname>. Tell DRD |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1039 | to no longer ignore data races for the address range that was suppressed |
bart | 07ec593 | 2009-07-26 15:58:25 +0000 | [diff] [blame] | 1040 | either via the macro <literal>DRD_IGNORE_VAR(x)</literal> or via the |
| 1041 | client request <varname>VG_USERREQ__DRD_START_SUPPRESSION</varname>. |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1042 | </para> |
| 1043 | </listitem> |
| 1044 | <listitem> |
| 1045 | <para> |
bart | 3f27c8c | 2009-12-10 17:58:46 +0000 | [diff] [blame] | 1046 | The macro <literal>DRD_TRACE_VAR(x)</literal>. Trace all load and store |
| 1047 | activity for the address range starting at <literal>&x</literal> and |
| 1048 | occupying <literal>sizeof(x)</literal> bytes. When DRD reports a data |
| 1049 | race on a specified variable, and it's not immediately clear which |
| 1050 | source code statements triggered the conflicting accesses, it can be |
| 1051 | very helpful to trace all activity on the offending memory location. |
| 1052 | </para> |
| 1053 | </listitem> |
| 1054 | <listitem> |
| 1055 | <para> |
bart | 858c2d7 | 2012-06-16 18:51:16 +0000 | [diff] [blame] | 1056 | The macro <literal>DRD_STOP_TRACING_VAR(x)</literal>. Stop tracing load |
| 1057 | and store activity for the address range starting |
| 1058 | at <literal>&x</literal> and occupying <literal>sizeof(x)</literal> |
| 1059 | bytes. |
| 1060 | </para> |
| 1061 | </listitem> |
| 1062 | <listitem> |
| 1063 | <para> |
bart | 3f27c8c | 2009-12-10 17:58:46 +0000 | [diff] [blame] | 1064 | The macro <literal>ANNOTATE_TRACE_MEMORY(&x)</literal>. Trace all |
| 1065 | load and store activity that touches at least the single byte at the |
| 1066 | address <literal>&x</literal>. |
| 1067 | </para> |
| 1068 | </listitem> |
| 1069 | <listitem> |
| 1070 | <para> |
| 1071 | The client request <varname>VG_USERREQ__DRD_START_TRACE_ADDR</varname>, |
| 1072 | which allows to trace all load and store activity for the specified |
| 1073 | address range. |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1074 | </para> |
| 1075 | </listitem> |
| 1076 | <listitem> |
| 1077 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1078 | The client |
| 1079 | request <varname>VG_USERREQ__DRD_STOP_TRACE_ADDR</varname>. Do no longer |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1080 | trace load and store activity for the specified address range. |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1081 | </para> |
| 1082 | </listitem> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1083 | <listitem> |
| 1084 | <para> |
| 1085 | The macro <literal>ANNOTATE_HAPPENS_BEFORE(addr)</literal> tells DRD to |
| 1086 | insert a mark. Insert this macro just after an access to the variable at |
| 1087 | the specified address has been performed. |
| 1088 | </para> |
| 1089 | </listitem> |
| 1090 | <listitem> |
| 1091 | <para> |
| 1092 | The macro <literal>ANNOTATE_HAPPENS_AFTER(addr)</literal> tells DRD that |
| 1093 | the next access to the variable at the specified address should be |
| 1094 | considered to have happened after the access just before the latest |
| 1095 | <literal>ANNOTATE_HAPPENS_BEFORE(addr)</literal> annotation that |
bart | 18f734b | 2010-10-10 18:57:53 +0000 | [diff] [blame] | 1096 | references the same variable. The purpose of these two macros is to tell |
| 1097 | DRD about the order of inter-thread memory accesses implemented via |
| 1098 | atomic memory operations. See |
| 1099 | also <literal>drd/tests/annotate_smart_pointer.cpp</literal> for an |
| 1100 | example. |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1101 | </para> |
| 1102 | </listitem> |
| 1103 | <listitem> |
| 1104 | <para> |
| 1105 | The macro <literal>ANNOTATE_RWLOCK_CREATE(rwlock)</literal> tells DRD |
| 1106 | that the object at address <literal>rwlock</literal> is a |
| 1107 | reader-writer synchronization object that is not a |
bart | 18f734b | 2010-10-10 18:57:53 +0000 | [diff] [blame] | 1108 | <literal>pthread_rwlock_t</literal> synchronization object. See |
| 1109 | also <literal>drd/tests/annotate_rwlock.c</literal> for an example. |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1110 | </para> |
| 1111 | </listitem> |
| 1112 | <listitem> |
| 1113 | <para> |
| 1114 | The macro <literal>ANNOTATE_RWLOCK_DESTROY(rwlock)</literal> tells DRD |
| 1115 | that the reader-writer synchronization object at |
| 1116 | address <literal>rwlock</literal> has been destroyed. |
| 1117 | </para> |
| 1118 | </listitem> |
| 1119 | <listitem> |
| 1120 | <para> |
| 1121 | The macro <literal>ANNOTATE_WRITERLOCK_ACQUIRED(rwlock)</literal> tells |
| 1122 | DRD that a writer lock has been acquired on the reader-writer |
| 1123 | synchronization object at address <literal>rwlock</literal>. |
| 1124 | </para> |
| 1125 | </listitem> |
| 1126 | <listitem> |
| 1127 | <para> |
| 1128 | The macro <literal>ANNOTATE_READERLOCK_ACQUIRED(rwlock)</literal> tells |
| 1129 | DRD that a reader lock has been acquired on the reader-writer |
| 1130 | synchronization object at address <literal>rwlock</literal>. |
| 1131 | </para> |
| 1132 | </listitem> |
| 1133 | <listitem> |
| 1134 | <para> |
| 1135 | The macro <literal>ANNOTATE_RWLOCK_ACQUIRED(rwlock, is_w)</literal> |
| 1136 | tells DRD that a writer lock (when <literal>is_w != 0</literal>) or that |
| 1137 | a reader lock (when <literal>is_w == 0</literal>) has been acquired on |
| 1138 | the reader-writer synchronization object at |
| 1139 | address <literal>rwlock</literal>. |
| 1140 | </para> |
| 1141 | </listitem> |
| 1142 | <listitem> |
| 1143 | <para> |
| 1144 | The macro <literal>ANNOTATE_WRITERLOCK_RELEASED(rwlock)</literal> tells |
| 1145 | DRD that a writer lock has been released on the reader-writer |
| 1146 | synchronization object at address <literal>rwlock</literal>. |
| 1147 | </para> |
| 1148 | </listitem> |
| 1149 | <listitem> |
| 1150 | <para> |
| 1151 | The macro <literal>ANNOTATE_READERLOCK_RELEASED(rwlock)</literal> tells |
| 1152 | DRD that a reader lock has been released on the reader-writer |
| 1153 | synchronization object at address <literal>rwlock</literal>. |
| 1154 | </para> |
| 1155 | </listitem> |
| 1156 | <listitem> |
| 1157 | <para> |
| 1158 | The macro <literal>ANNOTATE_RWLOCK_RELEASED(rwlock, is_w)</literal> |
| 1159 | tells DRD that a writer lock (when <literal>is_w != 0</literal>) or that |
| 1160 | a reader lock (when <literal>is_w == 0</literal>) has been released on |
| 1161 | the reader-writer synchronization object at |
| 1162 | address <literal>rwlock</literal>. |
| 1163 | </para> |
| 1164 | </listitem> |
| 1165 | <listitem> |
| 1166 | <para> |
bart | 18f734b | 2010-10-10 18:57:53 +0000 | [diff] [blame] | 1167 | The macro <literal>ANNOTATE_BARRIER_INIT(barrier, count, |
| 1168 | reinitialization_allowed)</literal> tells DRD that a new barrier object |
| 1169 | at the address <literal>barrier</literal> has been initialized, |
| 1170 | that <literal>count</literal> threads participate in each barrier and |
| 1171 | also whether or not barrier reinitialization without intervening |
| 1172 | destruction should be reported as an error. See |
| 1173 | also <literal>drd/tests/annotate_barrier.c</literal> for an example. |
| 1174 | </para> |
| 1175 | </listitem> |
| 1176 | <listitem> |
| 1177 | <para> |
| 1178 | The macro <literal>ANNOTATE_BARRIER_DESTROY(barrier)</literal> |
| 1179 | tells DRD that a barrier object is about to be destroyed. |
| 1180 | </para> |
| 1181 | </listitem> |
| 1182 | <listitem> |
| 1183 | <para> |
| 1184 | The macro <literal>ANNOTATE_BARRIER_WAIT_BEFORE(barrier)</literal> |
| 1185 | tells DRD that waiting for a barrier will start. |
| 1186 | </para> |
| 1187 | </listitem> |
| 1188 | <listitem> |
| 1189 | <para> |
| 1190 | The macro <literal>ANNOTATE_BARRIER_WAIT_AFTER(barrier)</literal> |
| 1191 | tells DRD that waiting for a barrier has finished. |
| 1192 | </para> |
| 1193 | </listitem> |
| 1194 | <listitem> |
| 1195 | <para> |
| 1196 | The macro <literal>ANNOTATE_BENIGN_RACE_SIZED(addr, size, |
| 1197 | descr)</literal> tells DRD that any races detected on the specified |
| 1198 | address are benign and hence should not be |
| 1199 | reported. The <literal>descr</literal> argument is ignored but can be |
| 1200 | used to document why data races on <literal>addr</literal> are benign. |
| 1201 | </para> |
| 1202 | </listitem> |
| 1203 | <listitem> |
| 1204 | <para> |
| 1205 | The macro <literal>ANNOTATE_BENIGN_RACE_STATIC(var, descr)</literal> |
| 1206 | tells DRD that any races detected on the specified static variable are |
| 1207 | benign and hence should not be reported. The <literal>descr</literal> |
| 1208 | argument is ignored but can be used to document why data races |
| 1209 | on <literal>var</literal> are benign. Note: this macro can only be |
| 1210 | used in C++ programs and not in C programs. |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1211 | </para> |
| 1212 | </listitem> |
| 1213 | <listitem> |
| 1214 | <para> |
| 1215 | The macro <literal>ANNOTATE_IGNORE_READS_BEGIN</literal> tells |
| 1216 | DRD to ignore all memory loads performed by the current thread. |
| 1217 | </para> |
| 1218 | </listitem> |
| 1219 | <listitem> |
| 1220 | <para> |
| 1221 | The macro <literal>ANNOTATE_IGNORE_READS_END</literal> tells |
| 1222 | DRD to stop ignoring the memory loads performed by the current thread. |
| 1223 | </para> |
| 1224 | </listitem> |
| 1225 | <listitem> |
| 1226 | <para> |
| 1227 | The macro <literal>ANNOTATE_IGNORE_WRITES_BEGIN</literal> tells |
| 1228 | DRD to ignore all memory stores performed by the current thread. |
| 1229 | </para> |
| 1230 | </listitem> |
| 1231 | <listitem> |
| 1232 | <para> |
| 1233 | The macro <literal>ANNOTATE_IGNORE_WRITES_END</literal> tells |
| 1234 | DRD to stop ignoring the memory stores performed by the current thread. |
| 1235 | </para> |
| 1236 | </listitem> |
| 1237 | <listitem> |
| 1238 | <para> |
| 1239 | The macro <literal>ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN</literal> tells |
| 1240 | DRD to ignore all memory accesses performed by the current thread. |
| 1241 | </para> |
| 1242 | </listitem> |
| 1243 | <listitem> |
| 1244 | <para> |
| 1245 | The macro <literal>ANNOTATE_IGNORE_READS_AND_WRITES_END</literal> tells |
| 1246 | DRD to stop ignoring the memory accesses performed by the current thread. |
| 1247 | </para> |
| 1248 | </listitem> |
| 1249 | <listitem> |
| 1250 | <para> |
| 1251 | The macro <literal>ANNOTATE_NEW_MEMORY(addr, size)</literal> tells |
| 1252 | DRD that the specified memory range has been allocated by a custom |
| 1253 | memory allocator in the client program and that the client program |
| 1254 | will start using this memory range. |
| 1255 | </para> |
| 1256 | </listitem> |
| 1257 | <listitem> |
| 1258 | <para> |
| 1259 | The macro <literal>ANNOTATE_THREAD_NAME(name)</literal> tells DRD to |
| 1260 | associate the specified name with the current thread and to include this |
| 1261 | name in the error messages printed by DRD. |
| 1262 | </para> |
| 1263 | </listitem> |
njn | f0f9037 | 2009-08-10 01:34:27 +0000 | [diff] [blame] | 1264 | <listitem> |
| 1265 | <para> |
| 1266 | The macros <literal>VALGRIND_MALLOCLIKE_BLOCK</literal> and |
| 1267 | <literal>VALGRIND_FREELIKE_BLOCK</literal> from the Valgrind core are |
| 1268 | implemented; they are described in |
| 1269 | <xref linkend="manual-core-adv.clientreq"/>. |
| 1270 | </para> |
| 1271 | </listitem> |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1272 | </itemizedlist> |
| 1273 | </para> |
| 1274 | |
| 1275 | <para> |
| 1276 | Note: if you compiled Valgrind yourself, the header file |
| 1277 | <literal><valgrind/drd.h></literal> will have been installed in |
| 1278 | the directory <literal>/usr/include</literal> by the command |
| 1279 | <literal>make install</literal>. If you obtained Valgrind by |
| 1280 | installing it as a package however, you will probably have to install |
| 1281 | another package with a name like <literal>valgrind-devel</literal> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1282 | before Valgrind's header files are available. |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 1283 | </para> |
| 1284 | |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 1285 | </sect2> |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 1286 | |
| 1287 | |
bart | 8bad1f3 | 2014-06-06 07:23:06 +0000 | [diff] [blame] | 1288 | <sect2 id="drd-manual.C++11" xreflabel="C++11"> |
| 1289 | <title>Debugging C++11 Programs</title> |
| 1290 | |
bart | 5a3b2a4 | 2014-06-07 13:16:24 +0000 | [diff] [blame] | 1291 | <para>If you want to use the C++11 class std::thread you will need to do the |
| 1292 | following to annotate the std::shared_ptr<> objects used in the |
| 1293 | implementation of that class: |
| 1294 | <itemizedlist> |
| 1295 | <listitem> |
| 1296 | <para>Add the following code at the start of a common header or at the |
| 1297 | start of each source file, before any C++ header files are included:</para> |
| 1298 | <programlisting> |
bart | 8bad1f3 | 2014-06-06 07:23:06 +0000 | [diff] [blame] | 1299 | #include <valgrind/drd.h> |
| 1300 | #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE(addr) ANNOTATE_HAPPENS_BEFORE(addr) |
| 1301 | #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER(addr) ANNOTATE_HAPPENS_AFTER(addr) |
bart | 8bad1f3 | 2014-06-06 07:23:06 +0000 | [diff] [blame] | 1302 | </programlisting> |
bart | 5a3b2a4 | 2014-06-07 13:16:24 +0000 | [diff] [blame] | 1303 | </listitem> |
| 1304 | <listitem> |
| 1305 | <para>Download the gcc source code and from source file |
| 1306 | libstdc++-v3/src/c++11/thread.cc copy the implementation of the |
| 1307 | <computeroutput>execute_native_thread_routine()</computeroutput> |
| 1308 | and <computeroutput>std::thread::_M_start_thread()</computeroutput> |
| 1309 | functions into a source file that is linked with your application. Make |
| 1310 | sure that also in this source file the |
| 1311 | _GLIBCXX_SYNCHRONIZATION_HAPPENS_*() macros are defined properly.</para> |
| 1312 | </listitem> |
| 1313 | </itemizedlist> |
| 1314 | </para> |
| 1315 | <para>For more information, see also <emphasis>The |
bart | 8bad1f3 | 2014-06-06 07:23:06 +0000 | [diff] [blame] | 1316 | GNU C++ Library Manual, Debugging Support</emphasis> |
bart | de9b485 | 2014-09-06 06:23:15 +0000 | [diff] [blame] | 1317 | (<ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/manual/debug.html">http://gcc.gnu.org/onlinedocs/libstdc++/manual/debug.html</ulink>).</para> |
bart | 8bad1f3 | 2014-06-06 07:23:06 +0000 | [diff] [blame] | 1318 | |
| 1319 | </sect2> |
| 1320 | |
| 1321 | |
bart | 9ab8cac | 2008-07-07 18:38:17 +0000 | [diff] [blame] | 1322 | <sect2 id="drd-manual.gnome" xreflabel="GNOME"> |
bart | 76ca62c | 2008-12-17 19:10:06 +0000 | [diff] [blame] | 1323 | <title>Debugging GNOME Programs</title> |
bart | 9ab8cac | 2008-07-07 18:38:17 +0000 | [diff] [blame] | 1324 | |
| 1325 | <para> |
| 1326 | GNOME applications use the threading primitives provided by the |
bart | e2624a9 | 2008-07-28 14:55:38 +0000 | [diff] [blame] | 1327 | <computeroutput>glib</computeroutput> and |
| 1328 | <computeroutput>gthread</computeroutput> libraries. These libraries |
| 1329 | are built on top of POSIX threads, and hence are directly supported by |
| 1330 | DRD. Please keep in mind that you have to call |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 1331 | <function>g_thread_init</function> before creating any threads, or |
bart | e2624a9 | 2008-07-28 14:55:38 +0000 | [diff] [blame] | 1332 | DRD will report several data races on glib functions. See also the |
| 1333 | <ulink |
| 1334 | url="http://library.gnome.org/devel/glib/stable/glib-Threads.html">GLib |
| 1335 | Reference Manual</ulink> for more information about |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 1336 | <function>g_thread_init</function>. |
bart | 9ab8cac | 2008-07-07 18:38:17 +0000 | [diff] [blame] | 1337 | </para> |
| 1338 | |
bart | 39cf268 | 2008-07-10 06:27:52 +0000 | [diff] [blame] | 1339 | <para> |
| 1340 | One of the many facilities provided by the <literal>glib</literal> |
| 1341 | library is a block allocator, called <literal>g_slice</literal>. You |
| 1342 | have to disable this block allocator when using DRD by adding the |
| 1343 | following to the shell environment variables: |
| 1344 | <literal>G_SLICE=always-malloc</literal>. See also the <ulink |
| 1345 | url="http://library.gnome.org/devel/glib/stable/glib-Memory-Slices.html">GLib |
| 1346 | Reference Manual</ulink> for more information. |
| 1347 | </para> |
| 1348 | |
bart | 9ab8cac | 2008-07-07 18:38:17 +0000 | [diff] [blame] | 1349 | </sect2> |
| 1350 | |
| 1351 | |
bart | 76ca62c | 2008-12-17 19:10:06 +0000 | [diff] [blame] | 1352 | <sect2 id="drd-manual.boost.thread" xreflabel="Boost.Thread"> |
| 1353 | <title>Debugging Boost.Thread Programs</title> |
| 1354 | |
| 1355 | <para> |
bart | c57312c | 2008-12-17 19:15:58 +0000 | [diff] [blame] | 1356 | The Boost.Thread library is the threading library included with the |
| 1357 | cross-platform Boost Libraries. This threading library is an early |
| 1358 | implementation of the upcoming C++0x threading library. |
| 1359 | </para> |
| 1360 | |
| 1361 | <para> |
| 1362 | Applications that use the Boost.Thread library should run fine under DRD. |
bart | 76ca62c | 2008-12-17 19:10:06 +0000 | [diff] [blame] | 1363 | </para> |
| 1364 | |
| 1365 | <para> |
| 1366 | More information about Boost.Thread can be found here: |
| 1367 | <itemizedlist> |
| 1368 | <listitem> |
| 1369 | <para> |
| 1370 | Anthony Williams, <ulink |
| 1371 | url="http://www.boost.org/doc/libs/1_37_0/doc/html/thread.html">Boost.Thread</ulink> |
| 1372 | Library Documentation, Boost website, 2007. |
| 1373 | </para> |
| 1374 | </listitem> |
| 1375 | <listitem> |
| 1376 | <para> |
| 1377 | Anthony Williams, <ulink |
| 1378 | url="http://www.ddj.com/cpp/211600441">What's New in Boost |
| 1379 | Threads?</ulink>, Recent changes to the Boost Thread library, |
| 1380 | Dr. Dobbs Magazine, October 2008. |
| 1381 | </para> |
| 1382 | </listitem> |
| 1383 | </itemizedlist> |
| 1384 | </para> |
| 1385 | |
| 1386 | </sect2> |
| 1387 | |
| 1388 | |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 1389 | <sect2 id="drd-manual.openmp" xreflabel="OpenMP"> |
bart | 76ca62c | 2008-12-17 19:10:06 +0000 | [diff] [blame] | 1390 | <title>Debugging OpenMP Programs</title> |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 1391 | |
| 1392 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1393 | OpenMP stands for <emphasis>Open Multi-Processing</emphasis>. The OpenMP |
| 1394 | standard consists of a set of compiler directives for C, C++ and Fortran |
| 1395 | programs that allows a compiler to transform a sequential program into a |
| 1396 | parallel program. OpenMP is well suited for HPC applications and allows to |
| 1397 | work at a higher level compared to direct use of the POSIX threads API. While |
| 1398 | OpenMP ensures that the POSIX API is used correctly, OpenMP programs can still |
| 1399 | contain data races. So it definitely makes sense to verify OpenMP programs |
| 1400 | with a thread checking tool. |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1401 | </para> |
| 1402 | |
| 1403 | <para> |
njn | 7316df2 | 2009-08-04 01:16:01 +0000 | [diff] [blame] | 1404 | DRD supports OpenMP shared-memory programs generated by GCC. GCC |
| 1405 | supports OpenMP since version 4.2.0. GCC's runtime support |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1406 | for OpenMP programs is provided by a library called |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1407 | <literal>libgomp</literal>. The synchronization primitives implemented |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1408 | in this library use Linux' futex system call directly, unless the |
| 1409 | library has been configured with the |
njn | a331164 | 2009-08-10 01:29:14 +0000 | [diff] [blame] | 1410 | <literal>--disable-linux-futex</literal> option. DRD only supports |
| 1411 | libgomp libraries that have been configured with this option and in |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1412 | which symbol information is present. For most Linux distributions this |
njn | 7316df2 | 2009-08-04 01:16:01 +0000 | [diff] [blame] | 1413 | means that you will have to recompile GCC. See also the script |
bart | ef1b972 | 2008-07-04 15:34:23 +0000 | [diff] [blame] | 1414 | <literal>drd/scripts/download-and-build-gcc</literal> in the |
njn | 7316df2 | 2009-08-04 01:16:01 +0000 | [diff] [blame] | 1415 | Valgrind source tree for an example of how to compile GCC. You will |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1416 | also have to make sure that the newly compiled |
| 1417 | <literal>libgomp.so</literal> library is loaded when OpenMP programs |
| 1418 | are started. This is possible by adding a line similar to the |
| 1419 | following to your shell startup script: |
| 1420 | </para> |
| 1421 | <programlisting><![CDATA[ |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1422 | export LD_LIBRARY_PATH=~/gcc-4.4.0/lib64:~/gcc-4.4.0/lib: |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1423 | ]]></programlisting> |
| 1424 | |
| 1425 | <para> |
| 1426 | As an example, the test OpenMP test program |
bart | 66ba8c0 | 2008-10-11 18:28:12 +0000 | [diff] [blame] | 1427 | <literal>drd/tests/omp_matinv</literal> triggers a data race |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1428 | when the option -r has been specified on the command line. The data |
| 1429 | race is triggered by the following code: |
| 1430 | </para> |
| 1431 | <programlisting><![CDATA[ |
| 1432 | #pragma omp parallel for private(j) |
| 1433 | for (j = 0; j < rows; j++) |
| 1434 | { |
| 1435 | if (i != j) |
| 1436 | { |
| 1437 | const elem_t factor = a[j * cols + i]; |
| 1438 | for (k = 0; k < cols; k++) |
| 1439 | { |
| 1440 | a[j * cols + k] -= a[i * cols + k] * factor; |
| 1441 | } |
| 1442 | } |
| 1443 | } |
| 1444 | ]]></programlisting> |
| 1445 | |
| 1446 | <para> |
| 1447 | The above code is racy because the variable <literal>k</literal> has |
| 1448 | not been declared private. DRD will print the following error message |
| 1449 | for the above code: |
| 1450 | </para> |
| 1451 | <programlisting><![CDATA[ |
bart | e2b9823 | 2009-07-22 18:13:21 +0000 | [diff] [blame] | 1452 | $ valgrind --tool=drd --check-stack-var=yes --read-var-info=yes drd/tests/omp_matinv 3 -t 2 -r |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1453 | ... |
| 1454 | Conflicting store by thread 1/1 at 0x7fefffbc4 size 4 |
| 1455 | at 0x4014A0: gj.omp_fn.0 (omp_matinv.c:203) |
| 1456 | by 0x401211: gj (omp_matinv.c:159) |
| 1457 | by 0x40166A: invert_matrix (omp_matinv.c:238) |
| 1458 | by 0x4019B4: main (omp_matinv.c:316) |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1459 | Location 0x7fefffbc4 is 0 bytes inside local var "k" |
| 1460 | declared at omp_matinv.c:160, in frame #0 of thread 1 |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1461 | ... |
| 1462 | ]]></programlisting> |
| 1463 | <para> |
| 1464 | In the above output the function name <function>gj.omp_fn.0</function> |
njn | 7316df2 | 2009-08-04 01:16:01 +0000 | [diff] [blame] | 1465 | has been generated by GCC from the function name |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1466 | <function>gj</function>. The allocation context information shows that the |
| 1467 | data race has been caused by modifying the variable <literal>k</literal>. |
bart | 1e7f278 | 2008-07-01 13:43:44 +0000 | [diff] [blame] | 1468 | </para> |
| 1469 | |
| 1470 | <para> |
njn | 7316df2 | 2009-08-04 01:16:01 +0000 | [diff] [blame] | 1471 | Note: for GCC versions before 4.4.0, no allocation context information is |
| 1472 | shown. With these GCC versions the most usable information in the above output |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1473 | is the source file name and the line number where the data race has been |
| 1474 | detected (<literal>omp_matinv.c:203</literal>). |
bart | 243ad39 | 2008-07-02 11:50:37 +0000 | [diff] [blame] | 1475 | </para> |
| 1476 | |
| 1477 | <para> |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 1478 | For more information about OpenMP, see also |
| 1479 | <ulink url="http://openmp.org/">openmp.org</ulink>. |
| 1480 | </para> |
| 1481 | |
| 1482 | </sect2> |
| 1483 | |
| 1484 | |
bart | 88f1141 | 2008-07-03 07:08:04 +0000 | [diff] [blame] | 1485 | <sect2 id="drd-manual.cust-mem-alloc" xreflabel="Custom Memory Allocators"> |
| 1486 | <title>DRD and Custom Memory Allocators</title> |
| 1487 | |
| 1488 | <para> |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1489 | DRD tracks all memory allocation events that happen via the |
bart | 88f1141 | 2008-07-03 07:08:04 +0000 | [diff] [blame] | 1490 | standard memory allocation and deallocation functions |
| 1491 | (<function>malloc</function>, <function>free</function>, |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1492 | <function>new</function> and <function>delete</function>), via entry |
| 1493 | and exit of stack frames or that have been annotated with Valgrind's |
| 1494 | memory pool client requests. DRD uses memory allocation and deallocation |
bart | 88f1141 | 2008-07-03 07:08:04 +0000 | [diff] [blame] | 1495 | information for two purposes: |
| 1496 | <itemizedlist> |
| 1497 | <listitem> |
| 1498 | <para> |
| 1499 | To know where the scope ends of POSIX objects that have not been |
| 1500 | destroyed explicitly. It is e.g. not required by the POSIX |
| 1501 | threads standard to call |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 1502 | <function>pthread_mutex_destroy</function> before freeing the |
bart | 88f1141 | 2008-07-03 07:08:04 +0000 | [diff] [blame] | 1503 | memory in which a mutex object resides. |
| 1504 | </para> |
| 1505 | </listitem> |
| 1506 | <listitem> |
| 1507 | <para> |
| 1508 | To know where the scope of variables ends. If e.g. heap memory |
| 1509 | has been used by one thread, that thread frees that memory, and |
| 1510 | another thread allocates and starts using that memory, no data |
| 1511 | races must be reported for that memory. |
| 1512 | </para> |
| 1513 | </listitem> |
| 1514 | </itemizedlist> |
| 1515 | </para> |
| 1516 | |
| 1517 | <para> |
| 1518 | It is essential for correct operation of DRD that the tool knows about |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1519 | memory allocation and deallocation events. When analyzing a client program |
| 1520 | with DRD that uses a custom memory allocator, either instrument the custom |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 1521 | memory allocator with the <literal>VALGRIND_MALLOCLIKE_BLOCK</literal> |
| 1522 | and <literal>VALGRIND_FREELIKE_BLOCK</literal> macros or disable the |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1523 | custom memory allocator. |
| 1524 | </para> |
| 1525 | |
| 1526 | <para> |
| 1527 | As an example, the GNU libstdc++ library can be configured |
bart | 88f1141 | 2008-07-03 07:08:04 +0000 | [diff] [blame] | 1528 | to use standard memory allocation functions instead of memory pools by |
| 1529 | setting the environment variable |
| 1530 | <literal>GLIBCXX_FORCE_NEW</literal>. For more information, see also |
| 1531 | the <ulink |
| 1532 | url="http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt04ch11.html">libstdc++ |
| 1533 | manual</ulink>. |
| 1534 | </para> |
| 1535 | |
| 1536 | </sect2> |
| 1537 | |
| 1538 | |
| 1539 | <sect2 id="drd-manual.drd-versus-memcheck" xreflabel="DRD Versus Memcheck"> |
| 1540 | <title>DRD Versus Memcheck</title> |
| 1541 | |
| 1542 | <para> |
| 1543 | It is essential for correct operation of DRD that there are no memory |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 1544 | errors such as dangling pointers in the client program. Which means that |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 1545 | it is a good idea to make sure that your program is Memcheck-clean |
bart | 88f1141 | 2008-07-03 07:08:04 +0000 | [diff] [blame] | 1546 | before you analyze it with DRD. It is possible however that some of |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 1547 | the Memcheck reports are caused by data races. In this case it makes |
| 1548 | sense to run DRD before Memcheck. |
bart | 88f1141 | 2008-07-03 07:08:04 +0000 | [diff] [blame] | 1549 | </para> |
| 1550 | |
| 1551 | <para> |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 1552 | So which tool should be run first? In case both DRD and Memcheck |
bart | 88f1141 | 2008-07-03 07:08:04 +0000 | [diff] [blame] | 1553 | complain about a program, a possible approach is to run both tools |
| 1554 | alternatingly and to fix as many errors as possible after each run of |
| 1555 | each tool until none of the two tools prints any more error messages. |
| 1556 | </para> |
| 1557 | |
| 1558 | </sect2> |
| 1559 | |
| 1560 | |
bart | 3d986d6 | 2008-07-05 14:25:09 +0000 | [diff] [blame] | 1561 | <sect2 id="drd-manual.resource-requirements" xreflabel="Resource Requirements"> |
bart | 88f1141 | 2008-07-03 07:08:04 +0000 | [diff] [blame] | 1562 | <title>Resource Requirements</title> |
| 1563 | |
| 1564 | <para> |
| 1565 | The requirements of DRD with regard to heap and stack memory and the |
| 1566 | effect on the execution time of client programs are as follows: |
| 1567 | <itemizedlist> |
| 1568 | <listitem> |
| 1569 | <para> |
| 1570 | When running a program under DRD with default DRD options, |
| 1571 | between 1.1 and 3.6 times more memory will be needed compared to |
| 1572 | a native run of the client program. More memory will be needed |
| 1573 | if loading debug information has been enabled |
bart | e2b9823 | 2009-07-22 18:13:21 +0000 | [diff] [blame] | 1574 | (<literal>--read-var-info=yes</literal>). |
bart | 88f1141 | 2008-07-03 07:08:04 +0000 | [diff] [blame] | 1575 | </para> |
| 1576 | </listitem> |
| 1577 | <listitem> |
| 1578 | <para> |
| 1579 | DRD allocates some of its temporary data structures on the stack |
| 1580 | of the client program threads. This amount of data is limited to |
| 1581 | 1 - 2 KB. Make sure that thread stacks are sufficiently large. |
| 1582 | </para> |
| 1583 | </listitem> |
| 1584 | <listitem> |
| 1585 | <para> |
| 1586 | Most applications will run between 20 and 50 times slower under |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1587 | DRD than a native single-threaded run. The slowdown will be most |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 1588 | noticeable for applications which perform frequent mutex lock / |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1589 | unlock operations. |
bart | 88f1141 | 2008-07-03 07:08:04 +0000 | [diff] [blame] | 1590 | </para> |
| 1591 | </listitem> |
| 1592 | </itemizedlist> |
| 1593 | </para> |
| 1594 | |
| 1595 | </sect2> |
| 1596 | |
| 1597 | |
bart | 3d986d6 | 2008-07-05 14:25:09 +0000 | [diff] [blame] | 1598 | <sect2 id="drd-manual.effective-use" xreflabel="Effective Use"> |
| 1599 | <title>Hints and Tips for Effective Use of DRD</title> |
| 1600 | |
| 1601 | <para> |
| 1602 | The following information may be helpful when using DRD: |
| 1603 | <itemizedlist> |
| 1604 | <listitem> |
| 1605 | <para> |
| 1606 | Make sure that debug information is present in the executable |
bart | dd742f2 | 2009-07-19 19:50:54 +0000 | [diff] [blame] | 1607 | being analyzed, such that DRD can print function name and line |
bart | 3d986d6 | 2008-07-05 14:25:09 +0000 | [diff] [blame] | 1608 | number information in stack traces. Most compilers can be told |
| 1609 | to include debug information via compiler option |
| 1610 | <option>-g</option>. |
| 1611 | </para> |
| 1612 | </listitem> |
| 1613 | <listitem> |
| 1614 | <para> |
njn | a331164 | 2009-08-10 01:29:14 +0000 | [diff] [blame] | 1615 | Compile with option <option>-O1</option> instead of |
bart | 3d986d6 | 2008-07-05 14:25:09 +0000 | [diff] [blame] | 1616 | <option>-O0</option>. This will reduce the amount of generated |
| 1617 | code, may reduce the amount of debug info and will speed up |
| 1618 | DRD's processing of the client program. For more information, |
| 1619 | see also <xref linkend="manual-core.started"/>. |
| 1620 | </para> |
| 1621 | </listitem> |
| 1622 | <listitem> |
| 1623 | <para> |
| 1624 | If DRD reports any errors on libraries that are part of your |
| 1625 | Linux distribution like e.g. <literal>libc.so</literal> or |
| 1626 | <literal>libstdc++.so</literal>, installing the debug packages |
| 1627 | for these libraries will make the output of DRD a lot more |
| 1628 | detailed. |
| 1629 | </para> |
| 1630 | </listitem> |
| 1631 | <listitem> |
| 1632 | <para> |
| 1633 | When using C++, do not send output from more than one thread to |
| 1634 | <literal>std::cout</literal>. Doing so would not only |
| 1635 | generate multiple data race reports, it could also result in |
| 1636 | output from several threads getting mixed up. Either use |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 1637 | <function>printf</function> or do the following: |
bart | 3d986d6 | 2008-07-05 14:25:09 +0000 | [diff] [blame] | 1638 | <orderedlist> |
| 1639 | <listitem> |
| 1640 | <para>Derive a class from <literal>std::ostreambuf</literal> |
| 1641 | and let that class send output line by line to |
| 1642 | <literal>stdout</literal>. This will avoid that individual |
| 1643 | lines of text produced by different threads get mixed |
| 1644 | up.</para> |
| 1645 | </listitem> |
| 1646 | <listitem> |
| 1647 | <para>Create one instance of <literal>std::ostream</literal> |
| 1648 | for each thread. This makes stream formatting settings |
| 1649 | thread-local. Pass a per-thread instance of the class |
| 1650 | derived from <literal>std::ostreambuf</literal> to the |
| 1651 | constructor of each instance. </para> |
| 1652 | </listitem> |
| 1653 | <listitem> |
| 1654 | <para>Let each thread send its output to its own instance of |
| 1655 | <literal>std::ostream</literal> instead of |
| 1656 | <literal>std::cout</literal>.</para> |
| 1657 | </listitem> |
| 1658 | </orderedlist> |
| 1659 | </para> |
| 1660 | </listitem> |
| 1661 | </itemizedlist> |
| 1662 | </para> |
| 1663 | |
| 1664 | </sect2> |
| 1665 | |
| 1666 | |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 1667 | </sect1> |
| 1668 | |
| 1669 | |
bart | 66ba8c0 | 2008-10-11 18:28:12 +0000 | [diff] [blame] | 1670 | <sect1 id="drd-manual.Pthreads" xreflabel="Pthreads"> |
| 1671 | <title>Using the POSIX Threads API Effectively</title> |
| 1672 | |
| 1673 | <sect2 id="drd-manual.mutex-types" xreflabel="mutex-types"> |
| 1674 | <title>Mutex types</title> |
| 1675 | |
| 1676 | <para> |
| 1677 | The Single UNIX Specification version two defines the following four |
| 1678 | mutex types (see also the documentation of <ulink |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 1679 | url="http://www.opengroup.org/onlinepubs/007908799/xsh/pthread_mutexattr_settype.html"><function>pthread_mutexattr_settype</function></ulink>): |
bart | 66ba8c0 | 2008-10-11 18:28:12 +0000 | [diff] [blame] | 1680 | <itemizedlist> |
| 1681 | <listitem> |
| 1682 | <para> |
| 1683 | <emphasis>normal</emphasis>, which means that no error checking |
| 1684 | is performed, and that the mutex is non-recursive. |
| 1685 | </para> |
| 1686 | </listitem> |
| 1687 | <listitem> |
| 1688 | <para> |
| 1689 | <emphasis>error checking</emphasis>, which means that the mutex |
| 1690 | is non-recursive and that error checking is performed. |
| 1691 | </para> |
| 1692 | </listitem> |
| 1693 | <listitem> |
| 1694 | <para> |
| 1695 | <emphasis>recursive</emphasis>, which means that a mutex may be |
| 1696 | locked recursively. |
| 1697 | </para> |
| 1698 | </listitem> |
| 1699 | <listitem> |
| 1700 | <para> |
| 1701 | <emphasis>default</emphasis>, which means that error checking |
| 1702 | behavior is undefined, and that the behavior for recursive |
| 1703 | locking is also undefined. Or: portable code must neither |
| 1704 | trigger error conditions through the Pthreads API nor attempt to |
| 1705 | lock a mutex of default type recursively. |
| 1706 | </para> |
| 1707 | </listitem> |
| 1708 | </itemizedlist> |
| 1709 | </para> |
| 1710 | |
| 1711 | <para> |
| 1712 | In complex applications it is not always clear from beforehand which |
| 1713 | mutex will be locked recursively and which mutex will not be locked |
| 1714 | recursively. Attempts lock a non-recursive mutex recursively will |
| 1715 | result in race conditions that are very hard to find without a thread |
| 1716 | checking tool. So either use the error checking mutex type and |
| 1717 | consistently check the return value of Pthread API mutex calls, or use |
| 1718 | the recursive mutex type. |
| 1719 | </para> |
| 1720 | |
| 1721 | </sect2> |
| 1722 | |
| 1723 | <sect2 id="drd-manual.condvar" xreflabel="condition-variables"> |
| 1724 | <title>Condition variables</title> |
| 1725 | |
| 1726 | <para> |
| 1727 | A condition variable allows one thread to wake up one or more other |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 1728 | threads. Condition variables are often used to notify one or more |
bart | 66ba8c0 | 2008-10-11 18:28:12 +0000 | [diff] [blame] | 1729 | threads about state changes of shared data. Unfortunately it is very |
| 1730 | easy to introduce race conditions by using condition variables as the |
| 1731 | only means of state information propagation. A better approach is to |
| 1732 | let threads poll for changes of a state variable that is protected by |
| 1733 | a mutex, and to use condition variables only as a thread wakeup |
| 1734 | mechanism. See also the source file |
| 1735 | <computeroutput>drd/tests/monitor_example.cpp</computeroutput> for an |
| 1736 | example of how to implement this concept in C++. The monitor concept |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 1737 | used in this example is a well known and very useful concept -- see |
| 1738 | also Wikipedia for more information about the <ulink |
bart | 66ba8c0 | 2008-10-11 18:28:12 +0000 | [diff] [blame] | 1739 | url="http://en.wikipedia.org/wiki/Monitor_(synchronization)">monitor</ulink> |
| 1740 | concept. |
| 1741 | </para> |
| 1742 | |
| 1743 | </sect2> |
| 1744 | |
| 1745 | <sect2 id="drd-manual.pctw" xreflabel="pthread_cond_timedwait"> |
sewardj | 1160e81 | 2010-09-10 14:56:18 +0000 | [diff] [blame] | 1746 | <title>pthread_cond_timedwait and timeouts</title> |
bart | 66ba8c0 | 2008-10-11 18:28:12 +0000 | [diff] [blame] | 1747 | |
| 1748 | <para> |
| 1749 | Historically the function |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 1750 | <function>pthread_cond_timedwait</function> only allowed the |
bart | 66ba8c0 | 2008-10-11 18:28:12 +0000 | [diff] [blame] | 1751 | specification of an absolute timeout, that is a timeout independent of |
| 1752 | the time when this function was called. However, almost every call to |
| 1753 | this function expresses a relative timeout. This typically happens by |
| 1754 | passing the sum of |
| 1755 | <computeroutput>clock_gettime(CLOCK_REALTIME)</computeroutput> and a |
| 1756 | relative timeout as the third argument. This approach is incorrect |
| 1757 | since forward or backward clock adjustments by e.g. ntpd will affect |
| 1758 | the timeout. A more reliable approach is as follows: |
| 1759 | <itemizedlist> |
| 1760 | <listitem> |
| 1761 | <para> |
| 1762 | When initializing a condition variable through |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 1763 | <function>pthread_cond_init</function>, specify that the timeout of |
| 1764 | <function>pthread_cond_timedwait</function> will use the clock |
bart | 66ba8c0 | 2008-10-11 18:28:12 +0000 | [diff] [blame] | 1765 | <literal>CLOCK_MONOTONIC</literal> instead of |
| 1766 | <literal>CLOCK_REALTIME</literal>. You can do this via |
| 1767 | <computeroutput>pthread_condattr_setclock(..., |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 1768 | CLOCK_MONOTONIC)</computeroutput>. |
bart | 66ba8c0 | 2008-10-11 18:28:12 +0000 | [diff] [blame] | 1769 | </para> |
| 1770 | </listitem> |
| 1771 | <listitem> |
| 1772 | <para> |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 1773 | When calling <function>pthread_cond_timedwait</function>, pass |
bart | 66ba8c0 | 2008-10-11 18:28:12 +0000 | [diff] [blame] | 1774 | the sum of |
| 1775 | <computeroutput>clock_gettime(CLOCK_MONOTONIC)</computeroutput> |
| 1776 | and a relative timeout as the third argument. |
| 1777 | </para> |
| 1778 | </listitem> |
| 1779 | </itemizedlist> |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 1780 | See also |
| 1781 | <computeroutput>drd/tests/monitor_example.cpp</computeroutput> for an |
| 1782 | example. |
bart | 66ba8c0 | 2008-10-11 18:28:12 +0000 | [diff] [blame] | 1783 | </para> |
| 1784 | |
| 1785 | </sect2> |
| 1786 | |
bart | 66ba8c0 | 2008-10-11 18:28:12 +0000 | [diff] [blame] | 1787 | </sect1> |
| 1788 | |
| 1789 | |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 1790 | <sect1 id="drd-manual.limitations" xreflabel="Limitations"> |
bart | 5a5fe0c | 2008-06-15 12:22:37 +0000 | [diff] [blame] | 1791 | <title>Limitations</title> |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 1792 | |
| 1793 | <para>DRD currently has the following limitations:</para> |
| 1794 | |
| 1795 | <itemizedlist> |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 1796 | <listitem> |
| 1797 | <para> |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 1798 | DRD, just like Memcheck, will refuse to start on Linux |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 1799 | distributions where all symbol information has been removed from |
njn | 2d6d503 | 2009-08-07 05:23:31 +0000 | [diff] [blame] | 1800 | <filename>ld.so</filename>. This is e.g. the case for the PPC editions |
| 1801 | of openSUSE and Gentoo. You will have to install the glibc debuginfo |
| 1802 | package on these platforms before you can use DRD. See also openSUSE |
| 1803 | bug <ulink url="http://bugzilla.novell.com/show_bug.cgi?id=396197"> |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 1804 | 396197</ulink> and Gentoo bug <ulink |
| 1805 | url="http://bugs.gentoo.org/214065">214065</ulink>. |
| 1806 | </para> |
| 1807 | </listitem> |
| 1808 | <listitem> |
| 1809 | <para> |
bart | 18f734b | 2010-10-10 18:57:53 +0000 | [diff] [blame] | 1810 | With gcc 4.4.3 and before, DRD may report data races on the C++ |
| 1811 | class <literal>std::string</literal> in a multithreaded program. This is |
| 1812 | a know <literal>libstdc++</literal> issue -- see also GCC bug |
| 1813 | <ulink url="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=40518">40518</ulink> |
| 1814 | for more information. |
| 1815 | </para> |
| 1816 | </listitem> |
| 1817 | <listitem> |
| 1818 | <para> |
njn | 7316df2 | 2009-08-04 01:16:01 +0000 | [diff] [blame] | 1819 | If you compile the DRD source code yourself, you need GCC 3.0 or |
| 1820 | later. GCC 2.95 is not supported. |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 1821 | </para> |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 1822 | </listitem> |
bart | 18f734b | 2010-10-10 18:57:53 +0000 | [diff] [blame] | 1823 | <listitem> |
| 1824 | <para> |
| 1825 | Of the two POSIX threads implementations for Linux, only the |
| 1826 | NPTL (Native POSIX Thread Library) is supported. The older |
| 1827 | LinuxThreads library is not supported. |
| 1828 | </para> |
| 1829 | </listitem> |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 1830 | </itemizedlist> |
| 1831 | |
| 1832 | </sect1> |
| 1833 | |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 1834 | |
| 1835 | <sect1 id="drd-manual.feedback" xreflabel="Feedback"> |
| 1836 | <title>Feedback</title> |
| 1837 | |
| 1838 | <para> |
| 1839 | If you have any comments, suggestions, feedback or bug reports about |
| 1840 | DRD, feel free to either post a message on the Valgrind users mailing |
| 1841 | list or to file a bug report. See also <ulink |
bart | 4ac853b | 2009-01-02 13:29:32 +0000 | [diff] [blame] | 1842 | url="&vg-url;">&vg-url;</ulink> for more information. |
bart | 68bac81 | 2008-06-27 14:56:06 +0000 | [diff] [blame] | 1843 | </para> |
| 1844 | |
| 1845 | </sect1> |
| 1846 | |
| 1847 | |
bart | e3e54df | 2008-06-12 15:20:42 +0000 | [diff] [blame] | 1848 | </chapter> |