From patchwork Fri Mar 2 17:10:11 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Torvald Riegel X-Patchwork-Id: 144286 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 30EE61007DA for ; Sat, 3 Mar 2012 04:10:45 +1100 (EST) Comment: DKIM? See http://www.dkim.org DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed; d=gcc.gnu.org; s=default; x=1331313046; h=Comment: DomainKey-Signature:Received:Received:Received:Received:Received: Subject:From:To:Cc:Content-Type:Date:Message-ID:Mime-Version: Mailing-List:Precedence:List-Id:List-Unsubscribe:List-Archive: List-Post:List-Help:Sender:Delivered-To; bh=1JK3od363mqxACYqwkgR RLPZwdI=; b=SVAKfOyd6pMe4JYuoX82pqx3CxvBvnb7BNABnPmz8h3LG/pjwtsZ f+E43tDKF8GW3/UKe8BRg5ip4IDNF//PWL3ql8oZ9+inYv+cZtu09zQXFzV5+kBi uKKBAXGvahc7RG7tYeCEw7lPt17NTnPOZXcycSzADB62eva9ICxUQ1o= Comment: DomainKeys? See http://antispam.yahoo.com/domainkeys DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws; s=default; d=gcc.gnu.org; h=Received:Received:X-SWARE-Spam-Status:X-Spam-Check-By:Received:Received:Received:Subject:From:To:Cc:Content-Type:Date:Message-ID:Mime-Version:X-IsSubscribed:Mailing-List:Precedence:List-Id:List-Unsubscribe:List-Archive:List-Post:List-Help:Sender:Delivered-To; b=jAZRnYo5jXO22Sz5gjBR7hsukicBF5xNQOnm00zoWdlsa3RPs5osvoXa8Cm5kc LvSTJ17gkI/GcaTByT+DSNgcXK2e7gZAEvcPi9Qk5MkQP2HZ9emjG9JWkNuDBD7q UNc2zWEt31v4AfCBRFLNK9of1DGEvawsa64My2U65Ahp8=; Received: (qmail 5743 invoked by alias); 2 Mar 2012 17:10:36 -0000 Received: (qmail 5717 invoked by uid 22791); 2 Mar 2012 17:10:34 -0000 X-SWARE-Spam-Status: No, hits=-6.7 required=5.0 tests=AWL, BAYES_00, RCVD_IN_DNSWL_HI, SPF_HELO_PASS, T_RP_MATCHES_RCVD X-Spam-Check-By: sourceware.org Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Fri, 02 Mar 2012 17:10:14 +0000 Received: from int-mx11.intmail.prod.int.phx2.redhat.com (int-mx11.intmail.prod.int.phx2.redhat.com [10.5.11.24]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id q22HAEfA012402 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Fri, 2 Mar 2012 12:10:14 -0500 Received: from [10.36.7.98] (vpn1-7-98.ams2.redhat.com [10.36.7.98]) by int-mx11.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id q22HACnA013010; Fri, 2 Mar 2012 12:10:13 -0500 Subject: libitm: Update texinfo docs. From: Torvald Riegel To: GCC Patches Cc: Richard Henderson , Jakub Jelinek Date: Fri, 02 Mar 2012 18:10:11 +0100 Message-ID: <1330708211.2986.5287.camel@triegel.csb> Mime-Version: 1.0 X-IsSubscribed: yes 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 Just fixed a missing subsection in libitm's texinfo docs. OK for trunk? If so, I'd also think it would be good if this could still get added to 4.7 (sorry for missing the deadline). commit e50b0c9e610fdefce5063de0b88cee6c842694e5 Author: Torvald Riegel Date: Fri Mar 2 18:07:16 2012 +0100 libitm: Update texinfo docs. libitm/ * libitm.texi: Link to specification and add a usage example. diff --git a/libitm/libitm.texi b/libitm/libitm.texi index b31657f..6cfcaf9 100644 --- a/libitm/libitm.texi +++ b/libitm/libitm.texi @@ -82,8 +82,8 @@ several threads. To activate support for TM in C/C++, the compile-time flag @option{-fgnu-tm} must be specified. This enables TM language-level constructs such as -transaction statements (@code{__transaction}, @pxref{C/C++ Language -Constructs for TM} for details). +transaction statements (e.g., @code{__transaction_atomic}, @pxref{C/C++ +Language Constructs for TM} for details). @c --------------------------------------------------------------------- @c C/C++ Language Constructs for TM @@ -92,7 +92,35 @@ Constructs for TM} for details). @node C/C++ Language Constructs for TM @chapter C/C++ Language Constructs for TM -TODO: link to the C++ TM spec. a few examples. how gcc's support differs. +Transactions are supported in C++ and C in the form of transaction statements, +transaction expressions, and function transactions. In the following example, +both @code{a} and @code{b} will be read and the difference will be written to +@code{c}, all atomically and isolated from other transactions: + +@example +__transaction_atomic @{ c = a - b; @} +@end example + +Therefore, another thread can use the following code to concurrently update +@code{b} without ever causing @code{c} to hold a negative value (and without +having to use other synchronization constructs such as locks or C++11 +atomics): + +@example +__transaction_atomic @{ if (a > b) b++; @} +@end example + +GCC follows the @uref{https://sites.google.com/site/tmforcplusplus/, Draft +Specification of Transactional Language Constructs for C++ (v1.1)} in its +implementation of transactions. + +The precise semantics of transactions are defined in terms of the C++11/C11 +memory model (see the specification). Roughly, transactions provide +synchronization guarantees that are similar to what would be guaranteed when +using a single global lock as a guard for all transactions. Note that like +other synchronization constructs in C/C++, transactions rely on a +data-race-free program (e.g., a nontransactional write that is concurrent +with a transactional read to the same memory location is a data race). @c --------------------------------------------------------------------- @c The libitm ABI