Patchwork libitm: Update texinfo docs.

login
register
mail settings
Submitter Torvald Riegel
Date March 2, 2012, 5:10 p.m.
Message ID <1330708211.2986.5287.camel@triegel.csb>
Download mbox | patch
Permalink /patch/144286/
State New
Headers show

Comments

Torvald Riegel - March 2, 2012, 5:10 p.m.
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 <triegel@redhat.com>
Date:   Fri Mar 2 18:07:16 2012 +0100

    libitm: Update texinfo docs.
    
    	libitm/
    	* libitm.texi: Link to specification and add a usage example.
Richard Henderson - March 2, 2012, 5:35 p.m.
On 03/02/2012 09:10 AM, Torvald Riegel wrote:
>     libitm: Update texinfo docs.
>     
>     	libitm/
>     	* libitm.texi: Link to specification and add a usage example.

I would think this should still be ok for 4.7...


r~
Jakub Jelinek - March 2, 2012, 6:06 p.m.
On Fri, Mar 02, 2012 at 09:35:18AM -0800, Richard Henderson wrote:
> On 03/02/2012 09:10 AM, Torvald Riegel wrote:
> >     libitm: Update texinfo docs.
> >     
> >     	libitm/
> >     	* libitm.texi: Link to specification and add a usage example.
> 
> I would think this should still be ok for 4.7...

Yes, it is.

	Jakub

Patch

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