|
From: <sv...@va...> - 2008-06-15 12:22:31
|
Author: bart Date: 2008-06-15 13:22:37 +0100 (Sun, 15 Jun 2008) New Revision: 8235 Log: Continued working on DRD's documentation. Modified: trunk/exp-drd/docs/drd-manual.xml Modified: trunk/exp-drd/docs/drd-manual.xml =================================================================== --- trunk/exp-drd/docs/drd-manual.xml 2008-06-15 12:21:55 UTC (rev 8234) +++ trunk/exp-drd/docs/drd-manual.xml 2008-06-15 12:22:37 UTC (rev 8235) @@ -12,42 +12,90 @@ on the Valgrind command line.</para> <sect1 id="drd-manual.overview" xreflabel="Overview"> -<title>Overview</title> +<title>Introduction</title> <para> 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. </para> <para> -The next section provides -<link linkend="drd-manual.multithreading"> -background information about multithreading</link>. +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: +<itemizedlist> + <listitem> + <para> + A data race, i.e. one or more threads access the same memory + location without sufficient locking. + </para> + </listitem> + <listitem> + <para> + Lock contention: one thread blocks the progress of another thread + by holding a lock too long. + </para> + </listitem> + <listitem> + <para> + Deadlock: two or more threads wait for each other indefinitely. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + Improper use of the POSIX threads API. + </para> + </listitem> +</itemizedlist> </para> <para> -DRD can detect two classes of errors, which are discussed in detail: +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. </para> +<para> +The remainder of this manual is organized as follows. In the next +section it is discussed which <link +linkend="drd-manual.mt-progr-models"> multithreading programming +paradigms</link> exist. +</para> + +<para>Then there is a +<link linkend="drd-manual.options">summary of command-line +options</link>. +</para> + +<para> +DRD can detect three classes of errors, which are discussed in detail: +</para> + <orderedlist> <listitem> - <para><link linkend="drd-manual.api-checks"> - Misuses of the POSIX threads API.</link></para> + <para><link linkend="drd-manual.data-races">Data races</link>.</para> </listitem> <listitem> - <para><link linkend="drd-manual.data-races"> - Data races -- accessing memory without adequate locking. - </link></para> + <para><link linkend="drd-manual.lock-contention">Lock contention</link>. + </para> </listitem> + <listitem> + <para><link linkend="drd-manual.api-checks"> + Misuse of the POSIX threads API</link>.</para> + </listitem> </orderedlist> -<para>Then there is a -<link linkend="drd-manual.options">summary of command-line -options.</link> -</para> - <para>Finally, there is a section about the current <link linkend="drd-manual.limitations">limitations</link> of DRD. @@ -56,23 +104,94 @@ </sect1> -<sect1 id="drd-manual.multithreading" xreflabel="Multithreading"> -<title>Multithreaded Programming</title> -</sect1> +<sect1 id="drd-manual.mt-progr-models" xreflabel="MT-progr-models"> +<title>Multithreaded Programming Paradigms</title> +<para> +For many applications multithreading is a necessity. There are two +reasons why the use of threads may be required: +<itemizedlist> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + To let computations run on multiple CPU cores simultaneously. This is + why many High Performance Computing (HPC) applications are multithreaded. + </para> + </listitem> +</itemizedlist> +</para> -<sect1 id="drd-manual.api-checks" xreflabel="API Checks"> -<title>Detected errors: Misuses of the POSIX threads API</title> -</sect1> +<para> +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. +<itemizedlist> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> +</itemizedlist> +</para> +<para> +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. +</para> -<sect1 id="drd-manual.data-races" xreflabel="Data Races"> -<title>Detected errors: Data Races</title> +<para> +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. +</para> + </sect1> <sect1 id="drd-manual.options" xreflabel="DRD Options"> -<title>DRD Options</title> +<title>Command Line Options</title> <para>The following end-user options are available:</para> @@ -90,8 +209,46 @@ </sect1> + +<sect1 id="drd-manual.data-races" xreflabel="Data Races"> +<title>Data Races</title> +</sect1> + + +<sect1 id="drd-manual.lock-contention" xreflabel="Lock Contention"> +<title>Lock Contention</title> +</sect1> + + +<sect1 id="drd-manual.api-checks" xreflabel="API Checks"> +<title>Misuse of the POSIX threads API</title> +</sect1> + + +<sect1 id="drd-manual.clientreqs" xreflabel="Client requests"> +<title>Client Requests</title> + +<para> +Just as for other Valgrind tools it is possible to pass information +from a client program to the DRD tool. +</para> + +</sect1> + + +<sect1 id="drd-manual.openmp" xreflabel="OpenMP"> +<title>Debugging OpenMP Programs With DRD</title> + +<para> +Just as for other Valgrind tools it is possible to pass information +from a client program to the DRD tool. +</para> + +</sect1> + + <sect1 id="drd-manual.limitations" xreflabel="Limitations"> -<title>DRD Limitations</title> +<title>Limitations</title> <para>DRD currently has the following limitations:</para> @@ -106,15 +263,15 @@ </listitem> <listitem><para>When running DRD on a PowerPC CPU, DRD will report false positives on atomic operations. See also <ulink - url="http://bugs.kde.org/show_bug.cgi?id=162354">bug 162354</ulink>. + url="http://bugs.kde.org/show_bug.cgi?id=162354">KDE bug 162354</ulink>. </para></listitem> <listitem><para>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 <ulink - url="http://bugzilla.novell.com/show_bug.cgi?id=396197">bug 396197</ulink>. + also <ulink url="http://bugzilla.novell.com/show_bug.cgi?id=396197"> + Novell bug 396197</ulink>. </para></listitem> - <listitem><para>If you compile the DRD sourcecode yourself, you need + <listitem><para>If you compile the DRD source code yourself, you need gcc 3.0 or later. gcc 2.95 is not supported.</para> </listitem> |