git
/
gcc
mirror of git://gcc.gnu.org/git/gcc.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

debug.xml: Improve data race docs. 

2011-02-10  Jonathan Wakely  <jwakely.gcc@gmail.com>

	* doc/xml/manual/debug.xml: Improve data race docs.

From-SVN: r169995
This commit is contained in:
Jonathan Wakely 2011-02-10 00:42:02 +00:00 committed by Jonathan Wakely
parent a58cf9794b
commit 4b09b79915
2 changed files with 24 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
libstdc++-v3/ChangeLog
View File

@ -1,3 +1,7 @@
2011-02-10 Jonathan Wakely <jwakely.gcc@gmail.com>
* doc/xml/manual/debug.xml: Improve data race docs.
2011-02-09 Paolo Carlini <paolo.carlini@oracle.com>
PR libstdc++/47668

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

@ -191,41 +191,44 @@
<section xml:id="debug.races"><info><title>Data Race Hunting</title></info>
<para>
All synchronization primitives used in the library internals should be
All synchronization primitives used in the library internals need to 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
Two annotation macros are used 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
By default, these macros are defined empty -- anyone who wants
to use a race detector needs to redefine them 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
Since these macros are empty by default when the library is built,
redefining them will only affect inline functions and template
instantiations which are compiled in user code. This allows annotation
of templates such as <code>shared_ptr</code>, but not code which is
only instantiated in the library.
In order to annotate <code>basic_string</code> reference counting it
is necessary to disable extern templates (by defining
<code>_GLIBCXX_EXTERN_TEMPLATE=-1</code>) or to 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.
Annotating the remaining atomic operations (at the time of writing these
are in <code>ios_base::Init::~Init</code>, <code>locale::_Impl</code> and
<code>locale::facet</code>) requires rebuilding the <code>.so</code> file.
</para>
<para>
The approach described above works at least with the following race
The approach described above is known to work 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>,
DRD</link>,
<link xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="http://valgrind.org/docs/manual/hg-manual.html">
Helgrind </link>,
Helgrind</link>, and
<link xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="http://code.google.com/p/data-race-test">
ThreadSanitizer </link>.
ThreadSanitizer</link>.
</para>
<para>
@ -235,7 +238,7 @@
#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.
Refer to the documentation of each particular tool for details.
</para>
</section>