From 3ff91293eb19a5b6fa7fd47ca99b93d57d89570d Mon Sep 17 00:00:00 2001 From: Kostya Serebryany Date: Wed, 18 Aug 2010 15:21:56 +0000 Subject: [PATCH] re PR libstdc++/45276 (Need to document _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE) 2010-08-18 Kostya Serebryany Paolo Carlini PR libstdc++/45276 * doc/xml/manual/debug.xml ([debug.races]): Add. Co-Authored-By: Paolo Carlini From-SVN: r163342 --- libstdc++-v3/ChangeLog | 6 ++++ libstdc++-v3/doc/xml/manual/debug.xml | 51 +++++++++++++++++++++++++++ 2 files changed, 57 insertions(+) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index c0dd0af0485..a8d53090770 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,9 @@ +2010-08-18 Kostya Serebryany + Paolo Carlini + + PR libstdc++/45276 + * doc/xml/manual/debug.xml ([debug.races]): Add. + 2010-08-17 Paolo Carlini PR libstdc++/45300 diff --git a/libstdc++-v3/doc/xml/manual/debug.xml b/libstdc++-v3/doc/xml/manual/debug.xml index 9772c368885..51219d45efd 100644 --- a/libstdc++-v3/doc/xml/manual/debug.xml +++ b/libstdc++-v3/doc/xml/manual/debug.xml @@ -189,6 +189,57 @@ +
Data Race Hunting + + All synchronization primitives used in the library internals should be + understood by race detectors so that they do not produce false reports. + + + + We use two annotations (macros) to explain low-level synchronization + to race detectors: + _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE() and + _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER(). + 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. shared_ptr. + In order to redefine the macros in basic_string one will + need to disable extern templates (by defining + _GLIBCXX_EXTERN_TEMPLATE=-1) or rebuild the + .so file. + The rest of the cases (currently, ios_base::Init::~Init, + locale::_Impl and locale::facet) will require + to rebuild the .so file. + + + + The approach described above works at least with the following race + detection tools: + + DRD , + + Helgrind , + + ThreadSanitizer . + + + + With DRD, Helgrind and ThreadSanitizer you will need to define + the macros like this: + + #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE(A) ANNOTATE_HAPPENS_BEFORE(A) + #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER(A) ANNOTATE_HAPPENS_AFTER(A) + + Refer to the documentation of each particular tool for the details. + + +
+
Using <command>gdb</command>