This is the mail archive of the
gcc-bugs@gcc.gnu.org
mailing list for the GCC project.
[Bug libstdc++/45276] New: Need to document _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE
- From: "konstantin dot s dot serebryany at gmail dot com" <gcc-bugzilla at gcc dot gnu dot org>
- To: gcc-bugs at gcc dot gnu dot org
- Date: 13 Aug 2010 11:34:52 -0000
- Subject: [Bug libstdc++/45276] New: Need to document _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE
- Reply-to: gcc-bugzilla at gcc dot gnu dot org
As of r163210 (http://gcc.gnu.org/viewcvs?view=revision&revision=163210)
libstdc++ has two new macros:
_GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE
_GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER
and a short documentation for them in include/bits/c++config
I propose to add a more detailed documentation (though I don't know the exact
place where to add it).
The proposed text follows. See also the discussion at
http://old.nabble.com/Re:-libstdc%2B%2B-and-race-detectors-to29116684.html
Support for race detectors.
All synchronization primitives used in the library internals should be
understood by race detectors so that the race detectors 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
appropriate race detector API.
Since these macros are empty by default, redefining them in the user code
will affect only the inline template code, i.e. 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.
The rest of the cases will require to rebuild the .so:
- ios_base::Init::~Init
- locale::_Impl and locale::facet
The approach described above works at least with the following
race detection tools:
- DRD, http://valgrind.org/docs/manual/drd-manual.html
- Helgrind, http://valgrind.org/docs/manual/hg-manual.html
- Intel Parallel Inspector,
http://software.intel.com/en-us/intel-parallel-inspector
- ThreadSanitizer, http://code.google.com/p/data-race-test
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);
For Intel Parallel Inspector:
#define _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE(a)
itt_notify_sync_releasing(a);
#define _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER(a) itt_notify_sync_acquired(a);
Refer to the documentation of a particular tool for the details.
--
Summary: Need to document _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE
Product: gcc
Version: 4.6.0
Status: UNCONFIRMED
Severity: normal
Priority: P3
Component: libstdc++
AssignedTo: unassigned at gcc dot gnu dot org
ReportedBy: konstantin dot s dot serebryany at gmail dot com
http://gcc.gnu.org/bugzilla/show_bug.cgi?id=45276