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 15Build LLVM/Clang with `CMake <http://llvm.org/docs/CMake.html>`_. 16 17Supported Platforms 18------------------- 19 20ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 12.04). 21Support for other 64-bit architectures is possible, contributions are welcome. 22Support for 32-bit platforms is problematic and is not planned. 23 24Usage 25----- 26 27Simply compile and link your program with ``-fsanitize=thread``. To get a 28reasonable performance add ``-O1`` or higher. Use ``-g`` to get file names 29and line numbers in the warning messages. 30 31Example: 32 33.. code-block:: console 34 35 % cat projects/compiler-rt/lib/tsan/lit_tests/tiny_race.c 36 #include <pthread.h> 37 int Global; 38 void *Thread1(void *x) { 39 Global = 42; 40 return x; 41 } 42 int main() { 43 pthread_t t; 44 pthread_create(&t, NULL, Thread1, NULL); 45 Global = 43; 46 pthread_join(t, NULL); 47 return Global; 48 } 49 50 $ clang -fsanitize=thread -g -O1 tiny_race.c 51 52If a bug is detected, the program will print an error message to stderr. 53Currently, ThreadSanitizer symbolizes its output using an external 54``addr2line`` process (this will be fixed in future). 55 56.. code-block:: bash 57 58 % ./a.out 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) 62 63 Previous write of size 4 at 0x7fcf47b21bc0 by main thread: 64 #0 main tiny_race.c:10 (exe+0x00000000a3b4) 65 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) 69 70``__has_feature(thread_sanitizer)`` 71------------------------------------ 72 73In some cases one may need to execute different code depending on whether 74ThreadSanitizer is enabled. 75:ref:`\_\_has\_feature <langext-__has_feature-__has_extension>` can be used for 76this purpose. 77 78.. code-block:: c 79 80 #if defined(__has_feature) 81 # if __has_feature(thread_sanitizer) 82 // code that builds only under ThreadSanitizer 83 # endif 84 #endif 85 86``__attribute__((no_sanitize_thread))`` 87----------------------------------------------- 88 89Some code should not be instrumented by ThreadSanitizer. One may use the 90function attribute `no_sanitize_thread` to disable instrumentation of plain 91(non-atomic) loads/stores in a particular function. ThreadSanitizer still 92instruments such functions to avoid false positives and provide meaningful stack 93traces. This attribute may not be supported by other compilers, so we suggest 94to use it together with ``__has_feature(thread_sanitizer)``. 95 96Blacklist 97--------- 98 99ThreadSanitizer supports ``src`` and ``fun`` entity types in 100:doc:`SanitizerSpecialCaseList`, that can be used to suppress data race reports 101in the specified source files or functions. Unlike functions marked with 102`no_sanitize_thread` attribute, blacklisted functions are not instrumented at 103all. This can lead to false positives due to missed synchronization via atomic 104operations and missed stack frames in reports. 105 106Limitations 107----------- 108 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 112 available. 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. 120 121Current Status 122-------------- 123 124ThreadSanitizer is in beta stage. It is known to work on large C++ programs 125using pthreads, but we do not promise anything (yet). C++11 threading is 126supported with llvm libc++. The test suite is integrated into CMake build 127and can be run with ``make check-tsan`` command. 128 129We are actively working on enhancing the tool --- stay tuned. Any help, 130especially in the form of minimized standalone tests is more than welcome. 131 132More Information 133---------------- 134`<https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual>`_ 135