1.\" $NetBSD: pthread_spin.3,v 1.6 2017/10/22 16:37:24 abhinav 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.Nm pthread_spin_init , 34.Nm pthread_spin_destroy , 35.Nm pthread_spin_lock , 36.Nm pthread_spin_trylock , 37.Nm pthread_spin_unlock 38.Nd spin lock interface 39.Sh LIBRARY 40.Lb libpthread 41.Sh SYNOPSIS 42.In pthread.h 43.Ft int 44.Fn pthread_spin_init "pthread_spinlock_t *lock" "int pshared" 45.Ft int 46.Fn pthread_spin_destroy "pthread_spinlock_t *lock" 47.Ft int 48.Fn pthread_spin_lock "pthread_spinlock_t *lock" 49.Ft int 50.Fn pthread_spin_trylock "pthread_spinlock_t *lock" 51.Ft int 52.Fn pthread_spin_unlock "pthread_spinlock_t *lock" 53.\" ---------------------------------------------------------------------------- 54.Sh DESCRIPTION 55The 56.Fn pthread_spin_init 57function is used to initialize a spin lock. 58In the 59.Nx 60implementation the 61.Fa pshared 62parameter is currently unused and all spin locks exhibit the 63.Dv PTHREAD_PROCESS_SHARED 64property, implying that all spin locks may be 65accessed by threads of multiple processes. 66The results of calling 67.Fn pthread_spin_init 68with an already initialized lock are undefined. 69.Pp 70.\" ----- 71The 72.Fn pthread_spin_destroy 73function is used to destroy a spin lock previously created with 74.Fn pthread_spin_init . 75It is undefined what happens if the function is called 76when a thread holds the lock, or if the function is called 77with an uninitialized spin lock. 78.Pp 79.\" ----- 80The 81.Fn pthread_spin_lock 82function acquires a spin lock on 83.Fa lock , 84provided that 85.Fa lock 86is not presently held. 87If the lock cannot be 88immediately acquired, the calling thread repeatedly retries until it can 89acquire the lock. 90Undefined behavior may follow if the calling thread holds 91the lock at the time the call is made. 92.Pp 93The 94.Fn pthread_spin_trylock 95function performs the same locking action, but does not block if the lock 96cannot be immediately obtained; if the lock is held, the call fails. 97.Pp 98.\" ----- 99The 100.Fn pthread_spin_unlock 101function is used to release the read/write lock previously obtained by 102.Fn pthread_spin_lock 103or 104.Fn pthread_spin_trylock . 105The results are undefined if the lock is not held by the calling thread. 106.\" ---------------------------------------------------------------------------- 107.Sh RETURN VALUES 108If successful, all described functions return zero. 109Otherwise an error number will be returned to indicate the error. 110.Sh ERRORS 111The 112.Fn pthread_spin_init 113function shall fail if: 114.Bl -tag -width Er 115.It Bq Er ENOMEM 116Insufficient memory exists to initialize the lock. 117.El 118.Pp 119The 120.Fn pthread_spin_init 121function may fail if: 122.Bl -tag -width Er 123.It Bq Er EINVAL 124The 125.Fa lock 126parameter was 127.Dv NULL 128or the 129.Fa pshared 130parameter was neither 131.Dv PTHREAD_PROCESS_SHARED 132nor 133.Dv PTHREAD_PROCESS_PRIVATE . 134.El 135.Pp 136.\" ----- 137The 138.Fn pthread_spin_destroy 139function may fail if: 140.Bl -tag -width Er 141.It Bq Er EBUSY 142The system has detected an attempt to destroy the object referenced by 143.Fa lock 144while it is locked. 145.It Bq Er EINVAL 146The value specified by 147.Fa lock 148is invalid. 149.El 150.Pp 151.\" ----- 152The 153.Fn pthread_spin_trylock 154function shall fail if: 155.Bl -tag -width Er 156.It Bq Er EBUSY 157The lock could not be acquired because a writer holds the lock or 158was blocked on it. 159.El 160.Pp 161The 162.Fn pthread_spin_lock 163function may fail if: 164.Bl -tag -width Er 165.It Bq Er EDEADLK 166The current thread already owns 167.Fa lock 168for writing. 169.El 170.Pp 171The 172.Fn pthread_spin_lock 173and 174.Fn pthread_spin_trylock 175functions may fail if: 176.Bl -tag -width Er 177.It Bq Er EINVAL 178The value specified by 179.Fa lock 180is invalid. 181.El 182.Pp 183.\" ----- 184The 185.Fn pthread_spin_unlock 186function may fail if: 187.Bl -tag -width Er 188.It Bq Er EINVAL 189The value specified by 190.Fa lock 191is invalid. 192.El 193.\" ---------------------------------------------------------------------------- 194.Sh SEE ALSO 195.Xr pthread 3 , 196.Xr pthread_barrier 3 , 197.Xr pthread_cond 3 , 198.Xr pthread_mutex 3 , 199.Xr pthread_rwlock 3 200.Sh STANDARDS 201These functions conform to 202.St -p1003.1-2001 . 203.\" ---------------------------------------------------------------------------- 204.Sh CAVEATS 205Applications using spin locks are vulnerable to the effects of priority 206inversion. 207Applications using real-time threads 208.Pq Dv SCHED_FIFO , 209.Pq Dv SCHED_RR 210should not use these interfaces. 211Outside carefully controlled environments, priority inversion with spin locks 212can lead to system deadlock. 213Mutexes are preferable in nearly every possible use case. 214