Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / 183ff2aaacbc1995ed64d5e2ffea4456fd871633 / . / docs / ThreadSanitizer.html
blob: c35979fcd01d666252ed209b0c249de759f4dab3 [file] [log] [blame]
Kostya Serebryanye2789bb2012-05-16 08:14:36 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
4<html>
5<head>
6 <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
7 <title>ThreadSanitizer, a race detector</title>
8 <link type="text/css" rel="stylesheet" href="../menu.css">
9 <link type="text/css" rel="stylesheet" href="../content.css">
10 <style type="text/css">
11 td {
12 vertical-align: top;
13 }
14 </style>
15</head>
16<body>
17
18<!--#include virtual="../menu.html.incl"-->
19
20<div id="content">
21
22<h1>ThreadSanitizer</h1>
23<ul>
24 <li> <a href="#intro">Introduction</a>
25 <li> <a href="#howtobuild">How to Build</a>
26 <li> <a href="#platforms">Supported Platforms</a>
27 <li> <a href="#usage">Usage</a>
28 <li> <a href="#limitations">Limitations</a>
29 <li> <a href="#status">Current Status</a>
30 <li> <a href="#moreinfo">More Information</a>
31</ul>
32
33<h2 id="intro">Introduction</h2>
34ThreadSanitizer is a tool that detects data races. <BR>
35It consists of a compiler instrumentation module and a run-time library. <BR>
36Typical slowdown introduced by ThreadSanitizer is <b>5x-15x</b> (TODO: these numbers are
37aproximate so far).
38
39<h2 id="howtobuild">How to build</h2>
40Follow the <a href="../get_started.html">clang build instructions</a>. <BR>
41Note: CMake build does not work yet.
42See <a href="http://llvm.org/bugs/show_bug.cgi?id=12272">bug 12272</a>.
43
44<h2 id="platforms">Supported Platforms</h2>
45ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 10.04). <BR>
Kostya Serebryanyf291d8c2012-05-17 08:49:14 +0000[diff] [blame]46Support for MacOS 10.7 (64-bit only) is planned for late 2012. <BR>
47Support for 32-bit platforms is problematic and not yet planned.
Kostya Serebryanye2789bb2012-05-16 08:14:36 +0000[diff] [blame]48
49
50
51<h2 id="usage">Usage</h2>
Kostya Serebryany53243802012-05-16 08:19:13 +0000[diff] [blame]52Simply compile your program with <tt>-fthread-sanitizer -fPIE</tt> and link it
53with <tt>-fthread-sanitizer -pie</tt>.<BR>
Kostya Serebryanye2789bb2012-05-16 08:14:36 +0000[diff] [blame]54To get a reasonable performance add <tt>-O1</tt> or higher. <BR>
55Use <tt>-g</tt> to get file names and line numbers in the warning messages. <BR>
56
57Example:
58<pre>
59% cat projects/compiler-rt/lib/tsan/output_tests/tiny_race.c
60#include <pthread.h>
61int Global;
62void *Thread1(void *x) {
63 Global = 42;
64 return x;
65}
66int main() {
67 pthread_t t;
68 pthread_create(&t, NULL, Thread1, NULL);
69 Global = 43;
70 pthread_join(t, NULL);
71 return Global;
72}
73</pre>
74
75<pre>
76% clang -fthread-sanitizer -g -O1 tiny_race.c -fPIE -pie
77</pre>
78
79If a bug is detected, the program will print an error message to stderr.
80Currently, ThreadSanitizer symbolizes its output using an external
81<tt>addr2line</tt>
82process (this will be fixed in future).
83<pre>
84% TSAN_OPTIONS=strip_path_prefix=`pwd`/ # Don't print full paths.
85% ./a.out 2> log
86% cat log
87WARNING: ThreadSanitizer: data race (pid=19219)
88 Write of size 4 at 0x7fcf47b21bc0 by thread 1:
89 #0 Thread1 tiny_race.c:4 (exe+0x00000000a360)
90 Previous write of size 4 at 0x7fcf47b21bc0 by main thread:
91 #0 main tiny_race.c:10 (exe+0x00000000a3b4)
92 Thread 1 (running) created at:
93 #0 pthread_create ??:0 (exe+0x00000000c790)
94 #1 main tiny_race.c:9 (exe+0x00000000a3a4)
95</pre>
96
97
98<h2 id="limitations">Limitations</h2>
99<ul>
100<li> ThreadSanitizer uses more real memory than a native run.
101At the default settings the memory overhead is 9x plus 9Mb per each thread.
102Settings with 5x and 3x overhead (but less accurate analysis) are also available.
Kostya Serebryanyf291d8c2012-05-17 08:49:14 +0000[diff] [blame]103<li> ThreadSanitizer maps (but does not reserve) a lot of virtual address space.
Kostya Serebryanye2789bb2012-05-16 08:14:36 +0000[diff] [blame]104This means that tools like <tt>ulimit</tt> may not work as usually expected.
105<li> Static linking is not supported.
106<li> ThreadSanitizer requires <tt>-fPIE -pie</tt>
107</ul>
108
109
110<h2 id="status">Current Status</h2>
111ThreadSanitizer is in alpha stage.
112It is known to work on large C++ programs using pthreads, but we do not promise
113anything (yet). <BR>
114C++11 threading is not yet supported.
115
116We are actively working on enhancing the tool -- stay tuned.
117Any help, especially in the form of minimized standalone tests is more than welcome.
118
119<h2 id="moreinfo">More Information</h2>
120<a href="http://code.google.com/p/thread-sanitizer/">http://code.google.com/p/thread-sanitizer</a>.
121
122
123</div>
124</body>
125</html>