blob: a7f6eb782b5fade03c2a5b9ebeda2691809585f7 [file] [log] [blame]
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 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.
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.
.. 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 (exe+0x00000000c790)
#1 main tiny_race.c:9 (exe+0x00000000a3a4)
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) && __has_feature(thread_sanitizer)
// code that builds only under ThreadSanitizer
* 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
* 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
` <>`_.