Home | History | Annotate | Download | only in docs 
      1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 
      2           "http://www.w3.org/TR/html4/strict.dtd">
      3 <!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
      4 <html>
      5 <head>
      6   <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
      7   <title>ThreadSanitizer, a race detector</title>
      8   <link type="text/css" rel="stylesheet" href="../menu.css">
      9   <link type="text/css" rel="stylesheet" href="../content.css">
     10   <style type="text/css">
     11     td {
     12             vertical-align: top;
     13     }
     14   </style>
     15 </head>
     16 <body>
     17 
     18 <!--#include virtual="../menu.html.incl"-->
     19 
     20 <div id="content">
     21 
     22 <h1>ThreadSanitizer</h1>
     23 <ul>
     24   <li> <a href="#intro">Introduction</a>
     25   <li> <a href="#howtobuild">How to Build</a>
     26   <li> <a href="#platforms">Supported Platforms</a>
     27   <li> <a href="#usage">Usage</a>
     28   <li> <a href="#limitations">Limitations</a>
     29   <li> <a href="#status">Current Status</a>
     30   <li> <a href="#moreinfo">More Information</a>
     31 </ul>
     32 
     33 <h2 id="intro">Introduction</h2>
     34 ThreadSanitizer is a tool that detects data races. <BR>
     35 It consists of a compiler instrumentation module and a run-time library. <BR>
     36 Typical slowdown introduced by ThreadSanitizer is <b>5x-15x</b> (TODO: these numbers are
     37 approximate so far).
     38 
     39 <h2 id="howtobuild">How to build</h2>
     40 Follow the <a href="../get_started.html">clang build instructions</a>. <BR>
     41 Note: CMake build does not work yet.
     42 See <a href="http://llvm.org/bugs/show_bug.cgi?id=12272">bug 12272</a>.
     43 
     44 <h2 id="platforms">Supported Platforms</h2>
     45 ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 10.04). <BR>
     46 Support for MacOS 10.7 (64-bit only) is planned for late 2012. <BR>
     47 Support for 32-bit platforms is problematic and not yet planned.
     48 
     49 
     50 
     51 <h2 id="usage">Usage</h2>
     52 Simply compile your program with <tt>-fthread-sanitizer -fPIE</tt> and link it
     53 with <tt>-fthread-sanitizer -pie</tt>.<BR>
     54 To get a reasonable performance add <tt>-O1</tt> or higher. <BR>
     55 Use <tt>-g</tt> to get file names and line numbers in the warning messages. <BR>
     56 
     57 Example:
     58 <pre>
     59 % cat projects/compiler-rt/lib/tsan/output_tests/tiny_race.c
     60 #include <pthread.h>
     61 int Global;
     62 void *Thread1(void *x) {
     63   Global = 42;
     64   return x;
     65 }
     66 int main() {
     67   pthread_t t;
     68   pthread_create(&t, NULL, Thread1, NULL);
     69   Global = 43;
     70   pthread_join(t, NULL);
     71   return Global;
     72 }
     73 </pre>
     74 
     75 <pre>
     76 % clang -fthread-sanitizer -g -O1 tiny_race.c -fPIE -pie
     77 </pre>
     78 
     79 If a bug is detected, the program will print an error message to stderr.
     80 Currently, ThreadSanitizer symbolizes its output using an external
     81 <tt>addr2line</tt>
     82 process (this will be fixed in future).
     83 <pre>
     84 % TSAN_OPTIONS=strip_path_prefix=`pwd`/  # Don't print full paths.
     85 % ./a.out 2> log
     86 % cat log
     87 WARNING: ThreadSanitizer: data race (pid=19219)
     88   Write of size 4 at 0x7fcf47b21bc0 by thread 1:
     89     #0 Thread1 tiny_race.c:4 (exe+0x00000000a360)
     90   Previous write of size 4 at 0x7fcf47b21bc0 by main thread:
     91     #0 main tiny_race.c:10 (exe+0x00000000a3b4)
     92   Thread 1 (running) created at:
     93     #0 pthread_create ??:0 (exe+0x00000000c790)
     94     #1 main tiny_race.c:9 (exe+0x00000000a3a4)
     95 </pre>
     96 
     97 
     98 <h2 id="limitations">Limitations</h2>
     99 <ul>
    100 <li> ThreadSanitizer uses more real memory than a native run.
    101 At the default settings the memory overhead is 9x plus 9Mb per each thread.
    102 Settings with 5x and 3x overhead (but less accurate analysis) are also available.
    103 <li> ThreadSanitizer maps (but does not reserve) a lot of virtual address space.
    104 This means that tools like <tt>ulimit</tt> may not work as usually expected.
    105 <li> Static linking is not supported.
    106 <li> ThreadSanitizer requires <tt>-fPIE -pie</tt>
    107 </ul>
    108 
    109 
    110 <h2 id="status">Current Status</h2>
    111 ThreadSanitizer is in alpha stage.
    112 It is known to work on large C++ programs using pthreads, but we do not promise
    113 anything (yet). <BR>
    114 C++11 threading is not yet supported.
    115 
    116 We are actively working on enhancing the tool -- stay tuned.
    117 Any help, especially in the form of minimized standalone tests is more than welcome.
    118 
    119 <h2 id="moreinfo">More Information</h2>
    120 <a href="http://code.google.com/p/thread-sanitizer/">http://code.google.com/p/thread-sanitizer</a>.
    121 
    122 
    123 </div>
    124 </body>
    125 </html>
    126