I was looking at PR94108 ("transaction memory attributes not
documented") and found that the link to the spec that defines these
attributes was (a) to the internal API document rather than the C++
interface document and (b) dead. From discussion on IRC and in the
mail archives it appears that the transactional memory feature is not
really usable but there is resistance to deprecating and/or removing
it. I've settled on just warning readers that it is obsolete and not
really usable, as well as digging up working links to both documents.
This patch doesn't address PR94108 as there seems to be little value
in telling readers about features that are not really useful.
gcc/ChangeLog
* doc/invoke.texi (C Dialect Options) <-fgnu-tm>: Do not describe
the 2009 document as "current". Warn readers this is an experimental
and unmaintained feature. Update pointer to libitm documentation.
libitm/ChangeLog
* libitm.texi (Implementation Status): New section, consolidating
bits of information formerly found elsewhere including...
(Enabling libitm): ...here.
(The libitm ABI): Do not describe the 2009 document as "current".
---
gcc/doc/invoke.texi | 20 +++++++++-----------
libitm/libitm.texi | 30 ++++++++++++++++++++++++------
2 files changed, 33 insertions(+), 17 deletions(-)
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 00f470a0d5d..56de3bc79ee 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -2757,18 +2757,16 @@ passes.
@opindex fno-gnu-tm
@item -fgnu-tm
When the option @option{-fgnu-tm} is specified, the compiler
-generates code for the Linux variant of Intel's current Transactional
-Memory ABI specification document (Revision 1.1, May 6 2009). This is
-an experimental feature whose interface may change in future versions
-of GCC, as the official specification changes. Please note that not
-all architectures are supported for this feature.
+generates code for the Linux variant of Intel's Transactional
+Memory ABI specification document (draft Revision 1.1, May 6 2009). This is
+an experimental feature and has not been maintained for some time; newer
+proposals for transactional memory in the C++ language are substantially
+different.
-For more information on GCC's support for transactional memory,
-@xref{Enabling libitm,,The GNU Transactional Memory Library,libitm,GNU
-Transactional Memory Library}.
-
-Note that the transactional memory feature is not supported with
-non-call exceptions (@option{-fnon-call-exceptions}).
+For more information on GCC's support for transactional memory and limitations
+of the current implementation,
+@xref{Implementation Status,Implementation Status,Implementation Status,
+libitm,The GNU Transactional Memory Library}.
@opindex fgnu89-inline
@opindex fno-gnu89-inline
diff --git a/libitm/libitm.texi b/libitm/libitm.texi
index d7c5626a4be..f43297b52e4 100644
--- a/libitm/libitm.texi
+++ b/libitm/libitm.texi
@@ -54,13 +54,13 @@ Memory Library. It provides transaction support for
accesses to a process'
memory, enabling easy-to-use synchronization of accesses to shared memory by
several threads.
-
@comment
@comment When you add a new menu item, please keep the right hand
@comment aligned to the same column. Do not use tabs. This provides
@comment better formatting.
@comment
@menu
+* Implementation Status:: Transactional Memory is experimental.
* Enabling libitm:: How to enable libitm for your applications.
* C/C++ Language Constructs for TM::
Notes on the language-level interface supported
@@ -72,6 +72,28 @@ several threads.
* Library Index:: Index of this documentation.
@end menu
+@node Implementation Status
+@chapter Implementation Status
+
+GCC follows the
+@uref{https://www.open-std.org/jtc1/sc22/wg14/www/docs/n1613.pdf,
+Draft Specification of Transactional Language Constructs for C++},
+version 1.1 dated February 3, 2011, and the
+@uref{https://gcc.gnu.org/wiki/TransactionalMemory,
+Intel Transactional Memory Compiler and Runtime Application Binary Interface}
+document identified as revision 1.1 (Draft) and dated May 6, 2009,
+in its implementation of transactional memory.
+
+Be aware that GCC's support for transactional memory is an
+experimental feature and has not been maintained for some time; newer
+proposals for transactional memory in the C++ language are
+substantially different.
+
+Please note that not all architectures are supported for this feature
+and additional limitations and caveats appear throughout this document.
+Transactional memory is also known to conflict with link-time optimization
+(@option{-flto}) and non-call exceptions (@option{-fnon-call-exceptions}).
+
@c ---------------------------------------------------------------------
@c Enabling libitm
@@ -110,10 +132,6 @@ atomics):
__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
@@ -130,7 +148,7 @@ with a transactional read to the same memory location is a
data race).
@chapter The libitm ABI
The ABI provided by libitm is basically equal to the Linux variant of Intel's
-current TM ABI specification document (Revision 1.1, May 6 2009) but with the
+TM ABI specification document (Revision 1.1, May 6 2009) but with the
differences listed in this chapter. It would be good if these changes would
eventually be merged into a future version of this specification. To ease
look-up, the following subsections mirror the structure of this specification.
--
2.39.5
