[PATCH] Clarify __atomic_compare_exchange_n docs

[Jonathan Wakely <jwakely@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 1123 bytes --]

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?


[-- Attachment #2: patch.txt --]
[-- Type: text/x-patch, Size: 1698 bytes --]

commit 370a92b7f4d318957a70d0d3f1185f1c6f282ff3
Author: Jonathan Wakely <jwakely@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}.