summaryrefslogtreecommitdiff
path: root/lib/libpthread/pthread_spin.3
diff options
context:
space:
mode:
authorjruoho <jruoho@NetBSD.org>2010-07-08 21:48:07 +0000
committerjruoho <jruoho@NetBSD.org>2010-07-08 21:48:07 +0000
commit290a8eeeb6e130399ceb97647674e8ddd23fe1e8 (patch)
tree69514abdc6755e7634855ccaabf8ab5c3acf6aa9 /lib/libpthread/pthread_spin.3
parent7714b84ee711553de68e70f3d3300e073f504968 (diff)
Add some remarks and clarifications, simplify RETURN VALUES, grammar, etc.
Diffstat (limited to 'lib/libpthread/pthread_spin.3')
-rw-r--r--lib/libpthread/pthread_spin.360
1 files changed, 21 insertions, 39 deletions
diff --git a/lib/libpthread/pthread_spin.3 b/lib/libpthread/pthread_spin.3
index be2c25f7ae3..ecfe2cf328c 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.