From be66bf152eeb26e183c15ae4dfa44083e116e210 Mon Sep 17 00:00:00 2001 From: Dmitry Vyukov Date: Mon, 17 Dec 2012 07:16:54 +0000 Subject: [PATCH] tsan: update docs llvm-svn: 170311 --- clang/docs/ThreadSanitizer.rst | 38 ++++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/clang/docs/ThreadSanitizer.rst b/clang/docs/ThreadSanitizer.rst index 5f04170..e434062 100644 --- a/clang/docs/ThreadSanitizer.rst +++ b/clang/docs/ThreadSanitizer.rst @@ -6,7 +6,8 @@ Introduction ThreadSanitizer is a tool that detects data races. It consists of a compiler instrumentation module and a run-time library. Typical slowdown introduced by -ThreadSanitizer is **5x-15x** (TODO: these numbers are approximate so far). +ThreadSanitizer is about **5x-15x**. Typical memory overhead introduced by +ThreadSanitizer is about **5x-10x**. How to build ------------ @@ -17,8 +18,8 @@ supported. Supported Platforms ------------------- -ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 10.04). Support -for MacOS 10.7 (64-bit only) is planned for late 2012. Support for 32-bit +ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 10.04 and 12.04). +Support for MacOS 10.7 (64-bit only) is planned for 2013. Support for 32-bit platforms is problematic and not yet planned. Usage @@ -32,7 +33,7 @@ Example: .. code-block:: c++ - % cat projects/compiler-rt/lib/tsan/output_tests/tiny_race.c + % cat projects/compiler-rt/lib/tsan/lit_tests/tiny_race.c #include int Global; void *Thread1(void *x) { @@ -55,36 +56,37 @@ Currently, ThreadSanitizer symbolizes its output using an external .. code-block:: bash - % TSAN_OPTIONS=strip_path_prefix=`pwd`/ # Don't print full paths. - % ./a.out 2> log - % cat log + % ./a.out WARNING: ThreadSanitizer: data race (pid=19219) - Write of size 4 at 0x7fcf47b21bc0 by thread 1: + Write of size 4 at 0x7fcf47b21bc0 by thread T1: #0 Thread1 tiny_race.c:4 (exe+0x00000000a360) + Previous write of size 4 at 0x7fcf47b21bc0 by main thread: #0 main tiny_race.c:10 (exe+0x00000000a3b4) - Thread 1 (running) created at: - #0 pthread_create ??:0 (exe+0x00000000c790) + + Thread T1 (running) created at: + #0 pthread_create tsan_interceptors.cc:705 (exe+0x00000000c790) #1 main tiny_race.c:9 (exe+0x00000000a3a4) Limitations ----------- * ThreadSanitizer uses more real memory than a native run. At the default - settings the memory overhead is 9x plus 9Mb per each thread. Settings with 5x - and 3x overhead (but less accurate analysis) are also available. + settings the memory overhead is 5x plus 1Mb per each thread. Settings with 3x + (less accurate analysis) and 9x (more accurate analysis) overhead are also + available. * ThreadSanitizer maps (but does not reserve) a lot of virtual address space. This means that tools like ``ulimit`` may not work as usually expected. -* Static linking is not supported. -* ThreadSanitizer requires ``-fPIE -pie``. +* Libc/libstdc++ static linking is not supported. +* ThreadSanitizer requires ``-fPIE -pie`` compiler flags. Current Status -------------- -ThreadSanitizer is in alpha stage. It is known to work on large C++ programs -using pthreads, but we do not promise anything (yet). C++11 threading is not -yet supported. The test suite is integrated into CMake build and can be run -with ``make check-tsan`` command. +ThreadSanitizer is in beta stage. It is known to work on large C++ programs +using pthreads, but we do not promise anything (yet). C++11 threading is +supported with llvm libstdc++. The test suite is integrated into CMake build +and can be run with ``make check-tsan`` command. We are actively working on enhancing the tool --- stay tuned. Any help, especially in the form of minimized standalone tests is more than welcome. -- 2.7.4