Aren
/
NetBSD
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

This commit is contained in:
jruoho 2010-07-08 21:48:07 +00:00
parent 7714b84ee7
commit 290a8eeeb6
1 changed files with 21 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
lib/libpthread/pthread_spin.3
View File

@ -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.