[src/trunk]: src/lib/libc/atomic Rework description for clarity; prompted by ...

[dholland <dholland%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/101f033a85d4
branches:  trunk
changeset: 326557:101f033a85d4
user:      dholland <dholland%NetBSD.org@localhost>
date:      Sun Feb 02 17:30:06 2014 +0000

description:
Rework description for clarity; prompted by chat comments from bad@.

diffstat:

 lib/libc/atomic/atomic_cas.3 |  58 +++++++++++++++++++++++--------------------
 1 files changed, 31 insertions(+), 27 deletions(-)

diffs (89 lines):

diff -r 38d5c61a806c -r 101f033a85d4 lib/libc/atomic/atomic_cas.3
--- a/lib/libc/atomic/atomic_cas.3      Sun Feb 02 16:59:13 2014 +0000
+++ b/lib/libc/atomic/atomic_cas.3      Sun Feb 02 17:30:06 2014 +0000
@@ -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 ,