7 ThreadSanitizer is a tool that detects data races. It consists of a compiler
8 instrumentation module and a run-time library. Typical slowdown introduced by
9 ThreadSanitizer is about **5x-15x**. Typical memory overhead introduced by
10 ThreadSanitizer is about **5x-10x**.
15 Build LLVM/Clang with `CMake <http://llvm.org/docs/CMake.html>`_.
20 ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 12.04).
21 Support for other 64-bit architectures is possible, contributions are welcome.
22 Support for 32-bit platforms is problematic and is not planned.
27 Simply compile and link your program with ``-fsanitize=thread``. To get a
28 reasonable performance add ``-O1`` or higher. Use ``-g`` to get file names
29 and line numbers in the warning messages.
35 % cat projects/compiler-rt/lib/tsan/lit_tests/tiny_race.c
38 void *Thread1(void *x) {
44 pthread_create(&t, NULL, Thread1, NULL);
46 pthread_join(t, NULL);
50 $ clang -fsanitize=thread -g -O1 tiny_race.c
52 If a bug is detected, the program will print an error message to stderr.
53 Currently, ThreadSanitizer symbolizes its output using an external
54 ``addr2line`` process (this will be fixed in future).
59 WARNING: ThreadSanitizer: data race (pid=19219)
60 Write of size 4 at 0x7fcf47b21bc0 by thread T1:
61 #0 Thread1 tiny_race.c:4 (exe+0x00000000a360)
63 Previous write of size 4 at 0x7fcf47b21bc0 by main thread:
64 #0 main tiny_race.c:10 (exe+0x00000000a3b4)
66 Thread T1 (running) created at:
67 #0 pthread_create tsan_interceptors.cc:705 (exe+0x00000000c790)
68 #1 main tiny_race.c:9 (exe+0x00000000a3a4)
70 ``__has_feature(thread_sanitizer)``
71 ------------------------------------
73 In some cases one may need to execute different code depending on whether
74 ThreadSanitizer is enabled.
75 :ref:`\_\_has\_feature <langext-__has_feature-__has_extension>` can be used for
80 #if defined(__has_feature)
81 # if __has_feature(thread_sanitizer)
82 // code that builds only under ThreadSanitizer
86 ``__attribute__((no_sanitize_thread))``
87 -----------------------------------------------
89 Some code should not be instrumented by ThreadSanitizer. One may use the
90 function attribute `no_sanitize_thread` to disable instrumentation of plain
91 (non-atomic) loads/stores in a particular function. ThreadSanitizer still
92 instruments such functions to avoid false positives and provide meaningful stack
93 traces. This attribute may not be supported by other compilers, so we suggest
94 to use it together with ``__has_feature(thread_sanitizer)``.
99 ThreadSanitizer supports ``src`` and ``fun`` entity types in
100 :doc:`SanitizerSpecialCaseList`, that can be used to suppress data race reports
101 in the specified source files or functions. Unlike functions marked with
102 `no_sanitize_thread` attribute, blacklisted functions are not instrumented at
103 all. This can lead to false positives due to missed synchronization via atomic
104 operations and missed stack frames in reports.
109 * ThreadSanitizer uses more real memory than a native run. At the default
110 settings the memory overhead is 5x plus 1Mb per each thread. Settings with 3x
111 (less accurate analysis) and 9x (more accurate analysis) overhead are also
113 * ThreadSanitizer maps (but does not reserve) a lot of virtual address space.
114 This means that tools like ``ulimit`` may not work as usually expected.
115 * Libc/libstdc++ static linking is not supported.
116 * Non-position-independent executables are not supported. Therefore, the
117 ``fsanitize=thread`` flag will cause Clang to act as though the ``-fPIE``
118 flag had been supplied if compiling without ``-fPIC``, and as though the
119 ``-pie`` flag had been supplied if linking an executable.
124 ThreadSanitizer is in beta stage. It is known to work on large C++ programs
125 using pthreads, but we do not promise anything (yet). C++11 threading is
126 supported with llvm libc++. The test suite is integrated into CMake build
127 and can be run with ``make check-tsan`` command.
129 We are actively working on enhancing the tool --- stay tuned. Any help,
130 especially in the form of minimized standalone tests is more than welcome.
134 `<https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual>`_