From: Bart Van Assche Date: Sun, 10 Oct 2010 18:57:53 +0000 (+0000) Subject: Updated DRD manual. X-Git-Tag: svn/VALGRIND_3_6_0~34 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fbf9a9135c53a47f417c0836a0a90221b9c8c7c9;p=thirdparty%2Fvalgrind.git Updated DRD manual. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@11423 --- diff --git a/drd/docs/drd-manual.xml b/drd/docs/drd-manual.xml index fcc91a3e45..b1e77ca94f 100644 --- a/drd/docs/drd-manual.xml +++ b/drd/docs/drd-manual.xml @@ -990,9 +990,11 @@ available macros 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 macros is to - tell DRD about the order of inter-thread memory accesses implemented via - atomic memory operations. + 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. See + also drd/tests/annotate_smart_pointer.cpp for an + example. @@ -1000,7 +1002,8 @@ available macros and client requests are: The macro ANNOTATE_RWLOCK_CREATE(rwlock) tells DRD that the object at address rwlock is a reader-writer synchronization object that is not a - pthread_rwlock_t synchronization object. + pthread_rwlock_t synchronization object. See + also drd/tests/annotate_rwlock.c for an example. @@ -1058,11 +1061,50 @@ available macros and client requests are: - The macro ANNOTATE_BENIGN_RACE(addr, descr) tells - DRD that any races detected on the specified address are benign and - hence should not be reported. The descr argument is - ignored but can be used to document why data races - on addr are benign. + The macro ANNOTATE_BARRIER_INIT(barrier, count, + reinitialization_allowed) tells DRD that a new barrier object + at the address barrier has been initialized, + that count threads participate in each barrier and + also whether or not barrier reinitialization without intervening + destruction should be reported as an error. See + also drd/tests/annotate_barrier.c for an example. + + + + + The macro ANNOTATE_BARRIER_DESTROY(barrier) + tells DRD that a barrier object is about to be destroyed. + + + + + The macro ANNOTATE_BARRIER_WAIT_BEFORE(barrier) + tells DRD that waiting for a barrier will start. + + + + + The macro ANNOTATE_BARRIER_WAIT_AFTER(barrier) + tells DRD that waiting for a barrier has finished. + + + + + The macro ANNOTATE_BENIGN_RACE_SIZED(addr, size, + descr) tells DRD that any races detected on the specified + address are benign and hence should not be + reported. The descr argument is ignored but can be + used to document why data races on addr are benign. + + + + + The macro ANNOTATE_BENIGN_RACE_STATIC(var, descr) + tells DRD that any races detected on the specified static variable are + benign and hence should not be reported. The descr + argument is ignored but can be used to document why data races + on var are benign. Note: this macro can only be + used in C++ programs and not in C programs. @@ -1127,17 +1169,6 @@ available macros and client requests are: - -For an example of how to use the annotations for user-defined reader-writer -synchronization objects, see -also the source file drd/tests/annotate_rwlock.c in the -Valgrind source archive. And an example of how to -use the ANNOTATE_HAPPENS_BEFORE and -the ANNOTATE_HAPPENS_AFTER annotations can be found -in the source code of the Chromium -web browser. - - Note: if you compiled Valgrind yourself, the header file <valgrind/drd.h> will have been installed in @@ -1644,46 +1675,6 @@ example. - -Assigning names to threads - - -Many applications log information about changes in internal or -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 -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 -include the assigned thread name in each log line. One possible -approach for managing thread names is as follows: - - - - Allocate a key for the pointer to the thread name through - pthread_key_create. - - - - - Just after thread creation, set the thread name through - pthread_setspecific. - - - - - In the code that generates the logging information, query the thread - name by calling pthread_getspecific. - - - - - - - - @@ -1693,18 +1684,6 @@ approach for managing thread names is as follows: DRD currently has the following limitations: - - - DRD has only been tested on Linux and Mac OS X. - - - - - Of the two POSIX threads implementations for Linux, only the - NPTL (Native POSIX Thread Library) is supported. The older - LinuxThreads library is not supported. - - DRD, just like Memcheck, will refuse to start on Linux @@ -1717,12 +1696,19 @@ approach for managing thread names is as follows: url="http://bugs.gentoo.org/214065">214065. + + + With gcc 4.4.3 and before, DRD may report data races on the C++ + class std::string in a multithreaded program. This is + a know libstdc++ issue -- see also GCC bug + 40518 + for more information. + + When address tracing is enabled, no information on atomic stores - will be displayed. This functionality is easy to add - however. Please contact the Valgrind authors if you would like - to see this functionality enabled. + will be displayed. @@ -1731,6 +1717,13 @@ approach for managing thread names is as follows: later. GCC 2.95 is not supported. + + + Of the two POSIX threads implementations for Linux, only the + NPTL (Native POSIX Thread Library) is supported. The older + LinuxThreads library is not supported. + +