Bug 45276 - Need to document _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE
Summary: Need to document _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE
Status: RESOLVED FIXED
Alias: None
Product: gcc
Classification: Unclassified
Component: libstdc++ (show other bugs)
Version: 4.6.0
: P3 normal
Target Milestone: 4.6.0
Assignee: Not yet assigned to anyone
URL:
Keywords: documentation
Depends on:
Blocks:
 
Reported: 2010-08-13 11:34 UTC by Konstantin Serebryany
Modified: 2010-08-18 15:24 UTC (History)
3 users (show)

See Also:
Host:
Target:
Build:
Known to work:
Known to fail:
Last reconfirmed: 2010-08-13 11:50:12


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Konstantin Serebryany 2010-08-13 11:34:51 UTC
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.
Comment 1 Jonathan Wakely 2010-08-13 11:50:12 UTC
(In reply to comment #0)
> I propose to add a more detailed documentation (though I don't know the exact
> place where to add it). 

maybe http://gcc.gnu.org/onlinedocs/libstdc++/manual/debug.html

The html docs are generated from docbook sources in libstdc++-v3/doc/xml/manual
Comment 2 paolo@gcc.gnu.org 2010-08-18 15:22:34 UTC
Subject: Bug 45276

Author: paolo
Date: Wed Aug 18 15:21:56 2010
New Revision: 163342

URL: http://gcc.gnu.org/viewcvs?root=gcc&view=rev&rev=163342
Log:
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.

Modified:
    trunk/libstdc++-v3/ChangeLog
    trunk/libstdc++-v3/doc/xml/manual/debug.xml

Comment 3 Paolo Carlini 2010-08-18 15:24:20 UTC
Done.