From: Nicholas Nethercote Date: Fri, 7 Aug 2009 05:23:31 +0000 (+0000) Subject: Minor formatting and grammar changes to the DRD manual chapter, to make it X-Git-Tag: svn/VALGRIND_3_5_0~115 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=ec5c7aa4e59cbb1842e0faca1830ad2f347efb61;p=thirdparty%2Fvalgrind.git Minor formatting and grammar changes to the DRD manual chapter, to make it consistent with the rest of the documentation. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@10735 --- diff --git a/drd/docs/drd-manual.xml b/drd/docs/drd-manual.xml index 996e121cf8..01690fe178 100644 --- a/drd/docs/drd-manual.xml +++ b/drd/docs/drd-manual.xml @@ -48,13 +48,13 @@ There are two possible reasons for using multithreading in a program: Multithreaded programs can use one or more of the following programming -paradigms. Which paradigm is appropriate depends a.o. on the application type. +paradigms. Which paradigm is appropriate depends e.g. on the application type. Some examples of multithreaded programming paradigms are: Locking. Data that is shared over threads is protected from concurrent - accesses via locking. A.o. the POSIX threads library, the Qt library + accesses via locking. E.g. the POSIX threads library, the Qt library and the Boost.Thread library support this paradigm directly. @@ -85,10 +85,9 @@ Some examples of multithreaded programming paradigms are: threads is updated via transactions. After each transaction it is verified whether there were any conflicting transactions. If there were conflicts, the transaction is aborted, otherwise it is committed. This - is a so-called optimistic approach. There is a prototype of the Intel C - Compiler (icc) available that supports - STM. Research about the addition of STM support - to GCC is ongoing. + is a so-called optimistic approach. There is a prototype of the Intel C++ + Compiler available that supports STM. Research about the addition of + STM support to GCC is ongoing. @@ -254,7 +253,7 @@ determined by: The combination of program order and synchronization order is called the happens-before relationship. This concept was first -defined by S. Adve e.a. in the paper Detecting data races on weak +defined by S. Adve et al in the paper Detecting data races on weak memory systems, ACM SIGARCH Computer Architecture News, v.19 n.3, p.234-243, May 1991. @@ -330,7 +329,7 @@ behavior of the DRD tool itself: - Controls whether DRD detects data races on stack + Controls whether DRD detects data races on stack variables. Verifying stack variables is disabled by default because most programs do not share stack variables over threads. @@ -371,11 +370,11 @@ behavior of the DRD tool itself: Whether to report calls to - pthread_cond_signal() and - pthread_cond_broadcast() where the mutex + pthread_cond_signal and + pthread_cond_broadcast where the mutex associated with the signal through - pthread_cond_wait() or - pthread_cond_timed_wait()is not locked at + pthread_cond_wait or + pthread_cond_timed_waitis not locked at the time the signal is sent. Sending a signal without holding a lock on the associated mutex is a common programming error which can cause subtle race conditions and unpredictable @@ -635,8 +634,9 @@ The above report has the following meaning: Next, the call stack of the conflicting access is displayed. If - your program has been compiled with debug information (-g), this - call stack will include file names and line numbers. The two + your program has been compiled with debug information + (), 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 @@ -644,7 +644,7 @@ The above report has the following meaning: 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(). + pthread_create. @@ -782,7 +782,7 @@ output reports that the lock acquired at line 51 in source file - Calling pthread_cond_wait() on 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. @@ -790,7 +790,7 @@ output reports that the lock acquired at line 51 in source file Associating two different mutexes with a condition variable - through pthread_cond_wait(). + through pthread_cond_wait. @@ -865,14 +865,14 @@ output reports that the lock acquired at line 51 in source file Just as for other Valgrind tools it is possible to let a client program interact with the DRD tool through client requests. In addition to the -client requests several macro's have been defined that allow to use the +client requests several macros have been defined that allow to use the client requests in a convenient way. The interface between client programs and the DRD tool is defined in the header file <valgrind/drd.h>. The -available macro's and client requests are: +available macros and client requests are: @@ -896,7 +896,7 @@ available macro's and client requests are: - The macro's DRD_IGNORE_VAR(x), + The macros DRD_IGNORE_VAR(x), ANNOTATE_TRACE_MEMORY(&x) and the corresponding client request VG_USERREQ__DRD_START_SUPPRESSION. Some applications contain intentional races. There exist e.g. applications @@ -917,7 +917,7 @@ available macro's and client requests are: - The macro's DRD_TRACE_VAR(x), + The macros DRD_TRACE_VAR(x), ANNOTATE_TRACE_MEMORY(&x) and the corresponding client request VG_USERREQ__DRD_START_TRACE_ADDR. Trace all @@ -947,7 +947,7 @@ available macro's and client requests are: the next access to the variable at the specified address should be considered to have happened after the access just before the latest ANNOTATE_HAPPENS_BEFORE(addr) annotation that - references the same variable. The purpose of these two macro's is to + references the same variable. The purpose of these two macros is to tell DRD about the order of inter-thread memory accesses implemented via atomic memory operations. @@ -1104,12 +1104,12 @@ GNOME applications use the threading primitives provided by the gthread libraries. These libraries are built on top of POSIX threads, and hence are directly supported by DRD. Please keep in mind that you have to call -g_thread_init() before creating any threads, or +g_thread_init before creating any threads, or DRD will report several data races on glib functions. See also the GLib Reference Manual for more information about -g_thread_init(). +g_thread_init. @@ -1303,7 +1303,7 @@ information for two purposes: To know where the scope ends of POSIX objects that have not been destroyed explicitly. It is e.g. not required by the POSIX threads standard to call - pthread_mutex_destroy() before freeing the + pthread_mutex_destroy before freeing the memory in which a mutex object resides. @@ -1322,8 +1322,8 @@ information for two purposes: It is essential for correct operation of DRD that the tool knows about memory allocation and deallocation events. When analyzing a client program with DRD that uses a custom memory allocator, either instrument the custom -memory allocator with the VALGRIND_MALLOCLIKE_BLOCK() -and VALGRIND_FREELIKE_BLOCK() macro's or disable the +memory allocator with the VALGRIND_MALLOCLIKE_BLOCK +and VALGRIND_FREELIKE_BLOCK macros or disable the custom memory allocator. @@ -1346,14 +1346,14 @@ manual. It is essential for correct operation of DRD that there are no memory 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 +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 -sense to run DRD before memcheck. +the Memcheck reports are caused by data races. In this case it makes +sense to run DRD before Memcheck. -So which tool should be run first ? In case both DRD and memcheck +So which tool should be run first? In case both DRD and Memcheck complain about a program, a possible approach is to run both tools alternatingly and to fix as many errors as possible after each run of each tool until none of the two tools prints any more error messages. @@ -1389,7 +1389,7 @@ effect on the execution time of client programs are as follows: Most applications will run between 20 and 50 times slower under DRD than a native single-threaded run. The slowdown will be most - noticeable for applications which perform very much mutex lock / + noticeable for applications which perform frequent mutex lock / unlock operations. @@ -1438,7 +1438,7 @@ The following information may be helpful when using DRD: std::cout. Doing so would not only generate multiple data race reports, it could also result in output from several threads getting mixed up. Either use - printf() or do the following: + printf or do the following: Derive a class from std::ostreambuf @@ -1480,7 +1480,7 @@ The following information may be helpful when using DRD: The Single UNIX Specification version two defines the following four mutex types (see also the documentation of pthread_mutexattr_settype()): +url="http://www.opengroup.org/onlinepubs/007908799/xsh/pthread_mutexattr_settype.html">pthread_mutexattr_settype): @@ -1547,11 +1547,11 @@ concept. -pthread_cond_timedwait() and timeouts +<function>pthread_cond_timedwait</function> and timeouts Historically the function -pthread_cond_timedwait() only allowed the +pthread_cond_timedwait only allowed the specification of an absolute timeout, that is a timeout independent of the time when this function was called. However, almost every call to this function expresses a relative timeout. This typically happens by @@ -1564,8 +1564,8 @@ the timeout. A more reliable approach is as follows: When initializing a condition variable through - pthread_cond_init(), specify that the timeout of - pthread_cond_timedwait() will use the clock + pthread_cond_init, specify that the timeout of + pthread_cond_timedwait will use the clock CLOCK_MONOTONIC instead of CLOCK_REALTIME. You can do this via pthread_condattr_setclock(..., @@ -1574,7 +1574,7 @@ the timeout. A more reliable approach is as follows: - When calling pthread_cond_timedwait(), pass + When calling pthread_cond_timedwait, pass the sum of clock_gettime(CLOCK_MONOTONIC) and a relative timeout as the third argument. @@ -1597,7 +1597,7 @@ external state to a file. When analyzing log files of a multithreaded application it can be very convenient to know which thread logged which information. One possible approach is to identify threads in logging output by including the result of -pthread_self() in every log line. However, this approach +pthread_self in every log line. However, this approach has two disadvantages: there is no direct relationship between these values and the source code and these values can be different in each run. A better approach is to assign a brief name to each thread and to @@ -1607,19 +1607,19 @@ approach for managing thread names is as follows: Allocate a key for the pointer to the thread name through - pthread_key_create(). + pthread_key_create. Just after thread creation, set the thread name through - pthread_setspecific(). + pthread_setspecific. In the code that generates the logging information, query the thread - name by calling pthread_getspecific(). + name by calling pthread_getspecific. @@ -1639,9 +1639,7 @@ approach for managing thread names is as follows: - DRD has only been tested on the Linux operating system, and not - on any of the other operating systems supported by - Valgrind. + DRD has only been tested on Linux and Mac OS X. @@ -1653,12 +1651,12 @@ approach for managing thread names is as follows: - DRD, just like memcheck, will refuse to start on Linux + DRD, just like Memcheck, will refuse to start on Linux distributions where all symbol information has been removed from - ld.so. This is a.o. the case for the PPC editions of openSUSE - and Gentoo. You will have to install the glibc debuginfo package - on these platforms before you can use DRD. See also openSUSE bug - + ld.so. This is e.g. the case for the PPC editions + of openSUSE and Gentoo. You will have to install the glibc debuginfo + package on these platforms before you can use DRD. See also openSUSE + bug 396197 and Gentoo bug 214065.