From 290a8eeeb6e130399ceb97647674e8ddd23fe1e8 Mon Sep 17 00:00:00 2001
From: jruoho <jruoho@NetBSD.org>
Date: Thu, 8 Jul 2010 21:48:07 +0000
Subject: [PATCH] Add some remarks and clarifications, simplify RETURN VALUES,
 grammar, etc.

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

diff --git a/lib/libpthread/pthread_spin.3 b/lib/libpthread/pthread_spin.3
index be2c25f7ae33..ecfe2cf328c1 100644
--- a/lib/libpthread/pthread_spin.3
+++ b/lib/libpthread/pthread_spin.3
@@ -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 @@ The
 .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 @@ function is used to release the read/write lock previously obtained by
 .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.
+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_destroy
-function will 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 @@ These functions conform to
 .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.