/share/man/man3/pthread_spin_lock.3

  1.\" Copyright (c) 2004 Michael Telahun Makonnen
  2.\" All rights reserved.
  3.\"
  4.\" Redistribution and use in source and binary forms, with or without
  5.\" modification, are permitted provided that the following conditions
  6.\" are met:
  7.\" 1. Redistributions of source code must retain the above copyright
  8.\"    notice, this list of conditions and the following disclaimer.
  9.\" 2. Redistributions in binary form must reproduce the above copyright
 10.\"    notice, this list of conditions and the following disclaimer in the
 11.\"    documentation and/or other materials provided with the distribution.
 12.\"
 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 23.\" SUCH DAMAGE.
 24.\"
 25.\" $FreeBSD$
 26.\"
 27.Dd January 22, 2004
 28.Dt PTHREAD_SPIN_LOCK 3
 29.Os
 30.Sh NAME
 31.Nm pthread_spin_lock , pthread_spin_trylock , pthread_spin_unlock
 32.Nd "lock or unlock a spin lock"
 33.Sh LIBRARY
 34.Lb libpthread
 35.Sh SYNOPSIS
 36.In pthread.h
 37.Ft int
 38.Fn pthread_spin_lock "pthread_spinlock_t *lock"
 39.Ft int
 40.Fn pthread_spin_trylock "pthread_spinlock_t *lock"
 41.Ft int
 42.Fn pthread_spin_unlock "pthread_spinlock_t *lock"
 43.Sh DESCRIPTION
 44The
 45.Fn pthread_spin_lock
 46function will acquire
 47.Fa lock
 48if it is not currently owned by another thread.
 49If the lock cannot be acquired immediately, it will
 50spin attempting to acquire the lock (it will not sleep) until
 51it becomes available.
 52.Pp
 53The
 54.Fn pthread_spin_trylock
 55function is the same as
 56.Fn pthread_spin_lock
 57except that if it cannot acquire
 58.Fa lock
 59immediately it will return with an error.
 60.Pp
 61The
 62.Fn pthread_spin_unlock
 63function will release
 64.Fa lock ,
 65which must have been previously locked by a call to
 66.Fn pthread_spin_lock
 67or
 68.Fn pthread_spin_trylock .
 69.Sh RETURN VALUES
 70If successful, all these functions will return zero.
 71Otherwise, an error number will be returned to indicate the error.
 72.Pp
 73None of these functions will return
 74.Er EINTR .
 75.Sh ERRORS
 76The
 77.Fn pthread_spin_lock ,
 78.Fn pthread_spin_trylock
 79and
 80.Fn pthread_spin_unlock
 81functions will fail if:
 82.Bl -tag -width Er
 83.It Bq Er EINVAL
 84The value specified by
 85.Fa lock
 86is invalid or is not initialized.
 87.El
 88.Pp
 89The
 90.Fn pthread_spin_lock
 91function may fail if:
 92.Bl -tag -width Er
 93.It Bq Er EDEADLK
 94The calling thread already owns the lock.
 95.El
 96.Pp
 97The
 98.Fn pthread_spin_trylock
 99function will fail if:
100.Bl -tag -width Er
101.It Bq Er EBUSY
102Another thread currently holds
103.Fa lock .
104.El
105.Pp
106The
107.Fn pthread_spin_unlock
108function may fail if:
109.Bl -tag -width Er
110.It Bq Er EPERM
111The calling thread does not own
112.Fa lock .
113.El
114.Sh SEE ALSO
115.Xr pthread_spin_destroy 3 ,
116.Xr pthread_spin_init 3
117.Sh HISTORY
118The
119.Fn pthread_spin_lock ,
120.Fn pthread_spin_trylock
121and
122.Fn pthread_spin_unlock
123functions first appeared in
124.Lb libkse
125in
126.Fx 5.2 ,
127and in
128.Lb libthr
129in
130.Fx 5.3 .
131.Sh BUGS
132The implementation of
133.Fn pthread_spin_lock ,
134.Fn pthread_spin_trylock
135and
136.Fn pthread_spin_unlock
137is expected to conform to
138.St -p1003.2 .