diff options
| author | dyoung <dyoung@NetBSD.org> | 2010-02-12 22:23:17 +0000 |
|---|---|---|
| committer | dyoung <dyoung@NetBSD.org> | 2010-02-12 22:23:17 +0000 |
| commit | ba71f034aa66234758ceda396ecfcbfdc3a0d73a (patch) | |
| tree | d19cea4ad375b159673389af88f83448ef8440e6 /lib | |
| parent | f88f81fcda91a459ae317a79c0b1bf39c1304cf5 (diff) | |
With help from rmind@, describe the non-interlocked (*_ni) variants of
the standard atomic compare-and-swap operations. Tell some caveats.
Manual page links, *_ni.3 -> atomic_cas.3 are coming up after a
successful 'build.sh distribution'.
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/libc/atomic/atomic_cas.3 | 47 |
1 files changed, 43 insertions, 4 deletions
diff --git a/lib/libc/atomic/atomic_cas.3 b/lib/libc/atomic/atomic_cas.3 index 1d207a752d3..06804b7fc66 100644 --- a/lib/libc/atomic/atomic_cas.3 +++ b/lib/libc/atomic/atomic_cas.3 @@ -1,6 +1,6 @@ -.\" $NetBSD: atomic_cas.3,v 1.1 2008/06/23 10:22:40 ad Exp $ +.\" $NetBSD: atomic_cas.3,v 1.2 2010/02/12 22:23:17 dyoung Exp $ .\" -.\" Copyright (c) 2007 The NetBSD Foundation, Inc. +.\" Copyright (c) 2007, 2010 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation @@ -27,7 +27,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd April 11, 2007 +.Dd February 11, 2010 .Dt ATOMIC_CAS 3 .Os .Sh NAME @@ -36,7 +36,12 @@ .Nm atomic_cas_uint , .Nm atomic_cas_ulong , .Nm atomic_cas_ptr , -.Nm atomic_cas_64 +.Nm atomic_cas_64 , +.Nm atomic_cas_32_ni , +.Nm atomic_cas_uint_ni , +.Nm atomic_cas_ulong_ni , +.Nm atomic_cas_ptr_ni , +.Nm atomic_cas_64_ni .Nd atomic compare-and-swap operations .\" .Sh LIBRARY .\" .Lb libc @@ -54,6 +59,18 @@ .Fn atomic_cas_ptr "volatile void *ptr" "void *old" "void *new" .Ft uint64_t .Fn atomic_cas_64 "volatile uint64_t *ptr" "uint64_t old" "uint64_t new" +.Ft uint32_t +.Fn atomic_cas_32_ni "volatile uint32_t *ptr" "uint32_t old" "uint32_t new" +.Ft unsigned int +.Fn atomic_cas_uint_ni "volatile unsigned int *ptr" "unsigned int old" \ + "unsigned int new" +.Ft unsigned long +.Fn atomic_cas_ulong_ni "volatile unsigned long *ptr" "unsigned long old" \ + "unsigned long new" +.Ft void * +.Fn atomic_cas_ptr_ni "volatile void *ptr" "void *old" "void *new" +.Ft uint64_t +.Fn atomic_cas_64_ni "volatile uint64_t *ptr" "uint64_t old" "uint64_t new" .Sh DESCRIPTION The .Nm atomic_cas @@ -75,6 +92,20 @@ return value to the value passed as .Fa old ; if they are equal then the new value was stored. .Pp +The non-interlocked variants, +.Fn *_ni , +guarantee atomicity within the same CPU with respect to +interrupts and preemption. +For example, they are suitable for synchronizing compare-and-swap +operations on a variable shared by a thread and an interrupt +that are bound to the same CPU. +The +.Fn *_ni +variants are not atomic with respect to different CPUs. +.Fn *_ni +variants should avoid the interprocessor synchronization overhead +of the standard compare-and-swap operations. +.Pp The 64-bit variants of these functions are available only on platforms that can support atomic 64-bit memory access. Applications can check for the availability of 64-bit atomic memory @@ -88,3 +119,11 @@ The .Nm atomic_cas functions first appeared in .Nx 5.0 . +.Sh NOTES +On some architectures, a +.Fn *_ni +variant is merely an alias for the corresponding standard +compare-and-swap operation. +While the non-interlocked variant behaves correctly on those +architectures, it does not avoid the interprocessor synchronization +overhead. |
