ThreadSanitizer

• Introduction
• How to Build
• Supported Platforms
• Usage
• Limitations
• Current Status
• More Information

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.
Note: CMake build does not work yet. See bug 12272.

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 -fthread-sanitizer -fPIE and link it with -fthread-sanitizer -pie.
To get a reasonable performance add -O1 or higher.
Use -g to get file names and line numbers in the warning messages.
Example:

% cat projects/compiler-rt/lib/tsan/output_tests/tiny_race.c
#include 
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 -fthread-sanitizer -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).

% 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. 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.