Re: libstdc++ and race detectors

[Kostya Serebryany <kcc at google dot com>]

>> I noticed it, really informative, thanks! Well, it would be nice if you
>> could massage all that information to an actual patch. At your ease, of
>> course...
>
> Sure.

Here is my first draft. Please comment.
http://codereview.appspot.com/download/issue1974042_1_2.diff
I validated and built the docs on Ubuntu Lucid using these commands:
  make doc-xml-validate-docbook
XSL_STYLE_DIR=/usr/share/xml/docbook/stylesheet/docbook-xsl-ns
SCHEMA_FLAGS="--dtdvalid
/usr/share/xml/docbook/schema/dtd/5.0/docbook.dtd"
  make doc-html-docbook
XSL_STYLE_DIR=/usr/share/xml/docbook/stylesheet/docbook-xsl-ns

Thanks,
--kcc


Index: doc/xml/manual/debug.xml
===================================================================
--- doc/xml/manual/debug.xml	(revision 163281)
+++ doc/xml/manual/debug.xml	(working copy)
@@ -189,6 +189,59 @@

 </section>

+<section xml:id="debug.races"><info><title>Data Race Hunting</title></info>
+  <para>
+  Libstdc++ does not create threads, but it is used in multi-threaded code
+  and internals of libstdc++ contain synchronization.
+  All synchronization primitives used in the library internals should be
+  understood by race detectors so that the race detectors 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
+  appropriate race detector API.
+  Since these macros are empty by default, redefining them in the user code
+  will affect only the inline template code, i.e. <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 (<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>,
+  and the non-free commercial product
+  <link xmlns:xlink="http://www.w3.org/1999/xlink";
xlink:href="http://software.intel.com/en-us/intel-parallel-inspector";>
Intel Parallel Inspector </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>
+  For Intel Parallel Inspector:
+<programlisting>
+  #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE(a)
itt_notify_sync_releasing(a)
+  #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER(a)
itt_notify_sync_acquired(a)
+</programlisting>
+  Refer to the documentation of a particular tool for the details.
+  </para>
+</section>
+
 <section xml:id="debug.gdb"><info><title>Using
<command>gdb</command></title></info>

   <para>