This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
Re: [PATCH] Clarify __atomic_compare_exchange_n docs
- From: Jonathan Wakely <jwakely at redhat dot com>
- To: Sandra Loosemore <sandra at codesourcery dot com>
- Cc: Andrew Haley <aph at redhat dot com>, gcc-patches at gcc dot gnu dot org
- Date: Sat, 3 Oct 2015 14:00:26 +0100
- Subject: Re: [PATCH] Clarify __atomic_compare_exchange_n docs
- Authentication-results: sourceware.org; auth=none
- References: <20150929120038 dot GW12094 at redhat dot com> <560AAC7B dot 4030904 at codesourcery dot com> <560D18EB dot 5090900 at redhat dot com> <560D73F5 dot 9090908 at codesourcery dot com> <20151001183518 dot GL12094 at redhat dot com> <20151001184007 dot GN12094 at redhat dot com>
Here's the latest version of the patch, including the typo fix.
commit 96468d6b7e782501459bad306b31d45bc0ba5155
Author: Jonathan Wakely <jwakely@redhat.com>
Date: Sat Oct 3 13:59:47 2015 +0100
Clarify __atomic_compare_exchange effects
* doc/extend.texi (__atomic Builtins): Clarify compare_exchange
effects.
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 8406945..599ad87 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -9353,17 +9353,18 @@ This compares the contents of @code{*@var{ptr}} with the contents of
@code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write}
operation that writes @var{desired} into @code{*@var{ptr}}. If they are not
equal, the operation is a @emph{read} and the current contents of
-@code{*@var{ptr}} is written into @code{*@var{expected}}. @var{weak} is true
-for weak compare_exchange, and false for the strong variation. Many targets
+@code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is true
+for weak compare_exchange, which may fail spuriously, and false for
+the strong variation, which never fails spuriously. Many targets
only offer the strong variation and ignore the parameter. When in doubt, use
the strong variation.
-True is returned if @var{desired} is written into
-@code{*@var{ptr}} and the operation is considered to conform to the
+If @var{desired} is written into @code{*@var{ptr}} then true is returned
+and memory is affected according to the
memory order specified by @var{success_memorder}. There are no
restrictions on what memory order can be used here.
-False is returned otherwise, and the operation is considered to conform
+Otherwise, false is returned and memory is affected according
to @var{failure_memorder}. This memory order cannot be
@code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a
stronger order than that specified by @var{success_memorder}.
@@ -9470,7 +9471,7 @@ alignment. A value of 0 indicates typical alignment should be used. The
compiler may also ignore this parameter.
@smallexample
-if (_atomic_always_lock_free (sizeof (long long), 0))
+if (__atomic_always_lock_free (sizeof (long long), 0))
@end smallexample
@end deftypefn