svn commit: r311168 - head/share/man/man9

[Mateusz Guzik]

Author: mjg
Date: Tue Jan  3 20:59:50 2017
New Revision: 311168
URL: https://svnweb.freebsd.org/changeset/base/311168

Log:
  Add the upcoming atomic_fcmpset family to the atomic(9) man page.
  
  These primitives give the caller the read value if the exchange attempt
  failed which saves an explicit reload for cmpset loops.
  
  The man page was partially submitted by kib.
  
  Reviewed by:	kib (previous version), jhb (previous version)

Modified:
  head/share/man/man9/atomic.9

Modified: head/share/man/man9/atomic.9
==============================================================================
--- head/share/man/man9/atomic.9	Tue Jan  3 20:28:48 2017	(r311167)
+++ head/share/man/man9/atomic.9	Tue Jan  3 20:59:50 2017	(r311168)
@@ -23,13 +23,14 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 12, 2016
+.Dd Jan 3, 2017
 .Dt ATOMIC 9
 .Os
 .Sh NAME
 .Nm atomic_add ,
 .Nm atomic_clear ,
 .Nm atomic_cmpset ,
+.Nm atomic_fcmpset ,
 .Nm atomic_fetchadd ,
 .Nm atomic_load ,
 .Nm atomic_readandclear ,
@@ -50,6 +51,12 @@
 .Fa "<type> old"
 .Fa "<type> new"
 .Fc
+.Ft int
+.Fo atomic_fcmpset_[acq_|rel_]<type>
+.Fa "volatile <type> *dst"
+.Fa "<type> *old"
+.Fa "<type> new"
+.Fc
 .Ft <type>
 .Fn atomic_fetchadd_<type> "volatile <type> *p" "<type> v"
 .Ft <type>
@@ -228,6 +235,45 @@ functions are not implemented for the ty
 and
 .Dq Li 16 .
 .Bl -hang
+.It Fn atomic_fcmpset dst *old new
+.El
+.Pp
+On architectures implementing
+.Em Compare And Swap
+operation in hardware, the functionality can be described as
+.Bd -literal -offset indent -compact
+if (*dst == *old) {
+	*dst = new;
+	return (1);
+} else {
+	*old = *dst;
+	return (0);
+}
+.Ed
+On architectures which provide
+.Em Load Linked/Store Conditional
+primitive, the write to
+.Dv *dst
+might also fail for several reasons, most important of which
+is a parallel write to
+.Dv *dst
+cache line by other CPU.
+In this case
+.Fn atomic_fcmpset
+function also returns
+.Dv false ,
+despite
+.Dl *old == *dst .
+.Pp
+The
+.Fn atomic_fcmpset
+functions are not implemented for the types
+.Dq Li char ,
+.Dq Li short ,
+.Dq Li 8 ,
+and
+.Dq Li 16 .
+.Bl -hang
 .It Fn atomic_fetchadd p v
 .Bd -literal -compact
 tmp = *p;
@@ -353,6 +399,16 @@ The
 .Fn atomic_cmpset
 function returns the result of the compare operation.
 The
+.Fn atomic_fcmpset
+function returns
+.Dv true
+if the operationg succeeded.
+Otherwise it returns
+.Dv false
+and sets
+.Va *old
+to the found value.
+The
 .Fn atomic_fetchadd ,
 .Fn atomic_load ,
 .Fn atomic_readandclear ,