mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-23 11:18:54 +00:00
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)
This commit is contained in:
parent
fa699bb23e
commit
c0b995bb1b
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=311168
@ -23,13 +23,14 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" $FreeBSD$
|
.\" $FreeBSD$
|
||||||
.\"
|
.\"
|
||||||
.Dd May 12, 2016
|
.Dd Jan 3, 2017
|
||||||
.Dt ATOMIC 9
|
.Dt ATOMIC 9
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
.Nm atomic_add ,
|
.Nm atomic_add ,
|
||||||
.Nm atomic_clear ,
|
.Nm atomic_clear ,
|
||||||
.Nm atomic_cmpset ,
|
.Nm atomic_cmpset ,
|
||||||
|
.Nm atomic_fcmpset ,
|
||||||
.Nm atomic_fetchadd ,
|
.Nm atomic_fetchadd ,
|
||||||
.Nm atomic_load ,
|
.Nm atomic_load ,
|
||||||
.Nm atomic_readandclear ,
|
.Nm atomic_readandclear ,
|
||||||
@ -50,6 +51,12 @@
|
|||||||
.Fa "<type> old"
|
.Fa "<type> old"
|
||||||
.Fa "<type> new"
|
.Fa "<type> new"
|
||||||
.Fc
|
.Fc
|
||||||
|
.Ft int
|
||||||
|
.Fo atomic_fcmpset_[acq_|rel_]<type>
|
||||||
|
.Fa "volatile <type> *dst"
|
||||||
|
.Fa "<type> *old"
|
||||||
|
.Fa "<type> new"
|
||||||
|
.Fc
|
||||||
.Ft <type>
|
.Ft <type>
|
||||||
.Fn atomic_fetchadd_<type> "volatile <type> *p" "<type> v"
|
.Fn atomic_fetchadd_<type> "volatile <type> *p" "<type> v"
|
||||||
.Ft <type>
|
.Ft <type>
|
||||||
@ -228,6 +235,45 @@ functions are not implemented for the types
|
|||||||
and
|
and
|
||||||
.Dq Li 16 .
|
.Dq Li 16 .
|
||||||
.Bl -hang
|
.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
|
.It Fn atomic_fetchadd p v
|
||||||
.Bd -literal -compact
|
.Bd -literal -compact
|
||||||
tmp = *p;
|
tmp = *p;
|
||||||
@ -353,6 +399,16 @@ The
|
|||||||
.Fn atomic_cmpset
|
.Fn atomic_cmpset
|
||||||
function returns the result of the compare operation.
|
function returns the result of the compare operation.
|
||||||
The
|
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_fetchadd ,
|
||||||
.Fn atomic_load ,
|
.Fn atomic_load ,
|
||||||
.Fn atomic_readandclear ,
|
.Fn atomic_readandclear ,
|
||||||
|
Loading…
Reference in New Issue
Block a user