1ThreadSanitizer
2===============
3
4Introduction
5------------
6
7ThreadSanitizer is a tool that detects data races.  It consists of a compiler
8instrumentation module and a run-time library.  Typical slowdown introduced by
9ThreadSanitizer is about **5x-15x**.  Typical memory overhead introduced by
10ThreadSanitizer is about **5x-10x**.
11
12How to build
13------------
14
15Follow the `Clang build instructions <../get_started.html>`_.  CMake build is
16supported.
17
18Supported Platforms
19-------------------
20
21ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 12.04).
22Support for other 64-bit architectures is possible, contributions are welcome.
23Support for 32-bit platforms is problematic and is not planned.
24
25Usage
26-----
27
28Simply compile and link your program with ``-fsanitize=thread``.  To get a
29reasonable performance add ``-O1`` or higher.  Use ``-g`` to get file names
30and line numbers in the warning messages.
31
32Example:
33
34.. code-block:: c++
35
36  % cat projects/compiler-rt/lib/tsan/lit_tests/tiny_race.c
37  #include <pthread.h>
38  int Global;
39  void *Thread1(void *x) {
40    Global = 42;
41    return x;
42  }
43  int main() {
44    pthread_t t;
45    pthread_create(&t, NULL, Thread1, NULL);
46    Global = 43;
47    pthread_join(t, NULL);
48    return Global;
49  }
50
51  $ clang -fsanitize=thread -g -O1 tiny_race.c
52
53If a bug is detected, the program will print an error message to stderr.
54Currently, ThreadSanitizer symbolizes its output using an external
55``addr2line`` process (this will be fixed in future).
56
57.. code-block:: bash
58
59  % ./a.out
60  WARNING: ThreadSanitizer: data race (pid=19219)
61    Write of size 4 at 0x7fcf47b21bc0 by thread T1:
62      #0 Thread1 tiny_race.c:4 (exe+0x00000000a360)
63
64    Previous write of size 4 at 0x7fcf47b21bc0 by main thread:
65      #0 main tiny_race.c:10 (exe+0x00000000a3b4)
66
67    Thread T1 (running) created at:
68      #0 pthread_create tsan_interceptors.cc:705 (exe+0x00000000c790)
69      #1 main tiny_race.c:9 (exe+0x00000000a3a4)
70
71``__has_feature(thread_sanitizer)``
72------------------------------------
73
74In some cases one may need to execute different code depending on whether
75ThreadSanitizer is enabled.
76:ref:`\_\_has\_feature <langext-__has_feature-__has_extension>` can be used for
77this purpose.
78
79.. code-block:: c
80
81    #if defined(__has_feature)
82    #  if __has_feature(thread_sanitizer)
83    // code that builds only under ThreadSanitizer
84    #  endif
85    #endif
86
87``__attribute__((no_sanitize_thread))``
88-----------------------------------------------
89
90Some code should not be instrumented by ThreadSanitizer.
91One may use the function attribute
92:ref:`no_sanitize_thread <langext-thread_sanitizer>`
93to disable instrumentation of plain (non-atomic) loads/stores in a particular function.
94ThreadSanitizer still instruments such functions to avoid false positives and
95provide meaningful stack traces.
96This attribute may not be
97supported by other compilers, so we suggest to use it together with
98``__has_feature(thread_sanitizer)``.
99
100Blacklist
101---------
102
103ThreadSanitizer supports ``src`` and ``fun`` entity types in
104:doc:`SanitizerSpecialCaseList`, that can be used to suppress data race reports in
105the specified source files or functions. Unlike functions marked with
106:ref:`no_sanitize_thread <langext-thread_sanitizer>` attribute,
107blacklisted functions are not instrumented at all. This can lead to false positives
108due to missed synchronization via atomic operations and missed stack frames in reports.
109
110Limitations
111-----------
112
113* ThreadSanitizer uses more real memory than a native run. At the default
114  settings the memory overhead is 5x plus 1Mb per each thread. Settings with 3x
115  (less accurate analysis) and 9x (more accurate analysis) overhead are also
116  available.
117* ThreadSanitizer maps (but does not reserve) a lot of virtual address space.
118  This means that tools like ``ulimit`` may not work as usually expected.
119* Libc/libstdc++ static linking is not supported.
120* Non-position-independent executables are not supported.  Therefore, the
121  ``fsanitize=thread`` flag will cause Clang to act as though the ``-fPIE``
122  flag had been supplied if compiling without ``-fPIC``, and as though the
123  ``-pie`` flag had been supplied if linking an executable.
124
125Current Status
126--------------
127
128ThreadSanitizer is in beta stage.  It is known to work on large C++ programs
129using pthreads, but we do not promise anything (yet).  C++11 threading is
130supported with llvm libc++.  The test suite is integrated into CMake build
131and can be run with ``make check-tsan`` command.
132
133We are actively working on enhancing the tool --- stay tuned.  Any help,
134especially in the form of minimized standalone tests is more than welcome.
135
136More Information
137----------------
138`http://code.google.com/p/thread-sanitizer <http://code.google.com/p/thread-sanitizer/>`_.
139
140