From: Julian Seward Date: Sun, 16 Aug 2009 22:47:02 +0000 (+0000) Subject: Update the Helgrind manual for 3.5.0. X-Git-Tag: svn/VALGRIND_3_5_0~21 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=29a513828a6f0516635ba91a707a5b32b140d464;p=thirdparty%2Fvalgrind.git Update the Helgrind manual for 3.5.0. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@10829 --- diff --git a/helgrind/docs/hg-manual.xml b/helgrind/docs/hg-manual.xml index 41ba083c3c..08ab3d5460 100644 --- a/helgrind/docs/hg-manual.xml +++ b/helgrind/docs/hg-manual.xml @@ -22,7 +22,8 @@ threading primitives. The main abstractions in POSIX pthreads are: a set of threads sharing a common address space, thread creation, thread joining, thread exit, mutexes (locks), condition variables (inter-thread event -notifications), reader-writer locks, semaphores and barriers. +notifications), reader-writer locks, spinlocks, semaphores and +barriers. Helgrind can detect three classes of errors, which are discussed in detail in the next three sections: @@ -49,14 +50,20 @@ in detail in the next three sections: timing-dependent crashes, deadlocks and other misbehaviour, and can be difficult to find by other means. -Helgrind is aware of all the pthread abstractions and tracks their -effects as accurately as it can. Currently it does not correctly -handle pthread spinlocks, although it will not object if you use them. -Adding support for spinlocks would be easy enough if the demand arises. -On x86 and amd64 platforms, it understands and partially handles -implicit locking arising from the use of the LOCK instruction prefix. +Helgrind is aware of all the pthread abstractions and tracks +their effects as accurately as it can. On x86 and amd64 platforms, it +understands and partially handles implicit locking arising from the +use of the LOCK instruction prefix. +Helgrind works best when your application uses only the POSIX +pthreads API. However, if you want to use custom threading +primitives, you can describe their behaviour to Helgrind using the +ANNOTATE_* macros defined +in helgrind.h. This functionality was added in +release 3.5.0 of Valgrind, and is considered experimental. + + Following those is a section containing @@ -107,6 +114,8 @@ are: with a not-locked mutex, an invalid mutex, or one locked by a different thread + inconsistent bindings between condition + variables and their associated mutexes invalid or duplicate initialisation of a pthread barrier initialisation of a pthread barrier on which threads @@ -968,22 +977,34 @@ unlock(mx) unlock(mx) [default: full] ]]> - When set to (the default), Helgrind - collects enough information about "old" accesses that it can produce - two stack traces in a race report -- both the stack trace for the - current access, and the trace for the older, conflicting - access. + (the default) causes + Helgrind collects enough information about "old" accesses that + it can produce two stack traces in a race report -- both the + stack trace for the current access, and the trace for the + older, conflicting access. Collecting such information is expensive in both speed and - memory. However, without it, it is very much more difficult to - track down the root causes of races. Nonetheless, you may not need - it in situations where you just want to check for the presence or - absence of races, for example, when doing regression testing of a - previously race-free program. - Setting this option to means that - Helgrind will show a full trace for one thread, and an approximation - for the other, and run faster. Setting it to - means that Helgrind will show a full trace for one thread, and - nothing for the other, and run faster again. + memory, particularly for programs that do many inter-thread + synchronisation events (locks, unlocks, etc). Without such + information, it is more difficult to track down the root + causes of races. Nonetheless, you may not need it in + situations where you just want to check for the presence or + absence of races, for example, when doing regression testing + of a previously race-free program. + is the opposite + extreme. It causes Helgrind not to collect any information + about previous accesses. This can be dramatically faster + than . + provides a + compromise between these two extremes. It causes Helgrind to + show a full trace for the later access, and approximate + information regarding the earlier access. This approximate + information consists of two stacks, and the earlier access is + guaranteed to have occurred somewhere between program points + denoted by the two stacks. This is not as useful as showing + the exact stack for the previous access + (as does), but it is + better than nothing, and it is almost as fast as + . @@ -994,6 +1015,8 @@ unlock(mx) unlock(mx) [default: 1000000] ]]> + This flag only has any effect + at . Information about "old" conflicting accesses is stored in a cache of limited size, with LRU-style management. This is necessary because it isn't practical to store a stack trace @@ -1005,10 +1028,10 @@ unlock(mx) unlock(mx) conflicting access information is stored. If you find that Helgrind is showing race errors with only one stack instead of the expected two stacks, try increasing this value. - The minimum value is 10,000 and the maximum is 20,000,000 - (twenty times the default value). Increasing the value by 1 + The minimum value is 10,000 and the maximum is 30,000,000 + (thirty times the default value). Increasing the value by 1 increases Helgrind's memory requirement by very roughly 100 - bytes, so the maximum value will easily eat up two extra + bytes, so the maximum value will easily eat up three extra gigabytes or so of memory. @@ -1097,10 +1120,36 @@ arguments. - VALGRIND_HG_CLEAN_MEMORY, - This makes Helgrind forget everything it knows about a specified memory - range. This is particularly useful for memory allocators that wish to - recycle memory. + VALGRIND_HG_CLEAN_MEMORY + This makes Helgrind forget everything it knows about a + specified memory range. This is particularly useful for memory + allocators that wish to recycle memory. + + + ANNOTATE_HAPPENS_BEFORE + + + ANNOTATE_HAPPENS_AFTER + + + ANNOTATE_NEW_MEMORY + + + ANNOTATE_RWLOCK_CREATE + + + ANNOTATE_RWLOCK_DESTROY + + + ANNOTATE_RWLOCK_ACQUIRED + + + ANNOTATE_RWLOCK_RELEASED + These are used to describe to Helgrind, the behaviour of + custom (non-POSIX) synchronisation primitives, which it otherwise + has no way to understand. See comments + in helgrind.h for further + documentation. @@ -1116,10 +1165,6 @@ arguments. some time. - Track which mutexes are associated with which - condition variables, and emit a warning if this becomes - inconsistent. - For lock order errors, print the complete lock cycle, rather than only doing for size-2 cycles as at present.