diff options
| author | Kostya Serebryany <kcc@google.com> | 2010-08-18 15:21:56 +0000 |
|---|---|---|
| committer | Paolo Carlini <paolo@gcc.gnu.org> | 2010-08-18 15:21:56 +0000 |
| commit | 3ff91293eb19a5b6fa7fd47ca99b93d57d89570d (patch) | |
| tree | 7ec1128f3daadc6b1a77eb6d68d91f1fd28c47b4 /libstdc++-v3 | |
| parent | 1027c9c5b9c0d3d60fe1eb711bd97c8432c6cfb6 (diff) | |
| download | gcc-3ff91293eb19a5b6fa7fd47ca99b93d57d89570d.zip gcc-3ff91293eb19a5b6fa7fd47ca99b93d57d89570d.tar.gz gcc-3ff91293eb19a5b6fa7fd47ca99b93d57d89570d.tar.bz2 | |
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
Diffstat (limited to 'libstdc++-v3')
| -rw-r--r-- | libstdc++-v3/ChangeLog | 6 | ||||
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/debug.xml | 51 |
2 files changed, 57 insertions, 0 deletions
diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index c0dd0af..a8d5309 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -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 diff --git a/libstdc++-v3/doc/xml/manual/debug.xml b/libstdc++-v3/doc/xml/manual/debug.xml index 9772c36..51219d4 100644 --- a/libstdc++-v3/doc/xml/manual/debug.xml +++ b/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> |