1.\" $NetBSD: pthread_spin.3,v 1.5 2010/07/09 10:55:11 wiz Exp $ 2.\" 3.\" Copyright (c) 2002, 2008, 2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.\" ---------------------------------------------------------------------------- 28.Dd July 8, 2010 29.Dt PTHREAD_SPIN 3 30.Os 31.Sh NAME 32.Nm pthread_spin 33.Nd spin lock interface 34.Sh LIBRARY 35.Lb libpthread 36.Sh SYNOPSIS 37.In pthread.h 38.Ft int 39.Fn pthread_spin_init "pthread_spinlock_t *lock" "int pshared" 40.Ft int 41.Fn pthread_spin_destroy "pthread_spinlock_t *lock" 42.Ft int 43.Fn pthread_spin_lock "pthread_spinlock_t *lock" 44.Ft int 45.Fn pthread_spin_trylock "pthread_spinlock_t *lock" 46.Ft int 47.Fn pthread_spin_unlock "pthread_spinlock_t *lock" 48.\" ---------------------------------------------------------------------------- 49.Sh DESCRIPTION 50The 51.Fn pthread_spin_init 52function is used to initialize a spin lock. 53In the 54.Nx 55implementation the 56.Fa pshared 57parameter is currently unused and all spin locks exhibit the 58.Dv PTHREAD_PROCESS_SHARED 59property, implying that all spin locks may be 60accessed by threads of multiple processes. 61The results of calling 62.Fn pthread_spin_init 63with an already initialized lock are undefined. 64.Pp 65.\" ----- 66The 67.Fn pthread_spin_destroy 68function is used to destroy a spin lock previously created with 69.Fn pthread_spin_init . 70It is undefined what happens if the function is called 71when a thread holds the lock, or if the function is called 72with an uninitialized spin lock. 73.Pp 74.\" ----- 75The 76.Fn pthread_spin_lock 77function acquires a spin lock on 78.Fa lock , 79provided that 80.Fa lock 81is not presently held. 82If the lock cannot be 83immediately acquired, the calling thread repeatedly retries until it can 84acquire the lock. 85Undefined behavior may follow if the calling thread holds 86the lock at the time the call is made. 87.Pp 88The 89.Fn pthread_spin_trylock 90function performs the same locking action, but does not block if the lock 91cannot be immediately obtained; if the lock is held, the call fails. 92.Pp 93.\" ----- 94The 95.Fn pthread_spin_unlock 96function is used to release the read/write lock previously obtained by 97.Fn pthread_spin_lock 98or 99.Fn pthread_spin_trylock . 100The results are undefined if the lock is not held by the calling thread. 101.\" ---------------------------------------------------------------------------- 102.Sh RETURN VALUES 103If successful, all described functions return zero. 104Otherwise an error number will be returned to indicate the error. 105.Sh ERRORS 106The 107.Fn pthread_spin_init 108function shall fail if: 109.Bl -tag -width Er 110.It Bq Er ENOMEM 111Insufficient memory exists to initialize the lock. 112.El 113.Pp 114The 115.Fn pthread_spin_init 116function may fail if: 117.Bl -tag -width Er 118.It Bq Er EINVAL 119The 120.Fa lock 121parameter was 122.Dv NULL 123or the 124.Fa pshared 125parameter was neither 126.Dv PTHREAD_PROCESS_SHARED 127nor 128.Dv PTHREAD_PROCESS_PRIVATE . 129.El 130.Pp 131.\" ----- 132The 133.Fn pthread_spin_destroy 134function may fail if: 135.Bl -tag -width Er 136.It Bq Er EBUSY 137The system has detected an attempt to destroy the object referenced by 138.Fa lock 139while it is locked. 140.It Bq Er EINVAL 141The value specified by 142.Fa lock 143is invalid. 144.El 145.Pp 146.\" ----- 147The 148.Fn pthread_spin_trylock 149function shall fail if: 150.Bl -tag -width Er 151.It Bq Er EBUSY 152The lock could not be acquired because a writer holds the lock or 153was blocked on it. 154.El 155.Pp 156The 157.Fn pthread_spin_lock 158function may fail if: 159.Bl -tag -width Er 160.It Bq Er EDEADLK 161The current thread already owns 162.Fa lock 163for writing. 164.El 165.Pp 166The 167.Fn pthread_spin_lock 168and 169.Fn pthread_spin_trylock 170functions may fail if: 171.Bl -tag -width Er 172.It Bq Er EINVAL 173The value specified by 174.Fa lock 175is invalid. 176.El 177.Pp 178.\" ----- 179The 180.Fn pthread_spin_unlock 181function may fail if: 182.Bl -tag -width Er 183.It Bq Er EINVAL 184The value specified by 185.Fa lock 186is invalid. 187.El 188.\" ---------------------------------------------------------------------------- 189.Sh SEE ALSO 190.Xr pthread 3 , 191.Xr pthread_barrier 3 , 192.Xr pthread_cond 3 , 193.Xr pthread_mutex 3 , 194.Xr pthread_rwlock 3 195.Sh STANDARDS 196These functions conform to 197.St -p1003.1-2001 . 198.\" ---------------------------------------------------------------------------- 199.Sh CAVEATS 200Applications using spin locks are vulnerable to the effects of priority 201inversion. 202Applications using real-time threads 203.Pq Dv SCHED_FIFO , 204.Pq Dv SCHED_RR 205should not use these interfaces. 206Outside carefully controlled environments, priority inversion with spin locks 207can lead to system deadlock. 208Mutexes are preferable in nearly every possible use case. 209