Debian Codegraph @

upstream/debian-unstable/man3/pthread_spin_init.3

raw
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)