Module Name: src
Committed By: jruoho
Date: Thu Jul 8 21:48:08 UTC 2010
Modified Files:
src/lib/libpthread: pthread_spin.3
Log Message:
Add some remarks and clarifications, simplify RETURN VALUES, grammar, etc.
To generate a diff of this commit:
cvs rdiff -u -r1.2 -r1.3 src/lib/libpthread/pthread_spin.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/libpthread/pthread_spin.3
diff -u src/lib/libpthread/pthread_spin.3:1.2 src/lib/libpthread/pthread_spin.3:1.3
--- src/lib/libpthread/pthread_spin.3:1.2 Thu Jul 8 21:35:09 2010
+++ src/lib/libpthread/pthread_spin.3 Thu Jul 8 21:48:07 2010
@@ -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.
+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 @@
.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.
