Module Name: src
Committed By: dyoung
Date: Fri Feb 12 22:23:17 UTC 2010
Modified Files:
src/lib/libc/atomic: atomic_cas.3
Log Message:
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'.
To generate a diff of this commit:
cvs rdiff -u -r1.1 -r1.2 src/lib/libc/atomic/atomic_cas.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libc/atomic/atomic_cas.3
diff -u src/lib/libc/atomic/atomic_cas.3:1.1 src/lib/libc/atomic/atomic_cas.3:1.2
--- src/lib/libc/atomic/atomic_cas.3:1.1 Mon Jun 23 10:22:40 2008
+++ src/lib/libc/atomic/atomic_cas.3 Fri Feb 12 22:23:17 2010
@@ -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 @@
.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 @@
.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.
