1 <html> 2 <head> 3 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 4 <title>7.�Helgrind: a thread error detector</title> 5 <link rel="stylesheet" href="vg_basic.css" type="text/css"> 6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> 7 <link rel="home" href="index.html" title="Valgrind Documentation"> 8 <link rel="up" href="manual.html" title="Valgrind User Manual"> 9 <link rel="prev" href="cl-manual.html" title="6.�Callgrind: a call-graph generating cache and branch prediction profiler"> 10 <link rel="next" href="drd-manual.html" title="8.�DRD: a thread error detector"> 11 </head> 12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13 <div><table class="nav" width="100%" cellspacing="3" cellpadding="3" border="0" summary="Navigation header"><tr> 14 <td width="22px" align="center" valign="middle"><a accesskey="p" href="cl-manual.html"><img src="images/prev.png" width="18" height="21" border="0" alt="Prev"></a></td> 15 <td width="25px" align="center" valign="middle"><a accesskey="u" href="manual.html"><img src="images/up.png" width="21" height="18" border="0" alt="Up"></a></td> 16 <td width="31px" align="center" valign="middle"><a accesskey="h" href="index.html"><img src="images/home.png" width="27" height="20" border="0" alt="Up"></a></td> 17 <th align="center" valign="middle">Valgrind User Manual</th> 18 <td width="22px" align="center" valign="middle"><a accesskey="n" href="drd-manual.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td> 19 </tr></table></div> 20 <div class="chapter" title="7.�Helgrind: a thread error detector"> 21 <div class="titlepage"><div><div><h2 class="title"> 22 <a name="hg-manual"></a>7.�Helgrind: a thread error detector</h2></div></div></div> 23 <div class="toc"> 24 <p><b>Table of Contents</b></p> 25 <dl> 26 <dt><span class="sect1"><a href="hg-manual.html#hg-manual.overview">7.1. Overview</a></span></dt> 27 <dt><span class="sect1"><a href="hg-manual.html#hg-manual.api-checks">7.2. Detected errors: Misuses of the POSIX pthreads API</a></span></dt> 28 <dt><span class="sect1"><a href="hg-manual.html#hg-manual.lock-orders">7.3. Detected errors: Inconsistent Lock Orderings</a></span></dt> 29 <dt><span class="sect1"><a href="hg-manual.html#hg-manual.data-races">7.4. Detected errors: Data Races</a></span></dt> 30 <dd><dl> 31 <dt><span class="sect2"><a href="hg-manual.html#hg-manual.data-races.example">7.4.1. A Simple Data Race</a></span></dt> 32 <dt><span class="sect2"><a href="hg-manual.html#hg-manual.data-races.algorithm">7.4.2. Helgrind's Race Detection Algorithm</a></span></dt> 33 <dt><span class="sect2"><a href="hg-manual.html#hg-manual.data-races.errmsgs">7.4.3. Interpreting Race Error Messages</a></span></dt> 34 </dl></dd> 35 <dt><span class="sect1"><a href="hg-manual.html#hg-manual.effective-use">7.5. Hints and Tips for Effective Use of Helgrind</a></span></dt> 36 <dt><span class="sect1"><a href="hg-manual.html#hg-manual.options">7.6. Helgrind Command-line Options</a></span></dt> 37 <dt><span class="sect1"><a href="hg-manual.html#hg-manual.client-requests">7.7. Helgrind Client Requests</a></span></dt> 38 <dt><span class="sect1"><a href="hg-manual.html#hg-manual.todolist">7.8. A To-Do List for Helgrind</a></span></dt> 39 </dl> 40 </div> 41 <p>To use this tool, you must specify 42 <code class="option">--tool=helgrind</code> on the Valgrind 43 command line.</p> 44 <div class="sect1" title="7.1.�Overview"> 45 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> 46 <a name="hg-manual.overview"></a>7.1.�Overview</h2></div></div></div> 47 <p>Helgrind is a Valgrind tool for detecting synchronisation errors 48 in C, C++ and Fortran programs that use the POSIX pthreads 49 threading primitives.</p> 50 <p>The main abstractions in POSIX pthreads are: a set of threads 51 sharing a common address space, thread creation, thread joining, 52 thread exit, mutexes (locks), condition variables (inter-thread event 53 notifications), reader-writer locks, spinlocks, semaphores and 54 barriers.</p> 55 <p>Helgrind can detect three classes of errors, which are discussed 56 in detail in the next three sections:</p> 57 <div class="orderedlist"><ol class="orderedlist" type="1"> 58 <li class="listitem"><p><a class="link" href="hg-manual.html#hg-manual.api-checks" title="7.2.�Detected errors: Misuses of the POSIX pthreads API"> 59 Misuses of the POSIX pthreads API.</a></p></li> 60 <li class="listitem"><p><a class="link" href="hg-manual.html#hg-manual.lock-orders" title="7.3.�Detected errors: Inconsistent Lock Orderings"> 61 Potential deadlocks arising from lock 62 ordering problems.</a></p></li> 63 <li class="listitem"><p><a class="link" href="hg-manual.html#hg-manual.data-races" title="7.4.�Detected errors: Data Races"> 64 Data races -- accessing memory without adequate locking 65 or synchronisation</a>. 66 </p></li> 67 </ol></div> 68 <p>Problems like these often result in unreproducible, 69 timing-dependent crashes, deadlocks and other misbehaviour, and 70 can be difficult to find by other means.</p> 71 <p>Helgrind is aware of all the pthread abstractions and tracks 72 their effects as accurately as it can. On x86 and amd64 platforms, it 73 understands and partially handles implicit locking arising from the 74 use of the LOCK instruction prefix. 75 </p> 76 <p>Helgrind works best when your application uses only the POSIX 77 pthreads API. However, if you want to use custom threading 78 primitives, you can describe their behaviour to Helgrind using the 79 <code class="varname">ANNOTATE_*</code> macros defined 80 in <code class="varname">helgrind.h</code>. This functionality was added in 81 release 3.5.0 of Valgrind, and is considered experimental.</p> 82 <p>Following those is a section containing 83 <a class="link" href="hg-manual.html#hg-manual.effective-use" title="7.5.�Hints and Tips for Effective Use of Helgrind"> 84 hints and tips on how to get the best out of Helgrind.</a> 85 </p> 86 <p>Then there is a 87 <a class="link" href="hg-manual.html#hg-manual.options" title="7.6.�Helgrind Command-line Options">summary of command-line 88 options.</a> 89 </p> 90 <p>Finally, there is 91 <a class="link" href="hg-manual.html#hg-manual.todolist" title="7.8.�A To-Do List for Helgrind">a brief summary of areas in which Helgrind 92 could be improved.</a> 93 </p> 94 </div> 95 <div class="sect1" title="7.2.�Detected errors: Misuses of the POSIX pthreads API"> 96 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> 97 <a name="hg-manual.api-checks"></a>7.2.�Detected errors: Misuses of the POSIX pthreads API</h2></div></div></div> 98 <p>Helgrind intercepts calls to many POSIX pthreads functions, and 99 is therefore able to report on various common problems. Although 100 these are unglamourous errors, their presence can lead to undefined 101 program behaviour and hard-to-find bugs later on. The detected errors 102 are:</p> 103 <div class="itemizedlist"><ul class="itemizedlist" type="disc"> 104 <li class="listitem"><p>unlocking an invalid mutex</p></li> 105 <li class="listitem"><p>unlocking a not-locked mutex</p></li> 106 <li class="listitem"><p>unlocking a mutex held by a different 107 thread</p></li> 108 <li class="listitem"><p>destroying an invalid or a locked mutex</p></li> 109 <li class="listitem"><p>recursively locking a non-recursive mutex</p></li> 110 <li class="listitem"><p>deallocation of memory that contains a 111 locked mutex</p></li> 112 <li class="listitem"><p>passing mutex arguments to functions expecting 113 reader-writer lock arguments, and vice 114 versa</p></li> 115 <li class="listitem"><p>when a POSIX pthread function fails with an 116 error code that must be handled</p></li> 117 <li class="listitem"><p>when a thread exits whilst still holding locked 118 locks</p></li> 119 <li class="listitem"><p>calling <code class="function">pthread_cond_wait</code> 120 with a not-locked mutex, an invalid mutex, 121 or one locked by a different 122 thread</p></li> 123 <li class="listitem"><p>inconsistent bindings between condition 124 variables and their associated mutexes</p></li> 125 <li class="listitem"><p>invalid or duplicate initialisation of a pthread 126 barrier</p></li> 127 <li class="listitem"><p>initialisation of a pthread barrier on which threads 128 are still waiting</p></li> 129 <li class="listitem"><p>destruction of a pthread barrier object which was 130 never initialised, or on which threads are still 131 waiting</p></li> 132 <li class="listitem"><p>waiting on an uninitialised pthread 133 barrier</p></li> 134 <li class="listitem"><p>for all of the pthreads functions that Helgrind 135 intercepts, an error is reported, along with a stack 136 trace, if the system threading library routine returns 137 an error code, even if Helgrind itself detected no 138 error</p></li> 139 </ul></div> 140 <p>Checks pertaining to the validity of mutexes are generally also 141 performed for reader-writer locks.</p> 142 <p>Various kinds of this-can't-possibly-happen events are also 143 reported. These usually indicate bugs in the system threading 144 library.</p> 145 <p>Reported errors always contain a primary stack trace indicating 146 where the error was detected. They may also contain auxiliary stack 147 traces giving additional information. In particular, most errors 148 relating to mutexes will also tell you where that mutex first came to 149 Helgrind's attention (the "<code class="computeroutput">was first observed 150 at</code>" part), so you have a chance of figuring out which 151 mutex it is referring to. For example:</p> 152 <pre class="programlisting"> 153 Thread #1 unlocked a not-locked lock at 0x7FEFFFA90 154 at 0x4C2408D: pthread_mutex_unlock (hg_intercepts.c:492) 155 by 0x40073A: nearly_main (tc09_bad_unlock.c:27) 156 by 0x40079B: main (tc09_bad_unlock.c:50) 157 Lock at 0x7FEFFFA90 was first observed 158 at 0x4C25D01: pthread_mutex_init (hg_intercepts.c:326) 159 by 0x40071F: nearly_main (tc09_bad_unlock.c:23) 160 by 0x40079B: main (tc09_bad_unlock.c:50) 161 </pre> 162 <p>Helgrind has a way of summarising thread identities, as 163 you see here with the text "<code class="computeroutput">Thread 164 #1</code>". This is so that it can speak about threads and 165 sets of threads without overwhelming you with details. See 166 <a class="link" href="hg-manual.html#hg-manual.data-races.errmsgs" title="7.4.3.�Interpreting Race Error Messages">below</a> 167 for more information on interpreting error messages.</p> 168 </div> 169 <div class="sect1" title="7.3.�Detected errors: Inconsistent Lock Orderings"> 170 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> 171 <a name="hg-manual.lock-orders"></a>7.3.�Detected errors: Inconsistent Lock Orderings</h2></div></div></div> 172 <p>In this section, and in general, to "acquire" a lock simply 173 means to lock that lock, and to "release" a lock means to unlock 174 it.</p> 175 <p>Helgrind monitors the order in which threads acquire locks. 176 This allows it to detect potential deadlocks which could arise from 177 the formation of cycles of locks. Detecting such inconsistencies is 178 useful because, whilst actual deadlocks are fairly obvious, potential 179 deadlocks may never be discovered during testing and could later lead 180 to hard-to-diagnose in-service failures.</p> 181 <p>The simplest example of such a problem is as 182 follows.</p> 183 <div class="itemizedlist"><ul class="itemizedlist" type="disc"> 184 <li class="listitem"><p>Imagine some shared resource R, which, for whatever 185 reason, is guarded by two locks, L1 and L2, which must both be held 186 when R is accessed.</p></li> 187 <li class="listitem"><p>Suppose a thread acquires L1, then L2, and proceeds 188 to access R. The implication of this is that all threads in the 189 program must acquire the two locks in the order first L1 then L2. 190 Not doing so risks deadlock.</p></li> 191 <li class="listitem"><p>The deadlock could happen if two threads -- call them 192 T1 and T2 -- both want to access R. Suppose T1 acquires L1 first, 193 and T2 acquires L2 first. Then T1 tries to acquire L2, and T2 tries 194 to acquire L1, but those locks are both already held. So T1 and T2 195 become deadlocked.</p></li> 196 </ul></div> 197 <p>Helgrind builds a directed graph indicating the order in which 198 locks have been acquired in the past. When a thread acquires a new 199 lock, the graph is updated, and then checked to see if it now contains 200 a cycle. The presence of a cycle indicates a potential deadlock involving 201 the locks in the cycle.</p> 202 <p>In simple situations, where the cycle only contains two locks, 203 Helgrind will show where the required order was established:</p> 204 <pre class="programlisting"> 205 Thread #1: lock order "0x7FEFFFAB0 before 0x7FEFFFA80" violated 206 at 0x4C23C91: pthread_mutex_lock (hg_intercepts.c:388) 207 by 0x40081F: main (tc13_laog1.c:24) 208 Required order was established by acquisition of lock at 0x7FEFFFAB0 209 at 0x4C23C91: pthread_mutex_lock (hg_intercepts.c:388) 210 by 0x400748: main (tc13_laog1.c:17) 211 followed by a later acquisition of lock at 0x7FEFFFA80 212 at 0x4C23C91: pthread_mutex_lock (hg_intercepts.c:388) 213 by 0x400773: main (tc13_laog1.c:18) 214 </pre> 215 <p>When there are more than two locks in the cycle, the error is 216 equally serious. However, at present Helgrind does not show the locks 217 involved, so as to avoid flooding you with information. That could be 218 fixed in future. For example, here is a an example involving a cycle 219 of five locks from a naive implementation the famous Dining 220 Philosophers problem 221 (see <code class="computeroutput">helgrind/tests/tc14_laog_dinphils.c</code>). 222 In this case Helgrind has detected that all 5 philosophers could 223 simultaneously pick up their left fork and then deadlock whilst 224 waiting to pick up their right forks.</p> 225 <pre class="programlisting"> 226 Thread #6: lock order "0x6010C0 before 0x601160" violated 227 at 0x4C23C91: pthread_mutex_lock (hg_intercepts.c:388) 228 by 0x4007C0: dine (tc14_laog_dinphils.c:19) 229 by 0x4C25DF7: mythread_wrapper (hg_intercepts.c:178) 230 by 0x4E2F09D: start_thread (in /lib64/libpthread-2.5.so) 231 by 0x51054CC: clone (in /lib64/libc-2.5.so) 232 </pre> 233 </div> 234 <div class="sect1" title="7.4.�Detected errors: Data Races"> 235 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> 236 <a name="hg-manual.data-races"></a>7.4.�Detected errors: Data Races</h2></div></div></div> 237 <p>A data race happens, or could happen, when two threads access a 238 shared memory location without using suitable locks or other 239 synchronisation to ensure single-threaded access. Such missing 240 locking can cause obscure timing dependent bugs. Ensuring programs 241 are race-free is one of the central difficulties of threaded 242 programming.</p> 243 <p>Reliably detecting races is a difficult problem, and most 244 of Helgrind's internals are devoted to do dealing with it. 245 We begin with a simple example.</p> 246 <div class="sect2" title="7.4.1.�A Simple Data Race"> 247 <div class="titlepage"><div><div><h3 class="title"> 248 <a name="hg-manual.data-races.example"></a>7.4.1.�A Simple Data Race</h3></div></div></div> 249 <p>About the simplest possible example of a race is as follows. In 250 this program, it is impossible to know what the value 251 of <code class="computeroutput">var</code> is at the end of the program. 252 Is it 2 ? Or 1 ?</p> 253 <pre class="programlisting"> 254 #include <pthread.h> 255 256 int var = 0; 257 258 void* child_fn ( void* arg ) { 259 var++; /* Unprotected relative to parent */ /* this is line 6 */ 260 return NULL; 261 } 262 263 int main ( void ) { 264 pthread_t child; 265 pthread_create(&child, NULL, child_fn, NULL); 266 var++; /* Unprotected relative to child */ /* this is line 13 */ 267 pthread_join(child, NULL); 268 return 0; 269 } 270 </pre> 271 <p>The problem is there is nothing to 272 stop <code class="varname">var</code> being updated simultaneously 273 by both threads. A correct program would 274 protect <code class="varname">var</code> with a lock of type 275 <code class="function">pthread_mutex_t</code>, which is acquired 276 before each access and released afterwards. Helgrind's output for 277 this program is:</p> 278 <pre class="programlisting"> 279 Thread #1 is the program's root thread 280 281 Thread #2 was created 282 at 0x511C08E: clone (in /lib64/libc-2.8.so) 283 by 0x4E333A4: do_clone (in /lib64/libpthread-2.8.so) 284 by 0x4E33A30: pthread_create@@GLIBC_2.2.5 (in /lib64/libpthread-2.8.so) 285 by 0x4C299D4: pthread_create@* (hg_intercepts.c:214) 286 by 0x400605: main (simple_race.c:12) 287 288 Possible data race during read of size 4 at 0x601038 by thread #1 289 at 0x400606: main (simple_race.c:13) 290 This conflicts with a previous write of size 4 by thread #2 291 at 0x4005DC: child_fn (simple_race.c:6) 292 by 0x4C29AFF: mythread_wrapper (hg_intercepts.c:194) 293 by 0x4E3403F: start_thread (in /lib64/libpthread-2.8.so) 294 by 0x511C0CC: clone (in /lib64/libc-2.8.so) 295 Location 0x601038 is 0 bytes inside global var "var" 296 declared at simple_race.c:3 297 </pre> 298 <p>This is quite a lot of detail for an apparently simple error. 299 The last clause is the main error message. It says there is a race as 300 a result of a read of size 4 (bytes), at 0x601038, which is the 301 address of <code class="computeroutput">var</code>, happening in 302 function <code class="computeroutput">main</code> at line 13 in the 303 program.</p> 304 <p>Two important parts of the message are:</p> 305 <div class="itemizedlist"><ul class="itemizedlist" type="disc"> 306 <li class="listitem"> 307 <p>Helgrind shows two stack traces for the error, not one. By 308 definition, a race involves two different threads accessing the 309 same location in such a way that the result depends on the relative 310 speeds of the two threads.</p> 311 <p> 312 The first stack trace follows the text "<code class="computeroutput">Possible 313 data race during read of size 4 ...</code>" and the 314 second trace follows the text "<code class="computeroutput">This conflicts with 315 a previous write of size 4 ...</code>". Helgrind is 316 usually able to show both accesses involved in a race. At least 317 one of these will be a write (since two concurrent, unsynchronised 318 reads are harmless), and they will of course be from different 319 threads.</p> 320 <p>By examining your program at the two locations, you should be 321 able to get at least some idea of what the root cause of the 322 problem is.</p> 323 </li> 324 <li class="listitem"> 325 <p>For races which occur on global or stack variables, Helgrind 326 tries to identify the name and defining point of the variable. 327 Hence the text "<code class="computeroutput">Location 0x601038 is 0 bytes inside 328 global var "var" declared at simple_race.c:3</code>".</p> 329 <p>Showing names of stack and global variables carries no 330 run-time overhead once Helgrind has your program up and running. 331 However, it does require Helgrind to spend considerable extra time 332 and memory at program startup to read the relevant debug info. 333 Hence this facility is disabled by default. To enable it, you need 334 to give the <code class="varname">--read-var-info=yes</code> option to 335 Helgrind.</p> 336 </li> 337 </ul></div> 338 <p>The following section explains Helgrind's race detection 339 algorithm in more detail.</p> 340 </div> 341 <div class="sect2" title="7.4.2.�Helgrind's Race Detection Algorithm"> 342 <div class="titlepage"><div><div><h3 class="title"> 343 <a name="hg-manual.data-races.algorithm"></a>7.4.2.�Helgrind's Race Detection Algorithm</h3></div></div></div> 344 <p>Most programmers think about threaded programming in terms of 345 the basic functionality provided by the threading library (POSIX 346 Pthreads): thread creation, thread joining, locks, condition 347 variables, semaphores and barriers.</p> 348 <p>The effect of using these functions is to impose 349 constraints upon the order in which memory accesses can 350 happen. This implied ordering is generally known as the 351 "happens-before relation". Once you understand the happens-before 352 relation, it is easy to see how Helgrind finds races in your code. 353 Fortunately, the happens-before relation is itself easy to understand, 354 and is by itself a useful tool for reasoning about the behaviour of 355 parallel programs. We now introduce it using a simple example.</p> 356 <p>Consider first the following buggy program:</p> 357 <pre class="programlisting"> 358 Parent thread: Child thread: 359 360 int var; 361 362 // create child thread 363 pthread_create(...) 364 var = 20; var = 10; 365 exit 366 367 // wait for child 368 pthread_join(...) 369 printf("%d\n", var); 370 </pre> 371 <p>The parent thread creates a child. Both then write different 372 values to some variable <code class="computeroutput">var</code>, and the 373 parent then waits for the child to exit.</p> 374 <p>What is the value of <code class="computeroutput">var</code> at the 375 end of the program, 10 or 20? We don't know. The program is 376 considered buggy (it has a race) because the final value 377 of <code class="computeroutput">var</code> depends on the relative rates 378 of progress of the parent and child threads. If the parent is fast 379 and the child is slow, then the child's assignment may happen later, 380 so the final value will be 10; and vice versa if the child is faster 381 than the parent.</p> 382 <p>The relative rates of progress of parent vs child is not something 383 the programmer can control, and will often change from run to run. 384 It depends on factors such as the load on the machine, what else is 385 running, the kernel's scheduling strategy, and many other factors.</p> 386 <p>The obvious fix is to use a lock to 387 protect <code class="computeroutput">var</code>. It is however 388 instructive to consider a somewhat more abstract solution, which is to 389 send a message from one thread to the other:</p> 390 <pre class="programlisting"> 391 Parent thread: Child thread: 392 393 int var; 394 395 // create child thread 396 pthread_create(...) 397 var = 20; 398 // send message to child 399 // wait for message to arrive 400 var = 10; 401 exit 402 403 // wait for child 404 pthread_join(...) 405 printf("%d\n", var); 406 </pre> 407 <p>Now the program reliably prints "10", regardless of the speed of 408 the threads. Why? Because the child's assignment cannot happen until 409 after it receives the message. And the message is not sent until 410 after the parent's assignment is done.</p> 411 <p>The message transmission creates a "happens-before" dependency 412 between the two assignments: <code class="computeroutput">var = 20;</code> 413 must now happen-before <code class="computeroutput">var = 10;</code>. 414 And so there is no longer a race 415 on <code class="computeroutput">var</code>. 416 </p> 417 <p>Note that it's not significant that the parent sends a message 418 to the child. Sending a message from the child (after its assignment) 419 to the parent (before its assignment) would also fix the problem, causing 420 the program to reliably print "20".</p> 421 <p>Helgrind's algorithm is (conceptually) very simple. It monitors all 422 accesses to memory locations. If a location -- in this example, 423 <code class="computeroutput">var</code>, 424 is accessed by two different threads, Helgrind checks to see if the 425 two accesses are ordered by the happens-before relation. If so, 426 that's fine; if not, it reports a race.</p> 427 <p>It is important to understand that the happens-before relation 428 creates only a partial ordering, not a total ordering. An example of 429 a total ordering is comparison of numbers: for any two numbers 430 <code class="computeroutput">x</code> and 431 <code class="computeroutput">y</code>, either 432 <code class="computeroutput">x</code> is less than, equal to, or greater 433 than 434 <code class="computeroutput">y</code>. A partial ordering is like a 435 total ordering, but it can also express the concept that two elements 436 are neither equal, less or greater, but merely unordered with respect 437 to each other.</p> 438 <p>In the fixed example above, we say that 439 <code class="computeroutput">var = 20;</code> "happens-before" 440 <code class="computeroutput">var = 10;</code>. But in the original 441 version, they are unordered: we cannot say that either happens-before 442 the other.</p> 443 <p>What does it mean to say that two accesses from different 444 threads are ordered by the happens-before relation? It means that 445 there is some chain of inter-thread synchronisation operations which 446 cause those accesses to happen in a particular order, irrespective of 447 the actual rates of progress of the individual threads. This is a 448 required property for a reliable threaded program, which is why 449 Helgrind checks for it.</p> 450 <p>The happens-before relations created by standard threading 451 primitives are as follows:</p> 452 <div class="itemizedlist"><ul class="itemizedlist" type="disc"> 453 <li class="listitem"><p>When a mutex is unlocked by thread T1 and later (or 454 immediately) locked by thread T2, then the memory accesses in T1 455 prior to the unlock must happen-before those in T2 after it acquires 456 the lock.</p></li> 457 <li class="listitem"><p>The same idea applies to reader-writer locks, 458 although with some complication so as to allow correct handling of 459 reads vs writes.</p></li> 460 <li class="listitem"><p>When a condition variable (CV) is signalled on by 461 thread T1 and some other thread T2 is thereby released from a wait 462 on the same CV, then the memory accesses in T1 prior to the 463 signalling must happen-before those in T2 after it returns from the 464 wait. If no thread was waiting on the CV then there is no 465 effect.</p></li> 466 <li class="listitem"><p>If instead T1 broadcasts on a CV, then all of the 467 waiting threads, rather than just one of them, acquire a 468 happens-before dependency on the broadcasting thread at the point it 469 did the broadcast.</p></li> 470 <li class="listitem"><p>A thread T2 that continues after completing sem_wait 471 on a semaphore that thread T1 posts on, acquires a happens-before 472 dependence on the posting thread, a bit like dependencies caused 473 mutex unlock-lock pairs. However, since a semaphore can be posted 474 on many times, it is unspecified from which of the post calls the 475 wait call gets its happens-before dependency.</p></li> 476 <li class="listitem"><p>For a group of threads T1 .. Tn which arrive at a 477 barrier and then move on, each thread after the call has a 478 happens-after dependency from all threads before the 479 barrier.</p></li> 480 <li class="listitem"><p>A newly-created child thread acquires an initial 481 happens-after dependency on the point where its parent created it. 482 That is, all memory accesses performed by the parent prior to 483 creating the child are regarded as happening-before all the accesses 484 of the child.</p></li> 485 <li class="listitem"><p>Similarly, when an exiting thread is reaped via a 486 call to <code class="function">pthread_join</code>, once the call returns, the 487 reaping thread acquires a happens-after dependency relative to all memory 488 accesses made by the exiting thread.</p></li> 489 </ul></div> 490 <p>In summary: Helgrind intercepts the above listed events, and builds a 491 directed acyclic graph represented the collective happens-before 492 dependencies. It also monitors all memory accesses.</p> 493 <p>If a location is accessed by two different threads, but Helgrind 494 cannot find any path through the happens-before graph from one access 495 to the other, then it reports a race.</p> 496 <p>There are a couple of caveats:</p> 497 <div class="itemizedlist"><ul class="itemizedlist" type="disc"> 498 <li class="listitem"><p>Helgrind doesn't check for a race in the case where 499 both accesses are reads. That would be silly, since concurrent 500 reads are harmless.</p></li> 501 <li class="listitem"><p>Two accesses are considered to be ordered by the 502 happens-before dependency even through arbitrarily long chains of 503 synchronisation events. For example, if T1 accesses some location 504 L, and then <code class="function">pthread_cond_signals</code> T2, which later 505 <code class="function">pthread_cond_signals</code> T3, which then accesses L, then 506 a suitable happens-before dependency exists between the first and second 507 accesses, even though it involves two different inter-thread 508 synchronisation events.</p></li> 509 </ul></div> 510 </div> 511 <div class="sect2" title="7.4.3.�Interpreting Race Error Messages"> 512 <div class="titlepage"><div><div><h3 class="title"> 513 <a name="hg-manual.data-races.errmsgs"></a>7.4.3.�Interpreting Race Error Messages</h3></div></div></div> 514 <p>Helgrind's race detection algorithm collects a lot of 515 information, and tries to present it in a helpful way when a race is 516 detected. Here's an example:</p> 517 <pre class="programlisting"> 518 Thread #2 was created 519 at 0x511C08E: clone (in /lib64/libc-2.8.so) 520 by 0x4E333A4: do_clone (in /lib64/libpthread-2.8.so) 521 by 0x4E33A30: pthread_create@@GLIBC_2.2.5 (in /lib64/libpthread-2.8.so) 522 by 0x4C299D4: pthread_create@* (hg_intercepts.c:214) 523 by 0x4008F2: main (tc21_pthonce.c:86) 524 525 Thread #3 was created 526 at 0x511C08E: clone (in /lib64/libc-2.8.so) 527 by 0x4E333A4: do_clone (in /lib64/libpthread-2.8.so) 528 by 0x4E33A30: pthread_create@@GLIBC_2.2.5 (in /lib64/libpthread-2.8.so) 529 by 0x4C299D4: pthread_create@* (hg_intercepts.c:214) 530 by 0x4008F2: main (tc21_pthonce.c:86) 531 532 Possible data race during read of size 4 at 0x601070 by thread #3 533 at 0x40087A: child (tc21_pthonce.c:74) 534 by 0x4C29AFF: mythread_wrapper (hg_intercepts.c:194) 535 by 0x4E3403F: start_thread (in /lib64/libpthread-2.8.so) 536 by 0x511C0CC: clone (in /lib64/libc-2.8.so) 537 This conflicts with a previous write of size 4 by thread #2 538 at 0x400883: child (tc21_pthonce.c:74) 539 by 0x4C29AFF: mythread_wrapper (hg_intercepts.c:194) 540 by 0x4E3403F: start_thread (in /lib64/libpthread-2.8.so) 541 by 0x511C0CC: clone (in /lib64/libc-2.8.so) 542 Location 0x601070 is 0 bytes inside local var "unprotected2" 543 declared at tc21_pthonce.c:51, in frame #0 of thread 3 544 </pre> 545 <p>Helgrind first announces the creation points of any threads 546 referenced in the error message. This is so it can speak concisely 547 about threads without repeatedly printing their creation point call 548 stacks. Each thread is only ever announced once, the first time it 549 appears in any Helgrind error message.</p> 550 <p>The main error message begins at the text 551 "<code class="computeroutput">Possible data race during read</code>". At 552 the start is information you would expect to see -- address and size 553 of the racing access, whether a read or a write, and the call stack at 554 the point it was detected.</p> 555 <p>A second call stack is presented starting at the text 556 "<code class="computeroutput">This conflicts with a previous 557 write</code>". This shows a previous access which also 558 accessed the stated address, and which is believed to be racing 559 against the access in the first call stack.</p> 560 <p>Finally, Helgrind may attempt to give a description of the 561 raced-on address in source level terms. In this example, it 562 identifies it as a local variable, shows its name, declaration point, 563 and in which frame (of the first call stack) it lives. Note that this 564 information is only shown when <code class="varname">--read-var-info=yes</code> 565 is specified on the command line. That's because reading the DWARF3 566 debug information in enough detail to capture variable type and 567 location information makes Helgrind much slower at startup, and also 568 requires considerable amounts of memory, for large programs. 569 </p> 570 <p>Once you have your two call stacks, how do you find the root 571 cause of the race?</p> 572 <p>The first thing to do is examine the source locations referred 573 to by each call stack. They should both show an access to the same 574 location, or variable.</p> 575 <p>Now figure out how how that location should have been made 576 thread-safe:</p> 577 <div class="itemizedlist"><ul class="itemizedlist" type="disc"> 578 <li class="listitem"><p>Perhaps the location was intended to be protected by 579 a mutex? If so, you need to lock and unlock the mutex at both 580 access points, even if one of the accesses is reported to be a read. 581 Did you perhaps forget the locking at one or other of the 582 accesses?</p></li> 583 <li class="listitem"> 584 <p>Alternatively, perhaps you intended to use a some 585 other scheme to make it safe, such as signalling on a condition 586 variable. In all such cases, try to find a synchronisation event 587 (or a chain thereof) which separates the earlier-observed access (as 588 shown in the second call stack) from the later-observed access (as 589 shown in the first call stack). In other words, try to find 590 evidence that the earlier access "happens-before" the later access. 591 See the previous subsection for an explanation of the happens-before 592 relation.</p> 593 <p> 594 The fact that Helgrind is reporting a race means it did not observe 595 any happens-before relation between the two accesses. If 596 Helgrind is working correctly, it should also be the case that you 597 also cannot find any such relation, even on detailed inspection 598 of the source code. Hopefully, though, your inspection of the code 599 will show where the missing synchronisation operation(s) should have 600 been.</p> 601 </li> 602 </ul></div> 603 </div> 604 </div> 605 <div class="sect1" title="7.5.�Hints and Tips for Effective Use of Helgrind"> 606 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> 607 <a name="hg-manual.effective-use"></a>7.5.�Hints and Tips for Effective Use of Helgrind</h2></div></div></div> 608 <p>Helgrind can be very helpful in finding and resolving 609 threading-related problems. Like all sophisticated tools, it is most 610 effective when you understand how to play to its strengths.</p> 611 <p>Helgrind will be less effective when you merely throw an 612 existing threaded program at it and try to make sense of any reported 613 errors. It will be more effective if you design threaded programs 614 from the start in a way that helps Helgrind verify correctness. The 615 same is true for finding memory errors with Memcheck, but applies more 616 here, because thread checking is a harder problem. Consequently it is 617 much easier to write a correct program for which Helgrind falsely 618 reports (threading) errors than it is to write a correct program for 619 which Memcheck falsely reports (memory) errors.</p> 620 <p>With that in mind, here are some tips, listed most important first, 621 for getting reliable results and avoiding false errors. The first two 622 are critical. Any violations of them will swamp you with huge numbers 623 of false data-race errors.</p> 624 <div class="orderedlist"><ol class="orderedlist" type="1"> 625 <li class="listitem"> 626 <p>Make sure your application, and all the libraries it uses, 627 use the POSIX threading primitives. Helgrind needs to be able to 628 see all events pertaining to thread creation, exit, locking and 629 other synchronisation events. To do so it intercepts many POSIX 630 pthreads functions.</p> 631 <p>Do not roll your own threading primitives (mutexes, etc) 632 from combinations of the Linux futex syscall, atomic counters, etc. 633 These throw Helgrind's internal what's-going-on models 634 way off course and will give bogus results.</p> 635 <p>Also, do not reimplement existing POSIX abstractions using 636 other POSIX abstractions. For example, don't build your own 637 semaphore routines or reader-writer locks from POSIX mutexes and 638 condition variables. Instead use POSIX reader-writer locks and 639 semaphores directly, since Helgrind supports them directly.</p> 640 <p>Helgrind directly supports the following POSIX threading 641 abstractions: mutexes, reader-writer locks, condition variables 642 (but see below), semaphores and barriers. Currently spinlocks 643 are not supported, although they could be in future.</p> 644 <p>At the time of writing, the following popular Linux packages 645 are known to implement their own threading primitives:</p> 646 <div class="itemizedlist"><ul class="itemizedlist" type="disc"> 647 <li class="listitem"><p>Qt version 4.X. Qt 3.X is harmless in that it 648 only uses POSIX pthreads primitives. Unfortunately Qt 4.X 649 has its own implementation of mutexes (QMutex) and thread reaping. 650 Helgrind 3.4.x contains direct support 651 for Qt 4.X threading, which is experimental but is believed to 652 work fairly well. A side effect of supporting Qt 4 directly is 653 that Helgrind can be used to debug KDE4 applications. As this 654 is an experimental feature, we would particularly appreciate 655 feedback from folks who have used Helgrind to successfully debug 656 Qt 4 and/or KDE4 applications.</p></li> 657 <li class="listitem"> 658 <p>Runtime support library for GNU OpenMP (part of 659 GCC), at least for GCC versions 4.2 and 4.3. The GNU OpenMP runtime 660 library (<code class="filename">libgomp.so</code>) constructs its own 661 synchronisation primitives using combinations of atomic memory 662 instructions and the futex syscall, which causes total chaos since in 663 Helgrind since it cannot "see" those.</p> 664 <p>Fortunately, this can be solved using a configuration-time 665 option (for GCC). Rebuild GCC from source, and configure using 666 <code class="varname">--disable-linux-futex</code>. 667 This makes libgomp.so use the standard 668 POSIX threading primitives instead. Note that this was tested 669 using GCC 4.2.3 and has not been re-tested using more recent GCC 670 versions. We would appreciate hearing about any successes or 671 failures with more recent versions.</p> 672 </li> 673 </ul></div> 674 </li> 675 <li class="listitem"> 676 <p>Avoid memory recycling. If you can't avoid it, you must use 677 tell Helgrind what is going on via the 678 <code class="function">VALGRIND_HG_CLEAN_MEMORY</code> client request (in 679 <code class="computeroutput">helgrind.h</code>).</p> 680 <p>Helgrind is aware of standard heap memory allocation and 681 deallocation that occurs via 682 <code class="function">malloc</code>/<code class="function">free</code>/<code class="function">new</code>/<code class="function">delete</code> 683 and from entry and exit of stack frames. In particular, when memory is 684 deallocated via <code class="function">free</code>, <code class="function">delete</code>, 685 or function exit, Helgrind considers that memory clean, so when it is 686 eventually reallocated, its history is irrelevant.</p> 687 <p>However, it is common practice to implement memory recycling 688 schemes. In these, memory to be freed is not handed to 689 <code class="function">free</code>/<code class="function">delete</code>, but instead put 690 into a pool of free buffers to be handed out again as required. The 691 problem is that Helgrind has no 692 way to know that such memory is logically no longer in use, and 693 its history is irrelevant. Hence you must make that explicit, 694 using the <code class="function">VALGRIND_HG_CLEAN_MEMORY</code> client request 695 to specify the relevant address ranges. It's easiest to put these 696 requests into the pool manager code, and use them either when memory is 697 returned to the pool, or is allocated from it.</p> 698 </li> 699 <li class="listitem"> 700 <p>Avoid POSIX condition variables. If you can, use POSIX 701 semaphores (<code class="function">sem_t</code>, <code class="function">sem_post</code>, 702 <code class="function">sem_wait</code>) to do inter-thread event signalling. 703 Semaphores with an initial value of zero are particularly useful for 704 this.</p> 705 <p>Helgrind only partially correctly handles POSIX condition 706 variables. This is because Helgrind can see inter-thread 707 dependencies between a <code class="function">pthread_cond_wait</code> call and a 708 <code class="function">pthread_cond_signal</code>/<code class="function">pthread_cond_broadcast</code> 709 call only if the waiting thread actually gets to the rendezvous first 710 (so that it actually calls 711 <code class="function">pthread_cond_wait</code>). It can't see dependencies 712 between the threads if the signaller arrives first. In the latter case, 713 POSIX guidelines imply that the associated boolean condition still 714 provides an inter-thread synchronisation event, but one which is 715 invisible to Helgrind.</p> 716 <p>The result of Helgrind missing some inter-thread 717 synchronisation events is to cause it to report false positives. 718 </p> 719 <p>The root cause of this synchronisation lossage is 720 particularly hard to understand, so an example is helpful. It was 721 discussed at length by Arndt Muehlenfeld ("Runtime Race Detection 722 in Multi-Threaded Programs", Dissertation, TU Graz, Austria). The 723 canonical POSIX-recommended usage scheme for condition variables 724 is as follows:</p> 725 <pre class="programlisting"> 726 b is a Boolean condition, which is False most of the time 727 cv is a condition variable 728 mx is its associated mutex 729 730 Signaller: Waiter: 731 732 lock(mx) lock(mx) 733 b = True while (b == False) 734 signal(cv) wait(cv,mx) 735 unlock(mx) unlock(mx) 736 </pre> 737 <p>Assume <code class="computeroutput">b</code> is False most of 738 the time. If the waiter arrives at the rendezvous first, it 739 enters its while-loop, waits for the signaller to signal, and 740 eventually proceeds. Helgrind sees the signal, notes the 741 dependency, and all is well.</p> 742 <p>If the signaller arrives 743 first, <code class="computeroutput">b</code> is set to true, and the 744 signal disappears into nowhere. When the waiter later arrives, it 745 does not enter its while-loop and simply carries on. But even in 746 this case, the waiter code following the while-loop cannot execute 747 until the signaller sets <code class="computeroutput">b</code> to 748 True. Hence there is still the same inter-thread dependency, but 749 this time it is through an arbitrary in-memory condition, and 750 Helgrind cannot see it.</p> 751 <p>By comparison, Helgrind's detection of inter-thread 752 dependencies caused by semaphore operations is believed to be 753 exactly correct.</p> 754 <p>As far as I know, a solution to this problem that does not 755 require source-level annotation of condition-variable wait loops 756 is beyond the current state of the art.</p> 757 </li> 758 <li class="listitem"><p>Make sure you are using a supported Linux distribution. At 759 present, Helgrind only properly supports glibc-2.3 or later. This 760 in turn means we only support glibc's NPTL threading 761 implementation. The old LinuxThreads implementation is not 762 supported.</p></li> 763 <li class="listitem"> 764 <p>Round up all finished threads using 765 <code class="function">pthread_join</code>. Avoid 766 detaching threads: don't create threads in the detached state, and 767 don't call <code class="function">pthread_detach</code> on existing threads.</p> 768 <p>Using <code class="function">pthread_join</code> to round up finished 769 threads provides a clear synchronisation point that both Helgrind and 770 programmers can see. If you don't call 771 <code class="function">pthread_join</code> on a thread, Helgrind has no way to 772 know when it finishes, relative to any 773 significant synchronisation points for other threads in the program. So 774 it assumes that the thread lingers indefinitely and can potentially 775 interfere indefinitely with the memory state of the program. It 776 has every right to assume that -- after all, it might really be 777 the case that, for scheduling reasons, the exiting thread did run 778 very slowly in the last stages of its life.</p> 779 </li> 780 <li class="listitem"> 781 <p>Perform thread debugging (with Helgrind) and memory 782 debugging (with Memcheck) together.</p> 783 <p>Helgrind tracks the state of memory in detail, and memory 784 management bugs in the application are liable to cause confusion. 785 In extreme cases, applications which do many invalid reads and 786 writes (particularly to freed memory) have been known to crash 787 Helgrind. So, ideally, you should make your application 788 Memcheck-clean before using Helgrind.</p> 789 <p>It may be impossible to make your application Memcheck-clean 790 unless you first remove threading bugs. In particular, it may be 791 difficult to remove all reads and writes to freed memory in 792 multithreaded C++ destructor sequences at program termination. 793 So, ideally, you should make your application Helgrind-clean 794 before using Memcheck.</p> 795 <p>Since this circularity is obviously unresolvable, at least 796 bear in mind that Memcheck and Helgrind are to some extent 797 complementary, and you may need to use them together.</p> 798 </li> 799 <li class="listitem"> 800 <p>POSIX requires that implementations of standard I/O 801 (<code class="function">printf</code>, <code class="function">fprintf</code>, 802 <code class="function">fwrite</code>, <code class="function">fread</code>, etc) are thread 803 safe. Unfortunately GNU libc implements this by using internal locking 804 primitives that Helgrind is unable to intercept. Consequently Helgrind 805 generates many false race reports when you use these functions.</p> 806 <p>Helgrind attempts to hide these errors using the standard 807 Valgrind error-suppression mechanism. So, at least for simple 808 test cases, you don't see any. Nevertheless, some may slip 809 through. Just something to be aware of.</p> 810 </li> 811 <li class="listitem"> 812 <p>Helgrind's error checks do not work properly inside the 813 system threading library itself 814 (<code class="computeroutput">libpthread.so</code>), and it usually 815 observes large numbers of (false) errors in there. Valgrind's 816 suppression system then filters these out, so you should not see 817 them.</p> 818 <p>If you see any race errors reported 819 where <code class="computeroutput">libpthread.so</code> or 820 <code class="computeroutput">ld.so</code> is the object associated 821 with the innermost stack frame, please file a bug report at 822 <a class="ulink" href="http://www.valgrind.org/" target="_top">http://www.valgrind.org/</a>. 823 </p> 824 </li> 825 </ol></div> 826 </div> 827 <div class="sect1" title="7.6.�Helgrind Command-line Options"> 828 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> 829 <a name="hg-manual.options"></a>7.6.�Helgrind Command-line Options</h2></div></div></div> 830 <p>The following end-user options are available:</p> 831 <div class="variablelist"> 832 <a name="hg.opts.list"></a><dl> 833 <dt> 834 <a name="opt.track-lockorders"></a><span class="term"> 835 <code class="option">--track-lockorders=no|yes 836 [default: yes] </code> 837 </span> 838 </dt> 839 <dd><p>When enabled (the default), Helgrind performs lock order 840 consistency checking. For some buggy programs, the large number 841 of lock order errors reported can become annoying, particularly 842 if you're only interested in race errors. You may therefore find 843 it helpful to disable lock order checking.</p></dd> 844 <dt> 845 <a name="opt.history-level"></a><span class="term"> 846 <code class="option">--history-level=none|approx|full 847 [default: full] </code> 848 </span> 849 </dt> 850 <dd> 851 <p><code class="option">--history-level=full</code> (the default) causes 852 Helgrind collects enough information about "old" accesses that 853 it can produce two stack traces in a race report -- both the 854 stack trace for the current access, and the trace for the 855 older, conflicting access.</p> 856 <p>Collecting such information is expensive in both speed and 857 memory, particularly for programs that do many inter-thread 858 synchronisation events (locks, unlocks, etc). Without such 859 information, it is more difficult to track down the root 860 causes of races. Nonetheless, you may not need it in 861 situations where you just want to check for the presence or 862 absence of races, for example, when doing regression testing 863 of a previously race-free program.</p> 864 <p><code class="option">--history-level=none</code> is the opposite 865 extreme. It causes Helgrind not to collect any information 866 about previous accesses. This can be dramatically faster 867 than <code class="option">--history-level=full</code>.</p> 868 <p><code class="option">--history-level=approx</code> provides a 869 compromise between these two extremes. It causes Helgrind to 870 show a full trace for the later access, and approximate 871 information regarding the earlier access. This approximate 872 information consists of two stacks, and the earlier access is 873 guaranteed to have occurred somewhere between program points 874 denoted by the two stacks. This is not as useful as showing 875 the exact stack for the previous access 876 (as <code class="option">--history-level=full</code> does), but it is 877 better than nothing, and it is almost as fast as 878 <code class="option">--history-level=none</code>.</p> 879 </dd> 880 <dt> 881 <a name="opt.conflict-cache-size"></a><span class="term"> 882 <code class="option">--conflict-cache-size=N 883 [default: 1000000] </code> 884 </span> 885 </dt> 886 <dd> 887 <p>This flag only has any effect 888 at <code class="option">--history-level=full</code>.</p> 889 <p>Information about "old" conflicting accesses is stored in 890 a cache of limited size, with LRU-style management. This is 891 necessary because it isn't practical to store a stack trace 892 for every single memory access made by the program. 893 Historical information on not recently accessed locations is 894 periodically discarded, to free up space in the cache.</p> 895 <p>This option controls the size of the cache, in terms of the 896 number of different memory addresses for which 897 conflicting access information is stored. If you find that 898 Helgrind is showing race errors with only one stack instead of 899 the expected two stacks, try increasing this value.</p> 900 <p>The minimum value is 10,000 and the maximum is 30,000,000 901 (thirty times the default value). Increasing the value by 1 902 increases Helgrind's memory requirement by very roughly 100 903 bytes, so the maximum value will easily eat up three extra 904 gigabytes or so of memory.</p> 905 </dd> 906 </dl> 907 </div> 908 </div> 909 <div class="sect1" title="7.7.�Helgrind Client Requests"> 910 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> 911 <a name="hg-manual.client-requests"></a>7.7.�Helgrind Client Requests</h2></div></div></div> 912 <p>The following client requests are defined in 913 <code class="filename">helgrind.h</code>. See that file for exact details of their 914 arguments.</p> 915 <div class="itemizedlist"><ul class="itemizedlist" type="disc"> 916 <li class="listitem"> 917 <p><code class="function">VALGRIND_HG_CLEAN_MEMORY</code></p> 918 <p>This makes Helgrind forget everything it knows about a 919 specified memory range. This is particularly useful for memory 920 allocators that wish to recycle memory.</p> 921 </li> 922 <li class="listitem"><p><code class="function">ANNOTATE_HAPPENS_BEFORE</code></p></li> 923 <li class="listitem"><p><code class="function">ANNOTATE_HAPPENS_AFTER</code></p></li> 924 <li class="listitem"><p><code class="function">ANNOTATE_NEW_MEMORY</code></p></li> 925 <li class="listitem"><p><code class="function">ANNOTATE_RWLOCK_CREATE</code></p></li> 926 <li class="listitem"><p><code class="function">ANNOTATE_RWLOCK_DESTROY</code></p></li> 927 <li class="listitem"><p><code class="function">ANNOTATE_RWLOCK_ACQUIRED</code></p></li> 928 <li class="listitem"> 929 <p><code class="function">ANNOTATE_RWLOCK_RELEASED</code></p> 930 <p>These are used to describe to Helgrind, the behaviour of 931 custom (non-POSIX) synchronisation primitives, which it otherwise 932 has no way to understand. See comments 933 in <code class="filename">helgrind.h</code> for further 934 documentation.</p> 935 </li> 936 </ul></div> 937 </div> 938 <div class="sect1" title="7.8.�A To-Do List for Helgrind"> 939 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> 940 <a name="hg-manual.todolist"></a>7.8.�A To-Do List for Helgrind</h2></div></div></div> 941 <p>The following is a list of loose ends which should be tidied up 942 some time.</p> 943 <div class="itemizedlist"><ul class="itemizedlist" type="disc"> 944 <li class="listitem"><p>For lock order errors, print the complete lock 945 cycle, rather than only doing for size-2 cycles as at 946 present.</p></li> 947 <li class="listitem"><p>The conflicting access mechanism sometimes 948 mysteriously fails to show the conflicting access' stack, even 949 when provided with unbounded storage for conflicting access info. 950 This should be investigated.</p></li> 951 <li class="listitem"><p>Document races caused by GCC's thread-unsafe code 952 generation for speculative stores. In the interim see 953 <code class="computeroutput">http://gcc.gnu.org/ml/gcc/2007-10/msg00266.html 954 </code> 955 and <code class="computeroutput">http://lkml.org/lkml/2007/10/24/673</code>. 956 </p></li> 957 <li class="listitem"><p>Don't update the lock-order graph, and don't check 958 for errors, when a "try"-style lock operation happens (e.g. 959 <code class="function">pthread_mutex_trylock</code>). Such calls do not add any real 960 restrictions to the locking order, since they can always fail to 961 acquire the lock, resulting in the caller going off and doing Plan 962 B (presumably it will have a Plan B). Doing such checks could 963 generate false lock-order errors and confuse users.</p></li> 964 <li class="listitem"><p> Performance can be very poor. Slowdowns on the 965 order of 100:1 are not unusual. There is limited scope for 966 performance improvements. 967 </p></li> 968 </ul></div> 969 </div> 970 </div> 971 <div> 972 <br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer"> 973 <tr> 974 <td rowspan="2" width="40%" align="left"> 975 <a accesskey="p" href="cl-manual.html"><<�6.�Callgrind: a call-graph generating cache and branch prediction profiler</a>�</td> 976 <td width="20%" align="center"><a accesskey="u" href="manual.html">Up</a></td> 977 <td rowspan="2" width="40%" align="right">�<a accesskey="n" href="drd-manual.html">8.�DRD: a thread error detector�>></a> 978 </td> 979 </tr> 980 <tr><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td></tr> 981 </table> 982 </div> 983 </body> 984 </html> 985
