forked from OSchip/llvm-project
127 lines
4.0 KiB
HTML
127 lines
4.0 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
|
|
<html>
|
|
<head>
|
|
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<title>ThreadSanitizer, a race detector</title>
|
|
<link type="text/css" rel="stylesheet" href="../menu.css">
|
|
<link type="text/css" rel="stylesheet" href="../content.css">
|
|
<style type="text/css">
|
|
td {
|
|
vertical-align: top;
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
|
|
<!--#include virtual="../menu.html.incl"-->
|
|
|
|
<div id="content">
|
|
|
|
<h1>ThreadSanitizer</h1>
|
|
<ul>
|
|
<li> <a href="#intro">Introduction</a>
|
|
<li> <a href="#howtobuild">How to Build</a>
|
|
<li> <a href="#platforms">Supported Platforms</a>
|
|
<li> <a href="#usage">Usage</a>
|
|
<li> <a href="#limitations">Limitations</a>
|
|
<li> <a href="#status">Current Status</a>
|
|
<li> <a href="#moreinfo">More Information</a>
|
|
</ul>
|
|
|
|
<h2 id="intro">Introduction</h2>
|
|
ThreadSanitizer is a tool that detects data races. <BR>
|
|
It consists of a compiler instrumentation module and a run-time library. <BR>
|
|
Typical slowdown introduced by ThreadSanitizer is <b>5x-15x</b> (TODO: these numbers are
|
|
approximate so far).
|
|
|
|
<h2 id="howtobuild">How to build</h2>
|
|
Follow the <a href="../get_started.html">clang build instructions</a>.
|
|
CMake build is supported.<BR>
|
|
|
|
<h2 id="platforms">Supported Platforms</h2>
|
|
ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 10.04). <BR>
|
|
Support for MacOS 10.7 (64-bit only) is planned for late 2012. <BR>
|
|
Support for 32-bit platforms is problematic and not yet planned.
|
|
|
|
|
|
|
|
<h2 id="usage">Usage</h2>
|
|
Simply compile your program with <tt>-fsanitize=thread -fPIE</tt> and link it
|
|
with <tt>-fsanitize=thread -pie</tt>.<BR>
|
|
To get a reasonable performance add <tt>-O1</tt> or higher. <BR>
|
|
Use <tt>-g</tt> to get file names and line numbers in the warning messages. <BR>
|
|
|
|
Example:
|
|
<pre>
|
|
% 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;
|
|
}
|
|
</pre>
|
|
|
|
<pre>
|
|
% clang -fsanitize=thread -g -O1 tiny_race.c -fPIE -pie
|
|
</pre>
|
|
|
|
If a bug is detected, the program will print an error message to stderr.
|
|
Currently, ThreadSanitizer symbolizes its output using an external
|
|
<tt>addr2line</tt>
|
|
process (this will be fixed in future).
|
|
<pre>
|
|
% 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)
|
|
</pre>
|
|
|
|
|
|
<h2 id="limitations">Limitations</h2>
|
|
<ul>
|
|
<li> 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.
|
|
<li> ThreadSanitizer maps (but does not reserve) a lot of virtual address space.
|
|
This means that tools like <tt>ulimit</tt> may not work as usually expected.
|
|
<li> Static linking is not supported.
|
|
<li> ThreadSanitizer requires <tt>-fPIE -pie</tt>
|
|
</ul>
|
|
|
|
|
|
<h2 id="status">Current Status</h2>
|
|
ThreadSanitizer is in alpha stage.
|
|
It is known to work on large C++ programs using pthreads, but we do not promise
|
|
anything (yet). <BR>
|
|
C++11 threading is not yet supported. <BR>
|
|
The test suite is integrated into CMake build and can be run with
|
|
<tt>make check-tsan</tt> command. <BR>
|
|
|
|
We are actively working on enhancing the tool -- stay tuned.
|
|
Any help, especially in the form of minimized standalone tests is more than welcome.
|
|
|
|
<h2 id="moreinfo">More Information</h2>
|
|
<a href="http://code.google.com/p/thread-sanitizer/">http://code.google.com/p/thread-sanitizer</a>.
|
|
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|