From: Julian Seward Date: Fri, 9 Nov 2007 23:59:49 +0000 (+0000) Subject: Rename in the manual. X-Git-Tag: svn/VALGRIND_3_3_0~159 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=969c77b26727cba5870408a50f84a28238ce9827;p=thirdparty%2Fvalgrind.git Rename in the manual. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@7130 --- diff --git a/helgrind/docs/hg-manual.xml b/helgrind/docs/hg-manual.xml index 5090cfc2ee..73dde8c69d 100644 --- a/helgrind/docs/hg-manual.xml +++ b/helgrind/docs/hg-manual.xml @@ -3,20 +3,20 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - - Thrcheck: a thread error detector + + Helgrind: a thread error detector To use this tool, you must specify ---tool=thrcheck on the Valgrind +--tool=helgrind on the Valgrind command line. - + Overview -Thrcheck is a Valgrind tool for detecting synchronisation errors +Helgrind is a Valgrind tool for detecting synchronisation errors in C, C++ and Fortran programs that use the POSIX pthreads threading primitives. @@ -25,7 +25,7 @@ sharing a common address space, thread creation, thread joinage, thread exit, mutexes (locks), condition variables (inter-thread event notifications), reader-writer locks, and semaphores. -Thrcheck is aware of all these abstractions and tracks their +Helgrind is aware of all these abstractions and tracks their effects as accurately as it can. Currently it does not correctly handle pthread barriers and pthread spinlocks, although it will not object if you use them. On x86 and amd64 platforms, it understands @@ -33,38 +33,38 @@ and partially handles implicit locking arising from the use of the LOCK instruction prefix. -Thrcheck can detect three classes of errors, which are discussed +Helgrind can detect three classes of errors, which are discussed in detail in the next three sections: - + Misuses of the POSIX pthreads API. - + Potential deadlocks arising from lock ordering problems. - + Data races -- accessing memory without adequate locking. Following those is a section containing - -hints and tips on how to get the best out of Thrcheck. + +hints and tips on how to get the best out of Helgrind. Then there is a -summary of command-line +summary of command-line options. Finally, there is -a brief summary of areas in which Thrcheck +a brief summary of areas in which Helgrind could be improved. @@ -73,10 +73,10 @@ could be improved. - + Detected errors: Misuses of the POSIX pthreads API -Thrcheck intercepts calls to many POSIX pthreads functions, and +Helgrind intercepts calls to many POSIX pthreads functions, and is therefore able to report on various common problems. Although these are unglamourous errors, their presence can lead to undefined program behaviour and hard-to-find bugs later in execution. The @@ -114,26 +114,26 @@ library. where the error was detected. They may also contain auxiliary stack traces giving additional information. In particular, most errors relating to mutexes will also tell you where that mutex first came to -Thrcheck's attention (the "was first observed +Helgrind's attention (the "was first observed at" part), so you have a chance of figuring out which mutex it is referring to. For example: -Thrcheck has a way of summarising thread identities, as +Helgrind has a way of summarising thread identities, as evidenced here by the text "Thread #1". This is so that it can speak about threads and sets of threads without overwhelming you with details. See -below +below for more information on interpreting error messages. @@ -141,14 +141,14 @@ for more information on interpreting error messages. - + Detected errors: Inconsistent Lock Orderings In this section, and in general, to "acquire" a lock simply means to lock that lock, and to "release" a lock means to unlock it. -Thrcheck monitors the order in which threads acquire locks. +Helgrind monitors the order in which threads acquire locks. This allows it to detect potential deadlocks which could arise from the formation of cycles of locks. Detecting such inconsistencies is useful because, whilst actual deadlocks are fairly obvious, potential @@ -176,43 +176,43 @@ follows. -Thrcheck builds a directed graph indicating the order in which +Helgrind builds a directed graph indicating the order in which locks have been acquired in the past. When a thread acquires a new lock, the graph is updated, and then checked to see if it now contains a cycle. The presence of a cycle indicates a potential deadlock involving the locks in the cycle. In simple situations, where the cycle only contains two locks, -Thrcheck will show where the required order was established: +Helgrind will show where the required order was established: When there are more than two locks in the cycle, the error is -equally serious. However, at present Thrcheck does not show the locks +equally serious. However, at present Helgrind does not show the locks involved, so as to avoid flooding you with information. That could be fixed in future. For example, here is a an example involving a cycle of five locks from a naive implementation the famous Dining Philosophers problem -(see thrcheck/tests/tc14_laog_dinphils.c). -In this case Thrcheck has detected that all 5 philosophers could +(see helgrind/tests/tc14_laog_dinphils.c). +In this case Helgrind has detected that all 5 philosophers could simultaneously pick up their left fork and then deadlock whilst waiting to pick up their right forks. @@ -222,7 +222,7 @@ Thread #6: lock order "0x6010C0 before 0x601160" violated - + Detected errors: Data Races A data race happens, or could happen, when two threads @@ -232,12 +232,12 @@ obscure timing dependent bugs. Ensuring programs are race-free is one of the central difficulties of threaded programming. Reliably detecting races is a difficult problem, and most -of Thrcheck's internals are devoted to do dealing with it. +of Helgrind's internals are devoted to do dealing with it. As a consequence this section is somewhat long and involved. We begin with a simple example. - + A Simple Data Race About the simplest possible example of a race is as follows. In @@ -269,7 +269,7 @@ stop var being updated simultaneously by both threads. A correct program would protect var with a lock of type pthread_mutex_t, which is acquired -before each access and released afterwards. Thrcheck's output for +before each access and released afterwards. Helgrind's output for this program is: sections below explain them. Here we merely note their presence: - Thrcheck maintains some kind of state machine for the + Helgrind maintains some kind of state machine for the memory location in question, hence the "Old state:" and "New state:" lines. - Thrcheck keeps track of which threads have accessed + Helgrind keeps track of which threads have accessed the location: "threads #1, #2". Before printing the main error message, it prints the creation points of these two threads, so you can see which threads it is referring to. - Thrcheck tries to provide an explaination of why the + Helgrind tries to provide an explaination of why the race exists: "Location 0x601034 has never been protected by any lock". Understanding the memory state machine is central to -understanding Thrcheck's race-detection algorithm. The next three +understanding Helgrind's race-detection algorithm. The next three subsections explain this. - -Thrcheck's Memory State Machine + +Helgrind's Memory State Machine -Thrcheck tracks the state of every byte of memory used by your +Helgrind tracks the state of every byte of memory used by your program. There are a number of states, but only three are interesting: @@ -355,7 +355,7 @@ interesting: Shared-Modified: memory in this state is regarded as shared by multiple threads, at least one of which has written to it. All participating threads must hold at least one lock in common when - accessing the memory. If no such lock exists, Thrcheck reports a + accessing the memory. If no such lock exists, Helgrind reports a race error. @@ -375,14 +375,14 @@ shared-readonly by both threads. This same thread adds one to the value it has and stores it back in var. This causes another state -change, this time to the shared-modified state. Because Thrcheck has +change, this time to the shared-modified state. Because Helgrind has also been tracking which threads hold which locks, it can see that var is in shared-modified state but no lock has been used to consistently protect it. Hence a race is reported exactly at the transition from shared-readonly to shared-modified. -The essence of the algorithm is this. Thrcheck keeps track of +The essence of the algorithm is this. Helgrind keeps track of each memory location that has been accessed by more than one thread. For each such location it incrementally infers the set of locks which have consistently been used to protect that location. If the @@ -396,11 +396,11 @@ Sobalvarro and Thomas Anderson, ACM Transactions on Computer Systems, 15(4):391-411, November 1997). Lockset inference has since been widely implemented, studied and -extended. Thrcheck incorporates several refinements aimed at avoiding +extended. Helgrind incorporates several refinements aimed at avoiding the high false error rate that naive versions of the algorithm suffer from. A -summary of the complete -algorithm used by Thrcheck is presented below. First, however, +summary of the complete +algorithm used by Helgrind is presented below. First, however, it is important to understand details of transitions pertaining to the Exclusive-ownership state. @@ -408,7 +408,7 @@ Exclusive-ownership state. - + Transfers of Exclusive Ownership Between Threads As presented, the algorithm is far too strict. It reports many @@ -460,7 +460,7 @@ after the parent initialises buf, and before the parent reads the results from buf. -To model this, Thrcheck allows the child to steal, from the +To model this, Helgrind allows the child to steal, from the parent, exclusive ownership of any memory exclusively owned by the parent before the pthread_create call. Similarly, once the parent's pthread_join call returns, it can steal back ownership of memory @@ -479,8 +479,8 @@ reported. segments" in "Runtime Checking of Multithreaded Applications with Visual Threads" (Jerry J. Harrow, Jr, Proceedings of the 7th International SPIN Workshop on Model Checking of Software Stanford, -California, USA, August 2000, LNCS 1885, pp331--342). Thrcheck -implements an extended version of it. Specifically, Thrcheck allows +California, USA, August 2000, LNCS 1885, pp331--342). Helgrind +implements an extended version of it. Specifically, Helgrind allows transfer of exclusive ownership in the following situations: @@ -511,7 +511,7 @@ transfer of exclusive ownership in the following situations: - + Restoration of Exclusive Ownership Another common idiom is to partition the lifetime of the program @@ -543,7 +543,7 @@ var += 4; /* no lock used */ ]]> This program is correct, but using only the mechanisms described -so far, Thrcheck would report an error at +so far, Helgrind would report an error at var += 4. This is because, by that point, var is marked as being in the state "shared-modified and protected by the @@ -552,10 +552,10 @@ without locking. Really, what we want is for var to return to the parent thread's exclusive ownership after the child thread has exited. -To make this possible, for every memory location Thrcheck also keeps +To make this possible, for every memory location Helgrind also keeps track of all the threads that have accessed that location -- its threadset. When a thread Tquitter joins back to Tstayer, -Thrcheck examines the locksets of all memory in shared-modified or +Helgrind examines the locksets of all memory in shared-modified or shared-readable state. In each such lockset, if Tquitter is mentioned, it is removed and replaced by Tstayer. If, as a result, a lockset becomes a singleton set containing Tstayer, then the @@ -568,7 +568,7 @@ parent after the child exits. More generally, when a group of threads merges back to a single thread via a cascade of pthread_join calls, any memory shared by the group (or a subset of it) ends up being owned exclusively by the sole -surviving thread. This significantly enhances Thrcheck's flexibility, +surviving thread. This significantly enhances Helgrind's flexibility, since it means that each memory location may make arbitrarily many transitions between exclusive and shared ownership. Furthermore, a different lock may protect the location during each period of shared @@ -578,22 +578,22 @@ ownership. - + A Summary of the Race Detection Algorithm -Thrcheck looks for memory locations which are accessed by more -than one thread. For each such location, Thrcheck records which of +Helgrind looks for memory locations which are accessed by more +than one thread. For each such location, Helgrind records which of the program's locks were held by the accessing thread at the time of each access. The hope is to discover that there is indeed at least one lock which is consistently used by all threads to protect that location. If no such lock can be found, then there is apparently no consistent locking strategy being applied for that location, and so a -possible data race might result. Thrcheck accordingly reports an +possible data race might result. Helgrind accordingly reports an error. In practice this discipline is far too simplistic, and is unusable since it reports many races in some widely used and -known-correct programming disciplines. Thrcheck's checking therefore +known-correct programming disciplines. Helgrind's checking therefore incorporates many refinements to this basic idea, and can be summarised as follows: @@ -630,7 +630,7 @@ monitored: All memory accesses are intercepted and monitored. -By observing the above events, Thrcheck can infer certain +By observing the above events, Helgrind can infer certain aspects of the program's locking discipline. Programs which adhere to the following rules are considered to be acceptable: @@ -677,7 +677,7 @@ However, two exemptions apply: on that same semaphore - This refinement allows Thrcheck to correctly track the ownership + This refinement allows Helgrind to correctly track the ownership state of inter-thread buffers used in the worker-thread and worker-thread-pool concurrent programming idioms (styles). @@ -704,23 +704,23 @@ for each memory location are tracked at 8-bit granularity. This means the algorithm is precise even for 16- and 8-bit memory accesses. -Thrcheck correctly handles reader-writer locks in this +Helgrind correctly handles reader-writer locks in this framework. Locations shared between multiple threads can be protected during reads by locks held in either read-mode or write-mode, but can only be protected during writes by locks held in write-mode. Normal POSIX mutexes are treated as if they are reader-writer locks which are only ever held in write-mode. -Thrcheck correctly handles POSIX mutexes for which recursive +Helgrind correctly handles POSIX mutexes for which recursive locking is allowed. -Thrcheck partially correctly handles x86 and amd64 memory access +Helgrind partially correctly handles x86 and amd64 memory access instructions preceded by a LOCK prefix. Writes are correctly handled, by pretending that the LOCK prefix implies acquisition and release of a magic "bus hardware lock" mutex before and after the instruction. This unfortunately requires subsequent reads from such locations to also use a LOCK prefix, which is not required by the real hardware. -Thrcheck does not offer any equivalent handling for atomic sequences +Helgrind does not offer any equivalent handling for atomic sequences on PowerPC/POWER platforms created by the use of lwarx/stwcx instructions. @@ -728,10 +728,10 @@ instructions. - + Interpreting Race Error Messages -Thrcheck's race detection algorithm collects a lot of +Helgrind's race detection algorithm collects a lot of information, and tries to present it in a helpful way when a race is detected. Here's an example: @@ -740,7 +740,7 @@ Thread #2 was created at 0x510548E: clone (in /lib64/libc-2.5.so) by 0x4E2F305: do_clone (in /lib64/libpthread-2.5.so) by 0x4E2F7C5: pthread_create@@GLIBC_2.2.5 (in /lib64/libpthread-2.5.so) - by 0x4C23870: pthread_create@* (tc_intercepts.c:198) + by 0x4C23870: pthread_create@* (hg_intercepts.c:198) by 0x400CEF: main (tc17_sembar.c:195) // And the same for threads #3, #4 and #5 -- omitted for conciseness @@ -748,23 +748,23 @@ Thread #2 was created Possible data race during read of size 4 at 0x602174 at 0x400BE5: gomp_barrier_wait (tc17_sembar.c:122) by 0x400C44: child (tc17_sembar.c:161) - by 0x4C25DF7: mythread_wrapper (tc_intercepts.c:178) + by 0x4C25DF7: mythread_wrapper (hg_intercepts.c:178) by 0x4E2F09D: start_thread (in /lib64/libpthread-2.5.so) by 0x51054CC: clone (in /lib64/libc-2.5.so) Old state: shared-modified by threads #2, #3, #4, #5 New state: shared-modified by threads #2, #3, #4, #5 Reason: this thread, #2, holds no consistent locks Last consistently used lock for 0x602174 was first observed - at 0x4C25D01: pthread_mutex_init (tc_intercepts.c:326) + at 0x4C25D01: pthread_mutex_init (hg_intercepts.c:326) by 0x4009E4: gomp_barrier_init (tc17_sembar.c:46) by 0x400CBC: main (tc17_sembar.c:192) ]]> -Thrcheck first announces the creation points of any threads +Helgrind first announces the creation points of any threads referenced in the error message. This is so it can speak concisely about threads and sets of threads without repeatedly printing their creation point call stacks. Each thread is only ever announced once, -the first time it appears in any Thrcheck error message. +the first time it appears in any Helgrind error message. The main error message begins at the text "Possible data race during read". @@ -779,7 +779,7 @@ making the access in question (thread #2, here) does not hold any locks in common with those held during all previous accesses to the location -- "no consistent locks", in other words. -Finally, Thrcheck shows the lock which has protected this +Finally, Helgrind shows the lock which has protected this location in all previous accesses. (If there is more than one, only one is shown). This can be a useful hint, because it typically shows the lock that the programmers intended to use to protect the location, @@ -814,7 +814,7 @@ Possible data race during read ... The location is shared by 3 threads, all of which have been reading and writing it while (as required) holding at least one lock in common. Now it is being read without that lock being held. In the -"Last consistently used lock" part, Thrcheck offers its best guess as +"Last consistently used lock" part, Helgrind offers its best guess as to the identity of the lock that should have been used. -Also, this message implies that Thrcheck did not see any +Also, this message implies that Helgrind did not see any synchronisation event between threads #4 and #5 that would have allowed #5 to acquire exclusive ownership from #4. See -above +above for a discussion of transfers of exclusive ownership states between threads. @@ -849,20 +849,20 @@ threads. - -Hints and Tips for Effective Use of Thrcheck + +Hints and Tips for Effective Use of Helgrind -Thrcheck can be very helpful in finding and resolving +Helgrind can be very helpful in finding and resolving threading-related problems. Like all sophisticated tools, it is most effective when you understand how to play to its strengths. -Thrcheck will be less effective when you merely throw an +Helgrind will be less effective when you merely throw an existing threaded program at it and try to make sense of any reported errors. It will be more effective if you design threaded programs -from the start in a way that helps Thrcheck verify correctness. The +from the start in a way that helps Helgrind verify correctness. The same is true for finding memory errors with Memcheck, but applies more here, because thread checking is a harder problem. Consequently it is -much easier to write a correct program for which Thrcheck falsely +much easier to write a correct program for which Helgrind falsely reports (threading) errors than it is to write a correct program for which Memcheck falsely reports (memory) errors. @@ -876,23 +876,23 @@ of false data-race errors. Make sure your application, and all the libraries it uses, - use the POSIX threading primitives. Thrcheck needs to be able to + use the POSIX threading primitives. Helgrind needs to be able to see all events pertaining to thread creation, exit, locking and other syncronisation events. To do so it intercepts many POSIX pthread_ functions. Do not roll your own threading primitives (mutexes, etc) from combinations of the Linux futex syscall, counters and wotnot. - These throw Thrcheck's internal what's-going-on models way off + These throw Helgrind's internal what's-going-on models way off course and will give bogus results. Also, do not reimplement existing POSIX abstractions using other POSIX abstractions. For example, don't build your own semaphore routines or reader-writer locks from POSIX mutexes and condition variables. Instead use POSIX reader-writer locks and - semaphores directly, since Thrcheck supports them directly. + semaphores directly, since Helgrind supports them directly. - Thrcheck directly supports the following POSIX threading + Helgrind directly supports the following POSIX threading abstractions: mutexes, reader-writer locks, condition variables (but see below), and semaphores. Currently spinlocks and barriers are not supported, although they could be in future. A prototype @@ -904,7 +904,7 @@ of false data-race errors. Qt version 4.X. Qt 3.X is fine, but not 4.X. - Thrcheck contains partial direct support for Qt 4.X threading, + Helgrind contains partial direct support for Qt 4.X threading, but this is not yet in a usable state. Assistance from folks knowledgeable in Qt 4 threading internals would be appreciated. @@ -912,28 +912,28 @@ of false data-race errors. Runtime support library for GNU OpenMP (part of GCC), at least GCC versions 4.2 and 4.3. With some minor effort of modifying the GNU OpenMP runtime support sources, it is - possible to use Thrcheck on GNU OpenMP compiled codes. Please + possible to use Helgrind on GNU OpenMP compiled codes. Please contact the Valgrind authors for details. Avoid memory recycling. If you can't avoid it, you must use - tell Thrcheck what is going on via the VALGRIND_HG_CLEAN_MEMORY + tell Helgrind what is going on via the VALGRIND_HG_CLEAN_MEMORY client request - (in thrcheck.h). + (in helgrind.h). - Thrcheck is aware of standard memory allocation and + Helgrind is aware of standard memory allocation and deallocation that occurs via malloc/free/new/delete and from entry and exit of stack frames. In particular, when memory is - deallocated via free, delete, or function exit, Thrcheck considers + deallocated via free, delete, or function exit, Helgrind considers that memory clean, so when it is eventually reallocated, its history is irrelevant. However, it is common practice to implement memory recycling schemes. In these, memory to be freed is not handed to malloc/delete, but instead put into a pool of free buffers to be - handed out again as required. The problem is that Thrcheck has no + handed out again as required. The problem is that Helgrind has no way to know that such memory is logically no longer in use, and its history is irrelevant. Hence you must make that explicit, using the VALGRIND_HG_CLEAN_MEMORY client request to specify the @@ -948,8 +948,8 @@ of false data-race errors. signalling. Semaphores with an initial value of zero are particularly useful for this. - Thrcheck only partially correctly handles POSIX condition - variables. This is because Thrcheck can see inter-thread + Helgrind only partially correctly handles POSIX condition + variables. This is because Helgrind can see inter-thread dependencies between a pthread_cond_wait call and a pthread_cond_signal/broadcast call only if the waiting thread actually gets to the rendezvous first (so that it actually calls @@ -957,9 +957,9 @@ of false data-race errors. if the signaller arrives first. In the latter case, POSIX guidelines imply that the associated boolean condition still provides an inter-thread synchronisation event, but one which is - invisible to Thrcheck. + invisible to Helgrind. - The result of Thrcheck missing some inter-thread + The result of Helgrind missing some inter-thread synchronisation events is to cause it to report false positives. That's because missing such events reduces the extent to which it can transfer exclusive memory ownership between threads. So @@ -989,7 +989,7 @@ unlock(mx) unlock(mx) Assume b is False most of the time. If the waiter arrives at the rendezvous first, it enters its while-loop, waits for the signaller to signal, and - eventually proceeds. Thrcheck sees the signal, notes the + eventually proceeds. Helgrind sees the signal, notes the dependency, and all is well. If the signaller arrives @@ -1000,9 +1000,9 @@ unlock(mx) unlock(mx) until the signaller sets b to True. Hence there is still the same inter-thread dependency, but this time it is through an arbitrary in-memory condition, and - Thrcheck cannot see it. + Helgrind cannot see it. - By comparison, Thrcheck's detection of inter-thread + By comparison, Helgrind's detection of inter-thread dependencies caused by semaphore operations is believed to be exactly correct. @@ -1013,14 +1013,14 @@ unlock(mx) unlock(mx) Make sure you are using a supported Linux distribution. At - present, Thrcheck only properly supports x86-linux and amd64-linux + present, Helgrind only properly supports x86-linux and amd64-linux with glibc-2.3 or later. The latter restriction means we only support glibc's NPTL threading implementation. The old LinuxThreads implementation is not supported. Unsupported targets may work to varying degrees. In particular ppc32-linux and ppc64-linux running NTPL should work, - but you will get false race errors because Thrcheck does not know + but you will get false race errors because Helgrind does not know how to properly handle atomic instruction sequences created using the lwarx/stwcx instructions. @@ -1031,14 +1031,14 @@ unlock(mx) unlock(mx) don't call pthread_detach on existing threads. Using pthread_join to round up finished threads provides a - clear synchronisation point that both Thrcheck and programmers can - see. This synchronisation point allows Thrcheck to adjust its + clear synchronisation point that both Helgrind and programmers can + see. This synchronisation point allows Helgrind to adjust its memory ownership - models as described - extensively above, which helps Thrcheck produce more + models as described + extensively above, which helps Helgrind produce more accurate error reports. - If you don't call pthread_join on a thread, Thrcheck has no + If you don't call pthread_join on a thread, Helgrind has no way to know when it finishes, relative to any significant synchronisation points for other threads in the program. So it assumes that the thread lingers indefinitely and can potentially @@ -1049,25 +1049,25 @@ unlock(mx) unlock(mx) - Perform thread debugging (with Thrcheck) and memory + Perform thread debugging (with Helgrind) and memory debugging (with Memcheck) together. - Thrcheck tracks the state of memory in detail, and memory + Helgrind tracks the state of memory in detail, and memory management bugs in the application are liable to cause confusion. In extreme cases, applications which do many invalid reads and writes (particularly to freed memory) have been known to crash - Thrcheck. So, ideally, you should make your application - Memcheck-clean before using Thrcheck. + Helgrind. So, ideally, you should make your application + Memcheck-clean before using Helgrind. It may be impossible to make your application Memcheck-clean unless you first remove threading bugs. In particular, it may be difficult to remove all reads and writes to freed memory in multithreaded C++ destructor sequences at program termination. - So, ideally, you should make your application Thrcheck-clean + So, ideally, you should make your application Helgrind-clean before using Memcheck. Since this circularity is obviously unresolvable, at least - bear in mind that Memcheck and Thrcheck are to some extent + bear in mind that Memcheck and Helgrind are to some extent complementary, and you may need to use them together. @@ -1075,17 +1075,17 @@ unlock(mx) unlock(mx) POSIX requires that implementations of standard I/O (printf, fprintf, fwrite, fread, etc) are thread safe. Unfortunately GNU libc implements this by using internal locking primitives that - Thrcheck is unable to intercept. Consequently Thrcheck generates + Helgrind is unable to intercept. Consequently Helgrind generates many false race reports when you use these functions. - Thrcheck attempts to hide these errors using the standard + Helgrind attempts to hide these errors using the standard Valgrind error-suppression mechanism. So, at least for simple test cases, you don't see any. Nevertheless, some may slip through. Just something to be aware of. - Thrcheck's error checks do not work properly inside the + Helgrind's error checks do not work properly inside the system threading library itself (libpthread.so), and it usually observes large numbers of (false) errors in there. Valgrind's @@ -1106,13 +1106,13 @@ unlock(mx) unlock(mx) - -Thrcheck Options + +Helgrind Options The following end-user options are available: - + @@ -1120,13 +1120,13 @@ unlock(mx) unlock(mx) [default: all] ]]> - Thrcheck always regards locks as the basis for + Helgrind always regards locks as the basis for inter-thread synchronisation. However, by default, before - reporting a race error, Thrcheck will also check whether + reporting a race error, Helgrind will also check whether certain other kinds of inter-thread synchronisation events happened. It may be that if such events took place, then no race really occurred, and so no error needs to be reported. - See above + See above for a discussion of transfers of exclusive ownership states between threads. @@ -1146,7 +1146,7 @@ unlock(mx) unlock(mx) Changing this setting from the default will increase your false-error rate but give little or no gain. The only advantage is that and - should make Thrcheck + should make Helgrind less and less sensitive to the scheduling of threads, and hence the output more and more repeatable across runs. @@ -1161,7 +1161,7 @@ unlock(mx) unlock(mx) ]]> - Requests that Thrcheck produces a log of all state changes + Requests that Helgrind produces a log of all state changes to location 0xXXYYZZ. This can be helpful in tracking down tricky races. --trace-level controls the verbosity of the log. At the default setting (1), a one-line @@ -1175,9 +1175,9 @@ unlock(mx) unlock(mx) In addition, the following debugging options are available for -Thrcheck: +Helgrind: - + @@ -1196,9 +1196,9 @@ Thrcheck: At exit, write to stderr a dump of the happens-before - graph computed by Thrcheck, in a format suitable for the VCG + graph computed by Helgrind, in a format suitable for the VCG graph visualisation tool. A suitable command line is: - valgrind --tool=thrcheck + valgrind --tool=helgrind --gen-vcg=yes my_app 2>&1 | grep xxxxxx | sed "s/xxxxxx//g" | xvcg - @@ -1233,7 +1233,7 @@ Thrcheck: ]]> - Run extensive sanity checks on Thrcheck's internal + Run extensive sanity checks on Helgrind's internal data structures at events defined by the bitstring, as follows: 10000 after changes to @@ -1246,7 +1246,7 @@ Thrcheck: lock or unlock event 00001 after every client thread creation or joinage event - Note these will make Thrcheck run very slowly, often to + Note these will make Helgrind run very slowly, often to the point of being completely unusable. @@ -1257,8 +1257,8 @@ Thrcheck: - -A To-Do List for Thrcheck + +A To-Do List for Helgrind The following is a list of loose ends which should be tidied up some time.