OpenE2K/gcc
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
Kostya Serebryany 2010-08-18 15:21:56 +00:00 committed by Paolo Carlini
parent 1027c9c5b9
commit 3ff91293eb
2 changed files with 57 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
libstdc++-v3/ChangeLog
View File

@ -1,3 +1,9 @@
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

51
libstdc++-v3/doc/xml/manual/debug.xml
View File

@ -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>