re PR libstdc++/45276 (Need to document _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE)

2010-08-18  Kostya Serebryany <kcc@google.com>
	    Paolo Carlini  <paolo.carlini@oracle.com>

	PR libstdc++/45276
	* doc/xml/manual/debug.xml ([debug.races]): Add.

Co-Authored-By: Paolo Carlini <paolo.carlini@oracle.com>

From-SVN: r163342

libstdc++-v3/ChangeLog

+2010-08-18  Kostya Serebryany <kcc@google.com>
+	    Paolo Carlini  <paolo.carlini@oracle.com>
+
+	PR libstdc++/45276
+	* doc/xml/manual/debug.xml ([debug.races]): Add.
+
 2010-08-17  Paolo Carlini  <paolo.carlini@oracle.com>
 
 	PR libstdc++/45300

libstdc++-v3/doc/xml/manual/debug.xml

@@ -189,6 +189,57 @@
 
 </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>