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 37approximate 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> 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. 48 49 50 51<h2 id="usage">Usage</h2> 52Simply compile your program with <tt>-fthread-sanitizer -fPIE</tt> and link it 53with <tt>-fthread-sanitizer -pie</tt>.<BR> 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. 103<li> ThreadSanitizer maps (but does not reserve) a lot of virtual address space. 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> 126