[cfe-commits] r170311 - /cfe/trunk/docs/ThreadSanitizer.rst

[Dmitry Vyukov]

Author: dvyukov
Date: Mon Dec 17 01:16:54 2012
New Revision: 170311

URL: http://llvm.org/viewvc/llvm-project?rev=170311&view=rev
Log:
tsan: update docs

Modified:
    cfe/trunk/docs/ThreadSanitizer.rst

Modified: cfe/trunk/docs/ThreadSanitizer.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ThreadSanitizer.rst?rev=170311&r1=170310&r2=170311&view=diff
==============================================================================
--- cfe/trunk/docs/ThreadSanitizer.rst (original)
+++ cfe/trunk/docs/ThreadSanitizer.rst Mon Dec 17 01:16:54 2012
@@ -6,7 +6,8 @@
 
 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 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 @@
 
 .. 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 <pthread.h>
   int Global;
   void *Thread1(void *x) {
@@ -55,36 +56,37 @@
 
 .. 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.