Date: Thu, 16 Mar 2017 07:51:34 +0000 (UTC) From: Mateusz Guzik <mjg@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-11@freebsd.org Subject: svn commit: r315392 - stable/11/share/man/man9 Message-ID: <201703160751.v2G7pYLO014076@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: mjg Date: Thu Mar 16 07:51:34 2017 New Revision: 315392 URL: https://svnweb.freebsd.org/changeset/base/315392 Log: MFC r311168,r311171: 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. == Fix typo Modified: stable/11/share/man/man9/atomic.9 Directory Properties: stable/11/ (props changed) Modified: stable/11/share/man/man9/atomic.9 ============================================================================== --- stable/11/share/man/man9/atomic.9 Thu Mar 16 07:46:24 2017 (r315391) +++ stable/11/share/man/man9/atomic.9 Thu Mar 16 07:51:34 2017 (r315392) @@ -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 operation succeeded. +Otherwise it returns +.Dv false +and sets +.Va *old +to the found value. +The .Fn atomic_fetchadd , .Fn atomic_load , .Fn atomic_readandclear ,
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201703160751.v2G7pYLO014076>