Check if GCC uses assembler cfi support

[gcc.git] / libitm / libitm.texi

diff --git a/libitm/libitm.texi b/libitm/libitm.texi
index b31657f7f97afe2402a9620b688c607c261081c0..08776f34f1b8ae39b25734f2a5a3cf1921bb97d7 100644 (file)
--- a/libitm/libitm.texi
+++ b/libitm/libitm.texi
@@ -7,7 +7,7 @@
 
 
 @copying
-Copyright @copyright{} 2011 Free Software Foundation, Inc.
+Copyright @copyright{} 2011-2014 Free Software Foundation, Inc.
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.2 or
@@ -69,7 +69,7 @@ several threads.
 * Internals::                  Notes on libitm's internal synchronization.
 * GNU Free Documentation License::
                                How you can copy and share this manual.
-* Index::                      Index of this documentation.
+* Library Index::              Index of this documentation.
 @end menu
 
 
@@ -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
@@ -128,6 +156,13 @@ about which memory locations are shared and which are not shared with other
 threads (i.e., data must be accessed either transactionally or
 nontransactionally). Otherwise, non-write-through TM algorithms would not work.
 
+For memory locations on the stack, this requirement extends to only the
+lifetime of the stack frame that the memory location belongs to (or the
+lifetime of the transaction, whichever is shorter).  Thus, memory that is
+reused for several stack frames could be target of both data logging and
+transactional accesses; however, this is harmless because these stack frames'
+lifetimes will end before the transaction finishes.
+
 @subsection [No changes] Scatter/gather calls
 @subsection [No changes] Serial and irrevocable mode
 @subsection [No changes] Transaction descriptor
@@ -731,8 +766,8 @@ priority inheritance until the TM has priority-aware contention management.
 @c Index
 @c ---------------------------------------------------------------------
 
-@node Index
-@unnumbered Index
+@node Library Index
+@unnumbered Library Index
 
 @printindex cp