| 1 |
.\" Copyright 2017, Michael Kerrisk <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH pthread_spin_init 3 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
pthread_spin_init, pthread_spin_destroy \- initialize or destroy a spin lock |
| 9 |
.SH LIBRARY |
| 10 |
POSIX threads library |
| 11 |
.RI ( libpthread ,\~ \-lpthread ) |
| 12 |
.SH SYNOPSIS |
| 13 |
.nf |
| 14 |
.B #include <pthread.h> |
| 15 |
.P |
| 16 |
.BI "int pthread_spin_init(pthread_spinlock_t *" lock ", int " pshared ");" |
| 17 |
.BI "int pthread_spin_destroy(pthread_spinlock_t *" lock ");" |
| 18 |
.fi |
| 19 |
.P |
| 20 |
.RS -4 |
| 21 |
Feature Test Macro Requirements for glibc (see |
| 22 |
.BR feature_test_macros (7)): |
| 23 |
.RE |
| 24 |
.P |
| 25 |
.BR pthread_spin_init (), |
| 26 |
.BR pthread_spin_destroy (): |
| 27 |
.nf |
| 28 |
_POSIX_C_SOURCE >= 200112L |
| 29 |
.fi |
| 30 |
.SH DESCRIPTION |
| 31 |
.IR "General note" : |
| 32 |
Most programs should use mutexes |
| 33 |
instead of spin locks. |
| 34 |
Spin locks are primarily useful in conjunction with real-time |
| 35 |
scheduling policies. |
| 36 |
See NOTES. |
| 37 |
.P |
| 38 |
The |
| 39 |
.BR pthread_spin_init () |
| 40 |
function allocates any resources required for the use of |
| 41 |
the spin lock referred to by |
| 42 |
.I lock |
| 43 |
and initializes the lock to be in the unlocked state. |
| 44 |
The |
| 45 |
.I pshared |
| 46 |
argument must have one of the following values: |
| 47 |
.TP |
| 48 |
.B PTHREAD_PROCESS_PRIVATE |
| 49 |
The spin lock is to be operated on only by threads in the same process |
| 50 |
as the thread that calls |
| 51 |
.BR pthread_spin_init (). |
| 52 |
(Attempting to share the spin lock between processes |
| 53 |
results in undefined behavior.) |
| 54 |
.TP |
| 55 |
.B PTHREAD_PROCESS_SHARED |
| 56 |
The spin lock may be operated on by any thread in any process that |
| 57 |
has access to the memory containing the lock |
| 58 |
(i.e., the lock may be in a shared memory object that is |
| 59 |
shared among multiple processes). |
| 60 |
.P |
| 61 |
Calling |
| 62 |
.BR pthread_spin_init () |
| 63 |
on a spin lock that has already been initialized results |
| 64 |
in undefined behavior. |
| 65 |
.P |
| 66 |
The |
| 67 |
.BR pthread_spin_destroy () |
| 68 |
function destroys a previously initialized spin lock, |
| 69 |
freeing any resources that were allocated for that lock. |
| 70 |
Destroying a spin lock that has not been previously been initialized |
| 71 |
or destroying a spin lock while another thread holds the lock |
| 72 |
results in undefined behavior. |
| 73 |
.P |
| 74 |
Once a spin lock has been destroyed, |
| 75 |
performing any operation on the lock other than |
| 76 |
once more initializing it with |
| 77 |
.BR pthread_spin_init () |
| 78 |
results in undefined behavior. |
| 79 |
.P |
| 80 |
The result of performing operations such as |
| 81 |
.BR pthread_spin_lock (3), |
| 82 |
.BR pthread_spin_unlock (3), |
| 83 |
and |
| 84 |
.BR pthread_spin_destroy () |
| 85 |
on |
| 86 |
.I copies |
| 87 |
of the object referred to by |
| 88 |
.I lock |
| 89 |
is undefined. |
| 90 |
.SH RETURN VALUE |
| 91 |
On success, there functions return zero. |
| 92 |
On failure, they return an error number. |
| 93 |
In the event that |
| 94 |
.BR pthread_spin_init () |
| 95 |
fails, the lock is not initialized. |
| 96 |
.SH ERRORS |
| 97 |
.BR pthread_spin_init () |
| 98 |
may fail with the following errors: |
| 99 |
.\" These errors don't occur on the glibc implementation |
| 100 |
.TP |
| 101 |
.B EAGAIN |
| 102 |
The system has insufficient resources to initialize |
| 103 |
a new spin lock. |
| 104 |
.TP |
| 105 |
.B ENOMEM |
| 106 |
Insufficient memory to initialize the spin lock. |
| 107 |
.SH STANDARDS |
| 108 |
POSIX.1-2008. |
| 109 |
.SH HISTORY |
| 110 |
glibc 2.2. |
| 111 |
POSIX.1-2001. |
| 112 |
.P |
| 113 |
Support for process-shared spin locks is a POSIX option. |
| 114 |
The option is supported in the glibc implementation. |
| 115 |
.SH NOTES |
| 116 |
Spin locks should be employed in conjunction with |
| 117 |
real-time scheduling policies |
| 118 |
.RB ( SCHED_FIFO , |
| 119 |
or possibly |
| 120 |
.BR SCHED_RR ). |
| 121 |
Use of spin locks with nondeterministic scheduling policies such as |
| 122 |
.B SCHED_OTHER |
| 123 |
probably indicates a design mistake. |
| 124 |
The problem is that if a thread operating under such a policy |
| 125 |
is scheduled off the CPU while it holds a spin lock, |
| 126 |
then other threads will waste time spinning on the lock |
| 127 |
until the lock holder is once more rescheduled and releases the lock. |
| 128 |
.P |
| 129 |
If threads create a deadlock situation while employing spin locks, |
| 130 |
those threads will spin forever consuming CPU time. |
| 131 |
.P |
| 132 |
User-space spin locks are |
| 133 |
.I not |
| 134 |
applicable as a general locking solution. |
| 135 |
They are, by definition, |
| 136 |
prone to priority inversion and unbounded spin times. |
| 137 |
A programmer using spin locks must be exceptionally careful not |
| 138 |
only in the code, but also in terms of system configuration, |
| 139 |
thread placement, and priority assignment. |
| 140 |
.\" FIXME . When PTHREAD_MUTEX_ADAPTIVE_NP is one day document |
| 141 |
.\" make reference to it here |
| 142 |
.SH SEE ALSO |
| 143 |
.ad l |
| 144 |
.nh |
| 145 |
.BR pthread_mutex_init (3), |
| 146 |
.BR pthread_mutex_lock (3), |
| 147 |
.BR pthread_spin_lock (3), |
| 148 |
.BR pthread_spin_unlock (3), |
| 149 |
.BR pthreads (7) |