[src/trunk]: src/lib/libpthread Add some remarks and clarifications, simplify...

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

details:   https://anonhg.NetBSD.org/src/rev/848e2d21bbc5
branches:  trunk
changeset: 756220:848e2d21bbc5
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Thu Jul 08 21:48:07 2010 +0000

description:
Add some remarks and clarifications, simplify RETURN VALUES, grammar, etc.

diffstat:

 lib/libpthread/pthread_spin.3 |  60 +++++++++++++++---------------------------
 1 files changed, 21 insertions(+), 39 deletions(-)

diffs (118 lines):

diff -r 21b07d25da82 -r 848e2d21bbc5 lib/libpthread/pthread_spin.3
--- a/lib/libpthread/pthread_spin.3     Thu Jul 08 21:43:58 2010 +0000
+++ b/lib/libpthread/pthread_spin.3     Thu Jul 08 21:48:07 2010 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: pthread_spin.3,v 1.2 2010/07/08 21:35:09 wiz Exp $
+.\" $NetBSD: pthread_spin.3,v 1.3 2010/07/08 21:48:07 jruoho Exp $
 .\"
 .\" Copyright (c) 2002, 2008, 2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -49,13 +49,15 @@
 .Sh DESCRIPTION
 The
 .Fn pthread_spin_init
-function is used to initialize a spinlock.
-The
+function is used to initialize a spin lock.
+In the
+.Nx
+implementation the
 .Fa pshared
-parameter is currently unused and all spinlocks exhibit the
+parameter is currently unused and all spin locks exhibit the
 .Dv PTHREAD_PROCESS_SHARED
-property.
-.Pp
+property, implying that all spin locks may be
+accessed by threads of multiple processes.
 The results of calling
 .Fn pthread_spin_init
 with an already initialized lock are undefined.
@@ -65,23 +67,28 @@
 .Fn pthread_spin_destroy
 function is used to destroy a spin lock previously created with
 .Fn pthread_spin_init .
+It is undefined what happens if the function is called
+when a thread holds the lock, or if the function is called
+with an uninitialized spin lock.
 .Pp
 .\" -----
 The
 .Fn pthread_spin_lock
 function acquires a spin lock on
-.Fa lock
+.Fa lock ,
 provided that
 .Fa lock
 is not presently held.
 If the lock cannot be
 immediately acquired, the calling thread repeatedly retries until it can
 acquire the lock.
+Undefined behavior may follow if the calling thread holds
+the lock at the time the call is made.
 .Pp
 The
 .Fn pthread_spin_trylock
-function performs the same action, but does not block if the lock
-cannot be immediately obtained (i.e., the lock is held).
+function performs the same locking action, but does not block if the lock
+cannot be immediately obtained; if the lock is held, the call fails.
 .Pp
 .\" -----
 The
@@ -90,37 +97,12 @@
 .Fn pthread_spin_lock
 or
 .Fn pthread_spin_trylock .
+The results are undefined if the lock is not held by the calling thread.
+
 .\" ----------------------------------------------------------------------------
 .Sh RETURN VALUES
-If successful, the
-.Fn pthread_spin_init
-function will return zero.
-Otherwise an error number will be returned to indicate the error.
-.Pp
-.\" -----
-If successful, the
-.Fn pthread_spin_destroy
-function will return zero.
+If successful, all described functions return zero.
 Otherwise an error number will be returned to indicate the error.
-.Pp
-.\" -----
-If successful, the
-.Fn pthread_spin_lock
-and
-.Fn pthread_spin_trylock
-functions will return zero.
-Otherwise an error number will be returned to indicate the error.
-.Pp
-.\" -----
-If successful, the
-.Fn pthread_spin_unlock
-function will return zero.
-Otherwise an error number will be returned to indicate the error.
-.Pp
-The results are undefined if
-.Fa lock
-is not held by the calling thread.
-.\" ----------------------------------------------------------------------------
 .Sh ERRORS
 The
 .Fn pthread_spin_init
@@ -214,12 +196,12 @@
 .St -p1003.1-2001 .
 .\" ----------------------------------------------------------------------------
 .Sh CAVEATS
-Applications using spinlocks are vulnerable to the effects of priority
+Applications using spin locks are vulnerable to the effects of priority
 inversion.
 Applications using real-time threads
 .Pq Dv SCHED_FIFO ,
 .Pq Dv SCHED_RR
 should not use these interfaces.
-Outside carefully controlled environments, priority inversion with spinlocks
+Outside carefully controlled environments, priority inversion with spin locks
 can lead to system deadlock.
 Mutexes are preferable in nearly every possible use case.