Someone on IRC incorrectly parsed the docs at
https://gcc.gnu.org/onlinedocs/gcc-5.2.0/gcc/_005f_005fatomic-Builtins.html#index-g_t_005f_005fatomic_005fcompare_005fexchange_005fn-3536
as:
IF
(
desired is written into *ptr
AND
the execution is considered to conform to the memory model
specified by success_memmodel.
)
{
true is returned
}
otherwise ...
rather than the intended:
IF ( desired is written into *ptr )
{
true is returned
AND
the execution is considered to conform to the memory model
specified by success_memmodel.
}
otherwise ...
So they asked:
What is otherwise, here? Can I make the function return false even
when 'desired' has been written into 'ptr'? How do I do it? I could
not write an example, so far.
This patch rewords it to avoid the ambiguity.
I've also replaced the rather clunky "the operation is considered to
conform to" phrasing. (It's only _considered_ to? So does it or doesn't
it use that memory order?) Instead I've used the terminology from the
C and C++ standards, which say "memory is affected according to".
OK for trunk?
commit 370a92b7f4d318957a70d0d3f1185f1c6f282ff3
Author: Jonathan Wakely <jwak...@redhat.com>
Date: Tue Sep 29 12:45:21 2015 +0100
* doc/extend.texi (__atomic Builtins): Clarify compare_exchange
effects.
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 8406945..0de94f2 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -9353,17 +9353,17 @@ 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
+@code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is true
for weak compare_exchange, and false for the strong variation. 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}.
