Re: [PATCH] Clarify __atomic_compare_exchange_n docs

[Sandra Loosemore <sandra@codesourcery.com>]

On 09/29/2015 06:00 AM, Jonathan Wakely wrote:
> 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?

This is OK, as far as it goes, but while we're at it, can we do 
something to fix the description of the weak parameter?

> @@ -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.

What is "weak compare_exchange", and what is "the strong variation", and 
how do they differ in terms of behavior?

-Sandra