external/bsd/llvm/dist/clang/docs/ThreadSanitizer.rst

   1 ThreadSanitizer
   2 ===============
   3
   4 Introduction
   5 ------------
   6
   7 ThreadSanitizer is a tool that detects data races.  It consists of a compiler
   8 instrumentation module and a run-time library.  Typical slowdown introduced by
   9 ThreadSanitizer is about **5x-15x**.  Typical memory overhead introduced by
  10 ThreadSanitizer is about **5x-10x**.
  11
  12 How to build
  13 ------------
  14
  15 Follow the `Clang build instructions <../get_started.html>`_.  CMake build is
  16 supported.
  17
  18 Supported Platforms
  19 -------------------
  20
  21 ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 12.04).
  22 Support for other 64-bit architectures is possible, contributions are welcome.
  23 Support for 32-bit platforms is problematic and is not planned.
  24
  25 Usage
  26 -----
  27
  28 Simply compile and link your program with ``-fsanitize=thread``.  To get a
  29 reasonable performance add ``-O1`` or higher.  Use ``-g`` to get file names
  30 and line numbers in the warning messages.
  31
  32 Example:
  33
  34 .. code-block:: c++
  35
  36   % cat projects/compiler-rt/lib/tsan/lit_tests/tiny_race.c
  37   #include <pthread.h>
  38   int Global;
  39   void *Thread1(void *x) {
  40     Global = 42;
  41     return x;
  42   }
  43   int main() {
  44     pthread_t t;
  45     pthread_create(&t, NULL, Thread1, NULL);
  46     Global = 43;
  47     pthread_join(t, NULL);
  48     return Global;
  49   }
  50
  51   $ clang -fsanitize=thread -g -O1 tiny_race.c
  52
  53 If a bug is detected, the program will print an error message to stderr.
  54 Currently, ThreadSanitizer symbolizes its output using an external
  55 ``addr2line`` process (this will be fixed in future).
  56
  57 .. code-block:: bash
  58
  59   % ./a.out
  60   WARNING: ThreadSanitizer: data race (pid=19219)
  61     Write of size 4 at 0x7fcf47b21bc0 by thread T1:
  62       #0 Thread1 tiny_race.c:4 (exe+0x00000000a360)
  63
  64     Previous write of size 4 at 0x7fcf47b21bc0 by main thread:
  65       #0 main tiny_race.c:10 (exe+0x00000000a3b4)
  66
  67     Thread T1 (running) created at:
  68       #0 pthread_create tsan_interceptors.cc:705 (exe+0x00000000c790)
  69       #1 main tiny_race.c:9 (exe+0x00000000a3a4)
  70
  71 ``__has_feature(thread_sanitizer)``
  72 ------------------------------------
  73
  74 In some cases one may need to execute different code depending on whether
  75 ThreadSanitizer is enabled.
  76 :ref:`\_\_has\_feature <langext-__has_feature-__has_extension>` can be used for
  77 this purpose.
  78
  79 .. code-block:: c
  80
  81     #if defined(__has_feature)
  82     #  if __has_feature(thread_sanitizer)
  83     // code that builds only under ThreadSanitizer
  84     #  endif
  85     #endif
  86
  87 ``__attribute__((no_sanitize_thread))``
  88 -----------------------------------------------
  89
  90 Some code should not be instrumented by ThreadSanitizer.
  91 One may use the function attribute
  92 :ref:`no_sanitize_thread <langext-thread_sanitizer>`
  93 to disable instrumentation of plain (non-atomic) loads/stores in a particular function.
  94 ThreadSanitizer still instruments such functions to avoid false positives and
  95 provide meaningful stack traces.
  96 This attribute may not be
  97 supported by other compilers, so we suggest to use it together with
  98 ``__has_feature(thread_sanitizer)``.
  99
 100 Blacklist
 101 ---------
 102
 103 ThreadSanitizer supports ``src`` and ``fun`` entity types in
 104 :doc:`SanitizerSpecialCaseList`, that can be used to suppress data race reports in
 105 the specified source files or functions. Unlike functions marked with
 106 :ref:`no_sanitize_thread <langext-thread_sanitizer>` attribute,
 107 blacklisted functions are not instrumented at all. This can lead to false positives
 108 due to missed synchronization via atomic operations and missed stack frames in reports.
 109
 110 Limitations
 111 -----------
 112
 113 * ThreadSanitizer uses more real memory than a native run. At the default
 114   settings the memory overhead is 5x plus 1Mb per each thread. Settings with 3x
 115   (less accurate analysis) and 9x (more accurate analysis) overhead are also
 116   available.
 117 * ThreadSanitizer maps (but does not reserve) a lot of virtual address space.
 118   This means that tools like ``ulimit`` may not work as usually expected.
 119 * Libc/libstdc++ static linking is not supported.
 120 * Non-position-independent executables are not supported.  Therefore, the
 121   ``fsanitize=thread`` flag will cause Clang to act as though the ``-fPIE``
 122   flag had been supplied if compiling without ``-fPIC``, and as though the
 123   ``-pie`` flag had been supplied if linking an executable.
 124
 125 Current Status
 126 --------------
 127
 128 ThreadSanitizer is in beta stage.  It is known to work on large C++ programs
 129 using pthreads, but we do not promise anything (yet).  C++11 threading is
 130 supported with llvm libc++.  The test suite is integrated into CMake build
 131 and can be run with ``make check-tsan`` command.
 132
 133 We are actively working on enhancing the tool --- stay tuned.  Any help,
 134 especially in the form of minimized standalone tests is more than welcome.
 135
 136 More Information
 137 ----------------
 138 `http://code.google.com/p/thread-sanitizer <http://code.google.com/p/thread-sanitizer/>`_.
 139