Module Name: src
Committed By: dholland
Date: Sun Feb 2 17:30:06 UTC 2014
Modified Files:
src/lib/libc/atomic: atomic_cas.3
Log Message:
Rework description for clarity; prompted by chat comments from bad@.
To generate a diff of this commit:
cvs rdiff -u -r1.2 -r1.3 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.2 src/lib/libc/atomic/atomic_cas.3:1.3
--- src/lib/libc/atomic/atomic_cas.3:1.2 Fri Feb 12 22:23:17 2010
+++ src/lib/libc/atomic/atomic_cas.3 Sun Feb 2 17:30:06 2014
@@ -1,4 +1,4 @@
-.\" $NetBSD: atomic_cas.3,v 1.2 2010/02/12 22:23:17 dyoung Exp $
+.\" $NetBSD: atomic_cas.3,v 1.3 2014/02/02 17:30:06 dholland Exp $
.\"
.\" Copyright (c) 2007, 2010 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -48,49 +48,53 @@
.Sh SYNOPSIS
.In sys/atomic.h
.Ft uint32_t
-.Fn atomic_cas_32 "volatile uint32_t *ptr" "uint32_t old" "uint32_t new"
+.Fn atomic_cas_32 "volatile uint32_t *ptr" "uint32_t expected" "uint32_t new"
.Ft unsigned int
-.Fn atomic_cas_uint "volatile unsigned int *ptr" "unsigned int old" \
+.Fn atomic_cas_uint "volatile unsigned int *ptr" "unsigned int expected" \
"unsigned int new"
.Ft unsigned long
-.Fn atomic_cas_ulong "volatile unsigned long *ptr" "unsigned long old" \
+.Fn atomic_cas_ulong "volatile unsigned long *ptr" "unsigned long expected" \
"unsigned long new"
.Ft void *
-.Fn atomic_cas_ptr "volatile void *ptr" "void *old" "void *new"
+.Fn atomic_cas_ptr "volatile void *ptr" "void *expected" "void *new"
.Ft uint64_t
-.Fn atomic_cas_64 "volatile uint64_t *ptr" "uint64_t old" "uint64_t new"
+.Fn atomic_cas_64 "volatile uint64_t *ptr" "uint64_t expected" "uint64_t new"
.Ft uint32_t
-.Fn atomic_cas_32_ni "volatile uint32_t *ptr" "uint32_t old" "uint32_t new"
+.Fn atomic_cas_32_ni "volatile uint32_t *ptr" "uint32_t expected" \
+ "uint32_t new"
.Ft unsigned int
-.Fn atomic_cas_uint_ni "volatile unsigned int *ptr" "unsigned int old" \
+.Fn atomic_cas_uint_ni "volatile unsigned int *ptr" "unsigned int expected" \
"unsigned int new"
.Ft unsigned long
-.Fn atomic_cas_ulong_ni "volatile unsigned long *ptr" "unsigned long old" \
- "unsigned long new"
+.Fn atomic_cas_ulong_ni "volatile unsigned long *ptr" \
+ "unsigned long expected" "unsigned long new"
.Ft void *
-.Fn atomic_cas_ptr_ni "volatile void *ptr" "void *old" "void *new"
+.Fn atomic_cas_ptr_ni "volatile void *ptr" "void *expected" "void *new"
.Ft uint64_t
-.Fn atomic_cas_64_ni "volatile uint64_t *ptr" "uint64_t old" "uint64_t new"
+.Fn atomic_cas_64_ni "volatile uint64_t *ptr" "uint64_t expected" \
+ "uint64_t new"
.Sh DESCRIPTION
The
.Nm atomic_cas
-family of functions perform a compare-and-swap operation in an atomic fashion.
-The value of the variable referenced by
-.Fa ptr
-is compared against
-.Fa old .
-If the values are equal,
+family of functions perform an atomic conditional assignment.
+The value
.Fa new
-is stored in the variable referenced by
+is assigned to the variable referenced by
.Fa ptr .
-.Pp
-The old value of the variable referenced by
-.Fa ptr
-is always returned regardless of whether or not the new value was stored.
-Applications can test for success of the operation by comparing the
-return value to the value passed as
-.Fa old ;
-if they are equal then the new value was stored.
+The assignment succeeds
+if and only if its current value matches the value
+.Fa expected .
+If the value is different, the assignment fails and no change is
+made.
+This operation is sometimes known as
+.Dq compare-and-swap .
+These functions always return the value found via
+.Fa ptr .
+Callers test for success by comparing the return value to the value
+passed as
+.Fa expected ;
+if they are equal then the new value was stored; if they are not, the
+value was not changed.
.Pp
The non-interlocked variants,
.Fn *_ni ,
