</section>
+<section xml:id="debug.races"><info><title>Data Race Hunting</title></info>
+<para>
+ All synchronization primitives used in the library internals should be
+ understood by race detectors so that they do not produce false reports.
+</para>
+
+<para>
+ We use two annotations (macros) to explain low-level synchronization
+ to race detectors:
+ <code>_GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE()</code> and
+ <code> _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER()</code>.
+ By default, these two macros are defined empty -- anyone who wants
+ to use a race detector will need to redefine these macros to call an
+ appropriate API.
+ Since these macros are empty by default, redefining them in the user code
+ will affect only the inline template code, e.g. <code>shared_ptr</code>.
+ In order to redefine the macros in <code>basic_string</code> one will
+ need to disable extern templates (by defining
+ <code>_GLIBCXX_EXTERN_TEMPLATE=-1</code>) or rebuild the
+ <code>.so</code> file.
+ The rest of the cases (currently, <code>ios_base::Init::~Init</code>,
+ <code>locale::_Impl</code> and <code>locale::facet</code>) will require
+ to rebuild the <code>.so</code> file.
+</para>
+
+<para>
+ The approach described above works at least with the following race
+ detection tools:
+ <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="http://valgrind.org/docs/manual/drd-manual.html">
+ DRD </link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="http://valgrind.org/docs/manual/hg-manual.html">
+ Helgrind </link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="http://code.google.com/p/data-race-test">
+ ThreadSanitizer </link>.
+</para>
+
+<para>
+ With DRD, Helgrind and ThreadSanitizer you will need to define
+ the macros like this:
+<programlisting>
+ #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE(A) ANNOTATE_HAPPENS_BEFORE(A)
+ #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER(A) ANNOTATE_HAPPENS_AFTER(A)
+</programlisting>
+ Refer to the documentation of each particular tool for the details.
+</para>
+
+</section>
+
<section xml:id="debug.gdb"><info><title>Using <command>gdb</command></title></info>
<para>