From patchwork Thu Feb 10 00:44:15 2011 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 82553 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) by ozlabs.org (Postfix) with SMTP id 67A9CB711B for ; Thu, 10 Feb 2011 11:44:24 +1100 (EST) Received: (qmail 21768 invoked by alias); 10 Feb 2011 00:44:22 -0000 Received: (qmail 21754 invoked by uid 22791); 10 Feb 2011 00:44:21 -0000 X-SWARE-Spam-Status: No, hits=-2.3 required=5.0 tests=AWL, BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, FREEMAIL_FROM, RCVD_IN_DNSWL_LOW X-Spam-Check-By: sourceware.org Received: from mail-iw0-f175.google.com (HELO mail-iw0-f175.google.com) (209.85.214.175) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Thu, 10 Feb 2011 00:44:17 +0000 Received: by iwn8 with SMTP id 8so764431iwn.20 for ; Wed, 09 Feb 2011 16:44:15 -0800 (PST) MIME-Version: 1.0 Received: by 10.42.179.67 with SMTP id bp3mr22953614icb.57.1297298655359; Wed, 09 Feb 2011 16:44:15 -0800 (PST) Received: by 10.42.230.68 with HTTP; Wed, 9 Feb 2011 16:44:15 -0800 (PST) Date: Thu, 10 Feb 2011 00:44:15 +0000 Message-ID: Subject: [v3] improve docs for data race hunting From: Jonathan Wakely To: "libstdc++" , gcc-patches Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Some minor improvements to the language in these docs 2011-02-10 Jonathan Wakely * doc/xml/manual/debug.xml: Improve data race docs. committed to trunk I haven't committed the regenerated HTML as I'm about to do some more doc changes Index: doc/xml/manual/debug.xml =================================================================== --- doc/xml/manual/debug.xml (revision 169984) +++ doc/xml/manual/debug.xml (working copy) @@ -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.