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