[PATCH] c/52190 update __atomic documentation

[PATCH] c/52190 update __atomic documentation

[Andrew MacLeod]

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


Updated the extra parameter to __atomic_{is,always}_lock_free , and bkoz 
noted that the __atomic_compare_exchange documentation did not document 
the 'weak' parameter.

Fixed as such, seems to format fine.  OK for mainline?

Andrew



[-- Attachment #2: doc.diff --]
[-- Type: text/plain, Size: 3592 bytes --]

	PR c/52190
	* doc/extend.texi : Update comments for __atomic_compare_exchange and
	__atomic_{is,always}_lock_free.

Index: doc/extend.texi
===================================================================
*** doc/extend.texi	(revision 183969)
--- doc/extend.texi	(working copy)
*************** This built-in function implements an ato
*** 7146,7152 ****
  This compares the contents of @code{*@var{ptr}} with the contents of
  @code{*@var{expected}} and if equal, writes @var{desired} into
  @code{*@var{ptr}}.  If they are not equal, the current contents of
! @code{*@var{ptr}} is written into @code{*@var{expected}}.
  
  True is returned if @code{*@var{desired}} is written into
  @code{*@var{ptr}} and the execution is considered to conform to the
--- 7146,7155 ----
  This compares the contents of @code{*@var{ptr}} with the contents of
  @code{*@var{expected}} and if equal, writes @var{desired} into
  @code{*@var{ptr}}.  If they are not equal, 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 
! only offer the strong variation and ignore the parameter.  When in doubt, use
! the strong variation.
  
  True is returned if @code{*@var{desired}} is written into
  @code{*@var{ptr}} and the execution is considered to conform to the
*************** All memory orders are valid.
*** 7242,7268 ****
  
  @end deftypefn
  
! @deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size)
  
! This built-in function returns true if objects of size bytes will always
! generate lock free atomic instructions for the target architecture.
! Otherwise false is returned.
  
! size must resolve to a compile time constant.
  
  @smallexample
! if (_atomic_always_lock_free (sizeof (long long)))
  @end smallexample
  
  @end deftypefn
  
! @deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size)
  
! This built-in function returns true if objects of size bytes will always
  generate lock free atomic instructions for the target architecture.  If
  it is not known to be lock free a call is made to a runtime routine named
  @code{__atomic_is_lock_free}.
  
  @end deftypefn
  
  @node Object Size Checking
--- 7245,7276 ----
  
  @end deftypefn
  
! @deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size,  void *ptr)
  
! This built-in function returns true if objects of @var{size} bytes will always
! generate lock free atomic instructions for the target architecture.  
! @var{size} must resolve to a compile time constant and the result also resolves to compile time constant.
  
! @var{ptr} is an optional pointer to the object which may be used to determine
! 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))
  @end smallexample
  
  @end deftypefn
  
! @deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr)
  
! This built-in function returns true if objects of @var{size} bytes will always
  generate lock free atomic instructions for the target architecture.  If
  it is not known to be lock free a call is made to a runtime routine named
  @code{__atomic_is_lock_free}.
  
+ @var{ptr} is an optional pointer to the object which may be used to determine
+ alignment.  A value of 0 indicates typical alignment should be used.  The 
+ compiler may also ignore this parameter.
  @end deftypefn
  
  @node Object Size Checking

Re: [PATCH] c/52190 update __atomic documentation

[Joseph S. Myers]

On Fri, 10 Feb 2012, Andrew MacLeod wrote:

> Updated the extra parameter to __atomic_{is,always}_lock_free , and bkoz noted
> that the __atomic_compare_exchange documentation did not document the 'weak'
> parameter.
> 
> Fixed as such, seems to format fine.  OK for mainline?

OK.

-- 
Joseph S. Myers
joseph@codesourcery.com