mirror of
https://github.com/llvm/llvm-project.git
synced 2025-04-27 03:36:06 +00:00
96 lines
3.0 KiB
ReStructuredText
96 lines
3.0 KiB
ReStructuredText
|
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 **5x-15x** (TODO: these numbers are approximate so far).
|
||
|
|
|
||
|
|
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). Support
|
||
|
|
for MacOS 10.7 (64-bit only) is planned for late 2012. 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/output_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
|
||
|
|
|
||
|
|
% TSAN_OPTIONS=strip_path_prefix=`pwd`/ # Don't print full paths.
|
||
|
|
% ./a.out 2> log
|
||
|
|
% cat log
|
||
|
|
WARNING: ThreadSanitizer: data race (pid=19219)
|
||
|
|
Write of size 4 at 0x7fcf47b21bc0 by thread 1:
|
||
|
|
#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 1 (running) created at:
|
||
|
|
#0 pthread_create ??:0 (exe+0x00000000c790)
|
||
|
|
#1 main tiny_race.c:9 (exe+0x00000000a3a4)
|
||
|
|
|
||
|
|
Limitations
|
||
|
|
-----------
|
||
|
|
|
||
|
|
* ThreadSanitizer uses more real memory than a native run. At the default
|
||
|
|
settings the memory overhead is 9x plus 9Mb per each thread. Settings with 5x
|
||
|
|
and 3x overhead (but less accurate analysis) 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.
|
||
|
|
* Static linking is not supported.
|
||
|
|
* ThreadSanitizer requires ``-fPIE -pie``.
|
||
|
|
|
||
|
|
Current Status
|
||
|
|
--------------
|
||
|
|
|
||
|
|
ThreadSanitizer is in alpha stage. It is known to work on large C++ programs
|
||
|
|
using pthreads, but we do not promise anything (yet). C++11 threading is not
|
||
|
|
yet supported. 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/>`_.
|
||
|
|
|