From 45936f18b2fbb1ca6647f04675fba92967276249 Mon Sep 17 00:00:00 2001 From: redi Date: Thu, 10 Feb 2011 00:42:02 +0000 Subject: [PATCH] 2011-02-10 Jonathan Wakely * doc/xml/manual/debug.xml: Improve data race docs. git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@169995 138bc75d-0d04-0410-961f-82ee72b054a4 --- libstdc++-v3/ChangeLog | 4 ++++ libstdc++-v3/doc/xml/manual/debug.xml | 37 +++++++++++++++++++---------------- 2 files changed, 24 insertions(+), 17 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 4ffa9cc0117..ae163c72dc2 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,7 @@ +2011-02-10 Jonathan Wakely + + * doc/xml/manual/debug.xml: Improve data race docs. + 2011-02-09 Paolo Carlini PR libstdc++/47668 diff --git a/libstdc++-v3/doc/xml/manual/debug.xml b/libstdc++-v3/doc/xml/manual/debug.xml index 160acebf928..05994ec17a9 100644 --- a/libstdc++-v3/doc/xml/manual/debug.xml +++ b/libstdc++-v3/doc/xml/manual/debug.xml @@ -191,41 +191,44 @@
Data Race Hunting - 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. - We use two annotations (macros) to explain low-level synchronization + Two annotation macros are used 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 + 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. 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 + 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 shared_ptr, but not code which is + only instantiated in the library. + In order to annotate basic_string reference counting it + is necessary to disable extern templates (by defining + _GLIBCXX_EXTERN_TEMPLATE=-1) or to 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. + Annotating the remaining atomic operations (at the time of writing these + are in ios_base::Init::~Init, locale::_Impl and + locale::facet) requires rebuilding the .so file. - 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: - DRD , + DRD, - Helgrind , + Helgrind, and - ThreadSanitizer . + ThreadSanitizer. @@ -235,7 +238,7 @@ #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. + Refer to the documentation of each particular tool for details.
-- 2.11.0