docs/ThreadSanitizer.html - platform/external/clang - Gitiles

 <!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>. <BR>
 Note: CMake build does not work yet.
 See <a href="http://llvm.org/bugs/show_bug.cgi?id=12272">bug 12272</a>.

 <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>-fthread-sanitizer -fPIE</tt> and link it
 with <tt>-fthread-sanitizer -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 -fthread-sanitizer -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.

 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>
	<!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>. <BR>
	Note: CMake build does not work yet.
	See <a href="http://llvm.org/bugs/show_bug.cgi?id=12272">bug 12272</a>.

	<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>-fthread-sanitizer -fPIE</tt> and link it
	with <tt>-fthread-sanitizer -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 -fthread-sanitizer -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.

	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>