diff options
Diffstat (limited to 'docs/ThreadSanitizer.rst')
| -rw-r--r-- | docs/ThreadSanitizer.rst | 126 |
1 files changed, 126 insertions, 0 deletions
diff --git a/docs/ThreadSanitizer.rst b/docs/ThreadSanitizer.rst new file mode 100644 index 0000000..c0c576b --- /dev/null +++ b/docs/ThreadSanitizer.rst @@ -0,0 +1,126 @@ +ThreadSanitizer +=============== + +Introduction +------------ + +ThreadSanitizer is a tool that detects data races. It consists of a compiler +instrumentation module and a run-time library. Typical slowdown introduced by +ThreadSanitizer is about **5x-15x**. Typical memory overhead introduced by +ThreadSanitizer is about **5x-10x**. + +How to build +------------ + +Follow the `Clang build instructions <../get_started.html>`_. CMake build is +supported. + +Supported Platforms +------------------- + +ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 10.04 and 12.04). +Support for MacOS 10.7 (64-bit only) is planned for 2013. Support for 32-bit +platforms is problematic and not yet planned. + +Usage +----- + +Simply compile your program with ``-fsanitize=thread -fPIE`` and link it with +``-fsanitize=thread -pie``. To get a reasonable performance add ``-O1`` or +higher. Use ``-g`` to get file names and line numbers in the warning messages. + +Example: + +.. code-block:: c++ + + % cat projects/compiler-rt/lib/tsan/lit_tests/tiny_race.c + #include <pthread.h> + int Global; + void *Thread1(void *x) { + Global = 42; + return x; + } + int main() { + pthread_t t; + pthread_create(&t, NULL, Thread1, NULL); + Global = 43; + pthread_join(t, NULL); + return Global; + } + + $ clang -fsanitize=thread -g -O1 tiny_race.c -fPIE -pie + +If a bug is detected, the program will print an error message to stderr. +Currently, ThreadSanitizer symbolizes its output using an external +``addr2line`` process (this will be fixed in future). + +.. code-block:: bash + + % ./a.out + WARNING: ThreadSanitizer: data race (pid=19219) + Write of size 4 at 0x7fcf47b21bc0 by thread T1: + #0 Thread1 tiny_race.c:4 (exe+0x00000000a360) + + Previous write of size 4 at 0x7fcf47b21bc0 by main thread: + #0 main tiny_race.c:10 (exe+0x00000000a3b4) + + Thread T1 (running) created at: + #0 pthread_create tsan_interceptors.cc:705 (exe+0x00000000c790) + #1 main tiny_race.c:9 (exe+0x00000000a3a4) + +``__has_feature(thread_sanitizer)`` +------------------------------------ + +In some cases one may need to execute different code depending on whether +ThreadSanitizer is enabled. +:ref:`\_\_has\_feature <langext-__has_feature-__has_extension>` can be used for +this purpose. + +.. code-block:: c + + #if defined(__has_feature) + # if __has_feature(thread_sanitizer) + // code that builds only under ThreadSanitizer + # endif + #endif + +``__attribute__((no_sanitize_thread))`` +----------------------------------------------- + +Some code should not be instrumented by ThreadSanitizer. +One may use the function attribute +:ref:`no_sanitize_thread <langext-thread_sanitizer>` +to disable instrumentation of plain (non-atomic) loads/stores in a particular function. +ThreadSanitizer may still instrument such functions to avoid false positives. +This attribute may not be +supported by other compilers, so we suggest to use it together with +``__has_feature(thread_sanitizer)``. Note: currently, this attribute will be +lost if the function is inlined. + +Limitations +----------- + +* ThreadSanitizer uses more real memory than a native run. At the default + settings the memory overhead is 5x plus 1Mb per each thread. Settings with 3x + (less accurate analysis) and 9x (more accurate analysis) overhead are also + available. +* ThreadSanitizer maps (but does not reserve) a lot of virtual address space. + This means that tools like ``ulimit`` may not work as usually expected. +* Libc/libstdc++ static linking is not supported. +* ThreadSanitizer requires ``-fPIE -pie`` compiler flags. + +Current Status +-------------- + +ThreadSanitizer is in beta stage. It is known to work on large C++ programs +using pthreads, but we do not promise anything (yet). C++11 threading is +supported with llvm libc++. The test suite is integrated into CMake build +and can be run with ``make check-tsan`` command. + +We are actively working on enhancing the tool --- stay tuned. Any help, +especially in the form of minimized standalone tests is more than welcome. + +More Information +---------------- +`http://code.google.com/p/thread-sanitizer <http://code.google.com/p/thread-sanitizer/>`_. + |
