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