From: Bart Van Assche Date: Fri, 2 Jan 2009 13:29:32 +0000 (+0000) Subject: Polished manual. X-Git-Tag: svn/VALGRIND_3_4_0~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fad4bf3d276dfa105804d03f90e25b0e3aa7dc08;p=thirdparty%2Fvalgrind.git Polished manual. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@8892 --- diff --git a/drd/docs/drd-manual.xml b/drd/docs/drd-manual.xml index 00b1f230f8..61df72f401 100644 --- a/drd/docs/drd-manual.xml +++ b/drd/docs/drd-manual.xml @@ -52,13 +52,14 @@ reasons why the use of threads may be required: Multithreaded programs can use one or more of the following paradigms. Which paradigm is appropriate a.o. depends on the application type -- modeling concurrent activities versus HPC. +Some examples of multithreaded programming paradigms are: Locking. Data that is shared between threads may only be - accessed after a lock is obtained on the mutex associated with - the shared data item. A.o. the POSIX threads library, the Qt - library and the Boost.Thread library support this paradigm + accessed after a lock has been obtained on the mutex associated + with the shared data item. A.o. the POSIX threads library, the + Qt library and the Boost.Thread library support this paradigm directly. @@ -70,6 +71,17 @@ application type -- modeling concurrent activities versus HPC. CORBA. + + + Automatic parallelization. A compiler converts a sequential + program into a multithreaded program. The original program may + or may not contain parallelization hints. As an example, + gcc supports the OpenMP + standard from gcc version 4.3.0 on. OpenMP is a set of compiler + directives which tell a compiler how to parallelize a C, C++ or + Fortran program. + + Software Transactional Memory (STM). Data is shared between @@ -83,16 +95,6 @@ application type -- modeling concurrent activities versus HPC. support to gcc. - - - Automatic parallelization. A compiler converts a sequential - program into a multithreaded program. The original program may - or may not contain parallelization hints. As an example, - gcc supports OpenMP from - version 4.3.0 on. OpenMP is a set of compiler directives which - tell a compiler how to parallelize a C, C++ or Fortran program. - - @@ -101,7 +103,7 @@ DRD supports any combination of multithreaded programming paradigms as long as the implementation of these paradigms is based on the POSIX threads primitives. DRD however does not support programs that use e.g. Linux' futexes directly. Attempts to analyze such programs with -DRD will result in false positives. +DRD will cause DRD to report many false positives. @@ -134,12 +136,14 @@ The POSIX threads programming model is based on the following abstractions: - Atomic store and load-modify-store operations. While these - are not mentioned in the POSIX threads standard, most + Atomic store and load-modify-store operations. While these are + not mentioned in the POSIX threads standard, most microprocessors support atomic memory operations. And some compilers provide direct support for atomic memory operations through built-in functions like - e.g. __sync_fetch_and_add(). + e.g. __sync_fetch_and_add() + which is supported by both gcc + and icc. @@ -161,9 +165,9 @@ The POSIX threads programming model is based on the following abstractions: Which source code statements generate which memory accesses depends on -the memory model of the programming language being used. There is not -yet a definitive memory model for the C and C++ languagues. For a -draft memory model, see also document memory model of the programming language +being used. There is not yet a definitive memory model for the C and +C++ languagues. For a draft memory model, see also document WG21/N2338. @@ -182,8 +186,8 @@ IEEE Std 1003.1. Multithreaded Programming Problems -Depending on how multithreading is expressed in a program, one or more -of the following problems can be triggered by a multithreaded program: +Depending on which multithreading paradigm is being used in a program, +one or more of the following problems can occur: @@ -224,10 +228,10 @@ of the following problems can be triggered by a multithreaded program: Although the likelihood of the occurrence of data races can be reduced -by a disciplined programming style, a tool for automatic detection of -data races is a necessity when developing multithreaded software. DRD -can detect these, as well as lock contention and improper use of the -POSIX threads API. +through a disciplined programming style, a tool for automatic +detection of data races is a necessity when developing multithreaded +software. DRD can detect these, as well as lock contention and +improper use of the POSIX threads API. @@ -316,9 +320,9 @@ behavior of the DRD tool itself: - Print an error message if any mutex or writer lock is held - longer than the specified time (in milliseconds). This option - is intended to allow detection of lock contention. + Print an error message if any mutex or writer lock has been + held longer than the specified time (in milliseconds). This + option enables detecting lock contention. @@ -332,8 +336,8 @@ behavior of the DRD tool itself: Whether to report calls to pthread_cond_signal() and - pthread_cond_broadcast()where the mutex - associated with the signal via + pthread_cond_broadcast() where the mutex + associated with the signal through pthread_cond_wait() or pthread_cond_timed_wait()is not locked at the time the signal is sent. Sending a signal without holding @@ -365,9 +369,9 @@ behavior of the DRD tool itself: - Print an error message if a reader lock is held longer than - the specified time (in milliseconds). This option is intended - to allow detection of lock contention. + Print an error message if a reader lock has been held longer + than the specified time (in milliseconds). This option enables + detection of lock contention. @@ -390,14 +394,15 @@ behavior of the DRD tool itself: - Print stack usage at thread exit time. When there is a large - number of threads created in a program it becomes important to - limit the amount of virtual memory allocated for thread - stacks. This option makes it possible to observe the maximum - number of bytes that has been used by the client program for - thread stacks. Note: the DRD tool allocates some temporary - data on the client thread stack. The space needed for this - temporary data is not reported via this option. + Print stack usage at thread exit time. When a program creates + a large number of threads it becomes important to limit the + amount of virtual memory allocated for thread stacks. This + option makes it possible to observe how much stack memory has + been used by each thread of the the client program. Note: the + DRD tool allocates some temporary data on the client thread + stack itself. The space necessary for this temporary data must + be allocated by the client program, but is not included in the + reported stack usage. @@ -409,9 +414,9 @@ behavior of the DRD tool itself: Display the names of global, static and stack variables when a data race is reported. While this information can be very - helpful, by default it is not loaded into memory since for big - programs reading in all debug information at once may cause an - out of memory error. + helpful, it is not loaded into memory by default. This is + because for big programs reading in all debug information at + once may cause an out of memory error. @@ -421,7 +426,7 @@ behavior of the DRD tool itself: The following options are available for monitoring the behavior of the -process being analyzed with DRD: +client program: @@ -506,8 +511,8 @@ process being analyzed with DRD: Detected Errors: Data Races -DRD prints a message every time it detects a data race. You should be -aware of the following when interpreting DRD's output: +DRD prints a message every time it detects a data race. Please keep +the following in mind when interpreting DRD's output: @@ -603,23 +608,24 @@ The above report has the following meaning: your program has been compiled with debug information (-g), this call stack will include file names and line numbers. The two bottommost frames in this call stack (clone - and start_thread) show how the NPTL starts a - thread. The third frame (vg_thread_wrapper) - is added by DRD. The fourth frame - (thread_func) is interesting because it - shows the thread entry point, that is the function that has been - passed as the third argument to + and start_thread) show how the NPTL starts + a thread. The third frame + (vg_thread_wrapper) is added by DRD. The + fourth frame (thread_func) is the first + interesting line because it shows the thread entry point, that + is the function that has been passed as the third argument to pthread_create(). Next, the allocation context for the conflicting address is - displayed. For static and stack variables the allocation context - is only shown when the option + displayed. For dynamically allocated data the allocation call + stack is shown. For static variables and stack variables the + allocation context is only shown when the option --var-info=yes has been specified. Otherwise DRD will print Allocation - context: unknown for such variables. + context: unknown. @@ -664,22 +670,19 @@ The above report has the following meaning: Detected Errors: Lock Contention -Threads should be able to make progress without being blocked by other -threads. Unfortunately this is not always true. Sometimes a thread -has to wait until a mutex or reader-writer lock is unlocked by another -thread. This is called lock contention. The more -granular the locks are, the less likely lock contention will -occur. The most unfortunate situation occurs when I/O is performed -while a lock is held. +Threads must be able to make progress without being blocked for too +long by other threads. Sometimes a thread has to wait until a mutex or +reader-writer lock is unlocked by another thread. This is called +lock contention. -Lock contention causes delays and hence should be avoided. The two -command line options +Lock contention causes delays. Such delays should be as short as +possible. The two command line options --exclusive-threshold=<n> and --shared-threshold=<n> make it possible to -detect lock contention by making DRD report any lock that is held -longer than the specified threshold. An example: +detect excessive lock contention by making DRD report any lock that +has been held longer than the specified threshold. An example: - Attempt to unlock a mutex that has not been locked. + Attempts to unlock a mutex that has not been locked. - Attempt to unlock a mutex that was locked by another thread. + Attempts to unlock a mutex that was locked by another thread. - Attempt to lock a mutex of type + Attempts to lock a mutex of type PTHREAD_MUTEX_NORMAL or a spinlock recursively. @@ -749,7 +752,7 @@ output reports that the lock acquired at line 51 in source file - Calling pthread_cond_wait() with a mutex + Calling pthread_cond_wait() on a mutex that is not locked, that is locked by another thread or that has been locked recursively. @@ -757,7 +760,7 @@ output reports that the lock acquired at line 51 in source file Associating two different mutexes with a condition variable - via pthread_cond_wait(). + through pthread_cond_wait(). @@ -773,13 +776,13 @@ output reports that the lock acquired at line 51 in source file - Attempt to unlock a reader-writer lock that was not locked by + Attempts to unlock a reader-writer lock that was not locked by the calling thread. - Attempt to recursively lock a reader-writer lock exclusively. + Attempts to recursively lock a reader-writer lock exclusively. @@ -804,16 +807,6 @@ output reports that the lock acquired at line 51 in source file - -Regarding the message DRD prints about sending a signal to a condition -variable while no lock is held on the mutex associated with the -signal: DRD reports this because some calls of -pthread_cond_signal() or -pthread_cond_broadcast() while no lock is held on -the mutex associated with the condition variable introduce subtle race -conditions. - - @@ -882,7 +875,6 @@ available client requests are: VG_USERREQ__DRD_STOP_TRACE_ADDR. Do no longer trace load and store activity for the specified address range. - range. @@ -1073,7 +1065,7 @@ Allocation context: unknown. In the above output the function name gj.omp_fn.0 has been generated by gcc from the function name gj. Unfortunately the variable name -(k) is not shown as the allocation context -- it is +k is not shown as the allocation context -- it is not clear to me whether this is caused by Valgrind or whether this is caused by gcc. The most usable information in the above output is the source file name and the line number where the data race has been detected @@ -1147,7 +1139,7 @@ manual. It is essential for correct operation of DRD that there are no memory -errors like dangling pointers in the client program. Which means that +errors such as dangling pointers in the client program. Which means that it is a good idea to make sure that your program is memcheck-clean before you analyze it with DRD. It is possible however that some of the memcheck reports are caused by data races. In this case it makes @@ -1332,7 +1324,7 @@ the recursive mutex type. A condition variable allows one thread to wake up one or more other -threads. Condition variables are typically used to notify one or more +threads. Condition variables are often used to notify one or more threads about state changes of shared data. Unfortunately it is very easy to introduce race conditions by using condition variables as the only means of state information propagation. A better approach is to @@ -1341,8 +1333,8 @@ a mutex, and to use condition variables only as a thread wakeup mechanism. See also the source file drd/tests/monitor_example.cpp for an example of how to implement this concept in C++. The monitor concept -used in this example is a well known concept in computer science -- -see also Wikipedia for more information about the monitor concept. @@ -1372,9 +1364,7 @@ the timeout. A more reliable approach is as follows: CLOCK_MONOTONIC instead of CLOCK_REALTIME. You can do this via pthread_condattr_setclock(..., - CLOCK_MONOTONIC). See also - drd/tests/monitor_example.cpp - for an example. + CLOCK_MONOTONIC). @@ -1386,6 +1376,9 @@ the timeout. A more reliable approach is as follows: +See also +drd/tests/monitor_example.cpp for an +example. @@ -1501,8 +1494,7 @@ approach for managing thread names is as follows: If you have any comments, suggestions, feedback or bug reports about DRD, feel free to either post a message on the Valgrind users mailing list or to file a bug report. See also &vg-url; for more information about the -Valgrind mailing lists or about how to file a bug report. +url="&vg-url;">&vg-url; for more information.