160 lines · plain
1ThreadSanitizer2===============3 4Introduction5------------6 7ThreadSanitizer is a tool that detects data races. It consists of a compiler8instrumentation module and a run-time library. Typical slowdown introduced by9ThreadSanitizer is about **5x-15x**. Typical memory overhead introduced by10ThreadSanitizer is about **5x-10x**.11 12How to build13------------14 15Build LLVM/Clang with `CMake <https://llvm.org/docs/CMake.html>`_.16 17Supported Platforms18-------------------19 20ThreadSanitizer is supported on the following OS:21 22* Android aarch64, x86_6423* Darwin arm64, x86_6424* FreeBSD25* Linux aarch64, x86_64, powerpc64, powerpc64le26* NetBSD27 28Support for other 64-bit architectures is possible, contributions are welcome.29Support for 32-bit platforms is problematic and is not planned.30 31Usage32-----33 34Simply compile and link your program with ``-fsanitize=thread``. To get a35reasonable performance add ``-O1`` or higher. Use ``-g`` to get file names36and line numbers in the warning messages.37 38Example:39 40.. code-block:: console41 42 % cat projects/compiler-rt/lib/tsan/lit_tests/tiny_race.c43 #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.c58 59If a bug is detected, the program will print an error message to stderr.60Currently, ThreadSanitizer symbolizes its output using an external61``addr2line`` process (this will be fixed in future).62 63.. code-block:: bash64 65 % ./a.out66 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 whether81ThreadSanitizer is enabled.82:ref:`\_\_has\_feature <langext-__has_feature-__has_extension>` can be used for83this purpose.84 85.. code-block:: c86 87 #if defined(__has_feature)88 # if __has_feature(thread_sanitizer)89 // code that builds only under ThreadSanitizer90 # endif91 #endif92 93``__attribute__((no_sanitize("thread")))``94-----------------------------------------------95 96Some code should not be instrumented by ThreadSanitizer. One may use the97function attribute ``no_sanitize("thread")`` to disable instrumentation of plain98(non-atomic) loads/stores in a particular function. ThreadSanitizer still99instruments such functions to avoid false positives and provide meaningful stack100traces. This attribute may not be supported by other compilers, so we suggest101to 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 functions107to prevent all kinds of instrumentation. As a result, it may introduce false108positives and incorrect stack traces. Therefore, it should be used with care,109and only if absolutely required; for example for certain code that cannot110tolerate any instrumentation and resulting side-effects. This attribute111overrides ``no_sanitize("thread")``.112 113Ignorelist114----------115 116ThreadSanitizer supports ``src`` and ``fun`` entity types in117:doc:`SanitizerSpecialCaseList`, that can be used to suppress data race reports118in the specified source files or functions. Unlike functions marked with119``no_sanitize("thread")`` attribute, ignored functions are not instrumented120at all. This can lead to false positives due to missed synchronization via121atomic operations and missed stack frames in reports.122 123Limitations124-----------125 126* ThreadSanitizer uses more real memory than a native run. At the default127 settings the memory overhead is 5x plus 1Mb per each thread. Settings with 3x128 (less accurate analysis) and 9x (more accurate analysis) overhead are also129 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, the134 ``fsanitize=thread`` flag will cause Clang to act as though the ``-fPIE``135 flag had been supplied if compiling without ``-fPIC``, and as though the136 ``-pie`` flag had been supplied if linking an executable.137 138Security Considerations139-----------------------140 141ThreadSanitizer is a bug detection tool and its runtime is not meant to be142linked against production executables. While it may be useful for testing,143ThreadSanitizer's runtime was not developed with security-sensitive144constraints in mind and may compromise the security of the resulting executable.145 146Current Status147--------------148 149ThreadSanitizer is in beta stage. It is known to work on large C++ programs150using pthreads, but we do not promise anything (yet). C++11 threading is151supported with llvm libc++. The test suite is integrated into CMake build152and 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 Information158----------------159`<https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual>`_160