Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src/lib/libpthread Add some remarks and clarifications, simplify...
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.
Home |
Main Index |
Thread Index |
Old Index