diff options
Diffstat (limited to 'static/netbsd/man3/pthread_spin.3')
| -rw-r--r-- | static/netbsd/man3/pthread_spin.3 | 213 |
1 files changed, 213 insertions, 0 deletions
diff --git a/static/netbsd/man3/pthread_spin.3 b/static/netbsd/man3/pthread_spin.3 new file mode 100644 index 00000000..b5b11bfa --- /dev/null +++ b/static/netbsd/man3/pthread_spin.3 @@ -0,0 +1,213 @@ +.\" $NetBSD: pthread_spin.3,v 1.6 2017/10/22 16:37:24 abhinav Exp $ +.\" +.\" Copyright (c) 2002, 2008, 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" ---------------------------------------------------------------------------- +.Dd July 8, 2010 +.Dt PTHREAD_SPIN 3 +.Os +.Sh NAME +.Nm pthread_spin , +.Nm pthread_spin_init , +.Nm pthread_spin_destroy , +.Nm pthread_spin_lock , +.Nm pthread_spin_trylock , +.Nm pthread_spin_unlock +.Nd spin lock interface +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_spin_init "pthread_spinlock_t *lock" "int pshared" +.Ft int +.Fn pthread_spin_destroy "pthread_spinlock_t *lock" +.Ft int +.Fn pthread_spin_lock "pthread_spinlock_t *lock" +.Ft int +.Fn pthread_spin_trylock "pthread_spinlock_t *lock" +.Ft int +.Fn pthread_spin_unlock "pthread_spinlock_t *lock" +.\" ---------------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn pthread_spin_init +function is used to initialize a spin lock. +In the +.Nx +implementation the +.Fa pshared +parameter is currently unused and all spin locks exhibit the +.Dv PTHREAD_PROCESS_SHARED +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. +.Pp +.\" ----- +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 , +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 locking action, but does not block if the lock +cannot be immediately obtained; if the lock is held, the call fails. +.Pp +.\" ----- +The +.Fn pthread_spin_unlock +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, all described functions return zero. +Otherwise an error number will be returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_spin_init +function shall fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory exists to initialize the lock. +.El +.Pp +The +.Fn pthread_spin_init +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa lock +parameter was +.Dv NULL +or the +.Fa pshared +parameter was neither +.Dv PTHREAD_PROCESS_SHARED +nor +.Dv PTHREAD_PROCESS_PRIVATE . +.El +.Pp +.\" ----- +The +.Fn pthread_spin_destroy +function may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The system has detected an attempt to destroy the object referenced by +.Fa lock +while it is locked. +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.Pp +.\" ----- +The +.Fn pthread_spin_trylock +function shall fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The lock could not be acquired because a writer holds the lock or +was blocked on it. +.El +.Pp +The +.Fn pthread_spin_lock +function may fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +The current thread already owns +.Fa lock +for writing. +.El +.Pp +The +.Fn pthread_spin_lock +and +.Fn pthread_spin_trylock +functions may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.Pp +.\" ----- +The +.Fn pthread_spin_unlock +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.\" ---------------------------------------------------------------------------- +.Sh SEE ALSO +.Xr pthread 3 , +.Xr pthread_barrier 3 , +.Xr pthread_cond 3 , +.Xr pthread_mutex 3 , +.Xr pthread_rwlock 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . +.\" ---------------------------------------------------------------------------- +.Sh CAVEATS +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 spin locks +can lead to system deadlock. +Mutexes are preferable in nearly every possible use case. |