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 10.04 and 12.04). 22Support for MacOS 10.7 (64-bit only) is planned for 2013. Support for 32-bit 23platforms is problematic and not yet 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 may still instrument such functions to avoid false positives. 95This attribute may not be 96supported by other compilers, so we suggest to use it together with 97``__has_feature(thread_sanitizer)``. Note: currently, this attribute will be 98lost if the function is inlined. 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. 106 107Limitations 108----------- 109 110* ThreadSanitizer uses more real memory than a native run. At the default 111 settings the memory overhead is 5x plus 1Mb per each thread. Settings with 3x 112 (less accurate analysis) and 9x (more accurate analysis) overhead are also 113 available. 114* ThreadSanitizer maps (but does not reserve) a lot of virtual address space. 115 This means that tools like ``ulimit`` may not work as usually expected. 116* Libc/libstdc++ static linking is not supported. 117* Non-position-independent executables are not supported. Therefore, the 118 ``fsanitize=thread`` flag will cause Clang to act as though the ``-fPIE`` 119 flag had been supplied if compiling without ``-fPIC``, and as though the 120 ``-pie`` flag had been supplied if linking an executable. 121 122Current Status 123-------------- 124 125ThreadSanitizer is in beta stage. It is known to work on large C++ programs 126using pthreads, but we do not promise anything (yet). C++11 threading is 127supported with llvm libc++. The test suite is integrated into CMake build 128and can be run with ``make check-tsan`` command. 129 130We are actively working on enhancing the tool --- stay tuned. Any help, 131especially in the form of minimized standalone tests is more than welcome. 132 133More Information 134---------------- 135`http://code.google.com/p/thread-sanitizer <http://code.google.com/p/thread-sanitizer/>`_. 136 137