From: Bart Van Assche Date: Sun, 15 Jun 2008 12:22:37 +0000 (+0000) Subject: Continued working on DRD's documentation. X-Git-Tag: svn/VALGRIND_3_4_0~471 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=88e43c7191fc95302202fcdf355a92b5c87203ec;p=thirdparty%2Fvalgrind.git Continued working on DRD's documentation. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@8235 --- diff --git a/exp-drd/docs/drd-manual.xml b/exp-drd/docs/drd-manual.xml index 049c91d7de..4f5a998e12 100644 --- a/exp-drd/docs/drd-manual.xml +++ b/exp-drd/docs/drd-manual.xml @@ -12,42 +12,90 @@ on the Valgrind command line. -Overview +Introduction DRD is a Valgrind tool for detecting errors in multithreaded C and C++ -programs that use the POSIX threading primitives, also known as -pthreads. POSIX threads is the most widely available threading library -on Unix systems. +shared-memory programs. The tool works for any program that uses the +POSIX threading primitives or a threading library built on top of the +POSIX threading primitives. POSIX threads, also known as Pthreads, is +the most widely available threading library on Unix systems. -The next section provides - -background information about multithreading. +Multithreaded programming is error prone. Depending on how multithreading is +expressed in a program, one or more of the following problems can pop up in a +multithreaded program: + + + + A data race, i.e. one or more threads access the same memory + location without sufficient locking. + + + + + Lock contention: one thread blocks the progress of another thread + by holding a lock too long. + + + + + Deadlock: two or more threads wait for each other indefinitely. + + + + + False sharing: threads on two different processors access different + variables in the same cache line frequently, causing frequent exchange + of cache lines and slowing down both threads. + + + + + Improper use of the POSIX threads API. + + + + + + +Although the likelihood of some classes of multithreaded programming +errors can be reduced by a disciplined programming style, a tool for +automatic detection of runtime threading errors is always a great help +when developing multithreaded software. -DRD can detect two classes of errors, which are discussed in detail: +The remainder of this manual is organized as follows. In the next +section it is discussed which multithreading programming +paradigms exist. + + +Then there is a +summary of command-line +options. + + + +DRD can detect three classes of errors, which are discussed in detail: - - Misuses of the POSIX threads API. + Data races. + + + Lock contention. + - - Data races -- accessing memory without adequate locking. - + + Misuse of the POSIX threads API. -Then there is a -summary of command-line -options. - - Finally, there is a section about the current limitations of DRD. @@ -56,23 +104,94 @@ of DRD. - -Multithreaded Programming - + +Multithreaded Programming Paradigms + +For many applications multithreading is a necessity. There are two +reasons why the use of threads may be required: + + + + To model concurrent activities. Managing the state of one activity + per thread is a simpler programming model than multiplexing the states + of multiple activities in a single thread. This is why most server and + embedded software is multithreaded. + + + + + To let computations run on multiple CPU cores simultaneously. This is + why many High Performance Computing (HPC) applications are multithreaded. + + + + - -Detected errors: Misuses of the POSIX threads API - + +Multithreaded programs can be developed by using one or more of the +following paradigms. Which paradigm is appropriate also depends on the +application type -- modeling concurrent activities versus HPC. + + + + Locking: data that is shared between threads may only be accessed + after a lock is obtained on the mutex(es) associated with the + shared data item. The POSIX threads library, the Qt library + and the Boost.Thread library support this paradigm directly. + + + + + Message passing: any data that has to be passed from one thread to + another is sent via a message to that other thread. No data is explicitly + shared. Well known implementations of the message passing paradigm are + MPI and CORBA. + + + + + Software Transactional Memory (STM). Just like the locking + paradigm, with STM data is shared between threads. While the + locking paradigm requires that all associated mutexes are locked + before the shared data is accessed, with the STM paradigm after + each transaction it is verified whether there were conflicting + transactions. If there were conflicts, the transaction is aborted, + otherwise it is committed. This is a so-called optimistic + approach. Not all C, C++ and Fortran compilers already support STM. + + + + + Automatic parallelization: a compiler converts a sequential + program into a multithreaded program. The original program can + contain parallelization hints. As an example, gcc version 4.3.0 + and later supports OpenMP, a set of standardized compiler + directives which tell a compiler how to parallelize a C, C++ or + Fortran program. + + + + + +Next to the above paradigms, most CPU instruction sets support atomic +memory accesses. Such operations are the most efficient way to update +a single value on a system with multiple CPU cores. + + + +DRD supports any combination of multithreaded programming paradigms +and atomic memory accesses, as long as the libraries that implement +the paradigms are based on POSIX threads. Direct use of e.g. Linux' +futexes is not recognized by DRD and will result in false positives. + - -Detected errors: Data Races -DRD Options +Command Line Options The following end-user options are available: @@ -90,8 +209,46 @@ DRD: + + +Data Races + + + + +Lock Contention + + + + +Misuse of the POSIX threads API + + + + +Client Requests + + +Just as for other Valgrind tools it is possible to pass information +from a client program to the DRD tool. + + + + + + +Debugging OpenMP Programs With DRD + + +Just as for other Valgrind tools it is possible to pass information +from a client program to the DRD tool. + + + + + -DRD Limitations +Limitations DRD currently has the following limitations: @@ -106,15 +263,15 @@ DRD: When running DRD on a PowerPC CPU, DRD will report false positives on atomic operations. See also bug 162354. + url="http://bugs.kde.org/show_bug.cgi?id=162354">KDE bug 162354. DRD, just like memcheck, will refuse to start on Linux distributions where all symbol information has been removed from ld.so. This is e.g. the case for openSUSE 10.3 -- see - also bug 396197. + also + Novell bug 396197. - If you compile the DRD sourcecode yourself, you need + If you compile the DRD source code yourself, you need gcc 3.0 or later. gcc 2.95 is not supported.