]>
Commit | Line | Data |
---|---|---|
7f5f8925 MK |
1 | .\" Copyright (c) 2017, Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" | |
3 | .\" %%%LICENSE_START(VERBATIM) | |
4 | .\" Permission is granted to make and distribute verbatim copies of this | |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
12 | .\" | |
13 | .\" Since the Linux kernel and libraries are constantly changing, this | |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
20 | .\" | |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
23 | .\" %%%LICENSE_END | |
24 | .\" | |
25 | .TH PTHREAD_SPIN_INIT 3 2017-09-30 "Linux" "Linux Programmer's Manual" | |
26 | .SH NAME | |
27 | pthread_spin_init, pthread_spin_destroy \- initialize or destroy a spin lock | |
28 | .SH SYNOPSIS | |
29 | .nf | |
30 | .B #include <pthread.h> | |
31 | .PP | |
eb93621d | 32 | .BI "int pthread_spin_init(pthread_spinlock_t *" lock " int " pshared ");" |
59524c5e | 33 | .BI "int pthread_spin_destroy(pthread_spinlock_t *" lock ");" |
7f5f8925 MK |
34 | .fi |
35 | .PP | |
36 | Compile and link with \fI\-pthread\fP. | |
37 | .PP | |
38 | .in -4n | |
39 | Feature Test Macro Requirements for glibc (see | |
40 | .BR feature_test_macros (7)): | |
41 | .in | |
42 | .PP | |
43 | .BR pthread_spin_init (), | |
44 | .BR pthread_spin_destroy (): | |
45 | .br | |
46 | .RS 4 | |
47 | .ad l | |
48 | _POSIX_C_SOURCE >= 200112L | |
49 | .RE | |
50 | .ad | |
51 | .SH DESCRIPTION | |
34d46b81 MK |
52 | .IR "General note" : |
53 | Most programs should use mutexes | |
54 | instead of spin locks. | |
55 | Spin locks are primarily useful in conjunction with real-time | |
56 | scheduling policies. | |
57 | See NOTES. | |
58 | .PP | |
7f5f8925 MK |
59 | The |
60 | .BR pthread_spin_init () | |
61 | function allocates any resources required for the use of | |
62 | the spin lock referred to by | |
63 | .I lock | |
64 | and initializes the lock to be in the unlocked state. | |
65 | The | |
66 | .I pshared | |
67 | argument must have one of the following values: | |
68 | .TP | |
69 | .B PTHREAD_PROCESS_PRIVATE | |
70 | The spin lock is to be operated on only by threads in the same process | |
71 | as the thread that calls | |
72 | .BR pthread_spin_init (). | |
73 | (Attempting to share the spin lock between processes | |
74 | results in undefined behavior.) | |
75 | .TP | |
76 | .B PTHREAD_PROCESS_SHARED | |
77 | The spin lock may be operated on by any thread in any process that | |
78 | has access to the memory containing the lock | |
eb93621d | 79 | (i.e., the lock may be in a shared memory object that is |
7f5f8925 MK |
80 | shared among multiple processes). |
81 | .PP | |
82 | Calling | |
83 | .BR pthread_spin_init () | |
84 | on a spin lock that has already been initialized results | |
85 | in undefined behavior. | |
86 | .PP | |
87 | The | |
88 | .BR pthread_spin_destroy () | |
89 | function destroys a previously initialized spin lock, | |
90 | freeing any resources that were allocated for that lock. | |
91 | Destroying a spin lock that has not been previously been initialized | |
92 | or destroying a spin lock while another thread holds the lock | |
93 | results in undefined behavior. | |
94 | .PP | |
95 | Once a spin lock has been destroyed, | |
96 | performing any operation on the lock other than | |
97 | once more initializing it with | |
98 | .BR pthread_spin_init () | |
99 | results in undefined behavior. | |
0e905edc MK |
100 | .PP |
101 | The result of performing operations such as | |
102 | .BR pthread_spin_lock (3), | |
103 | .BR pthread_spin_unlock (3), | |
104 | and | |
105 | .BR pthread_spin_destroy (3) | |
106 | on | |
107 | .I copies | |
108 | of the object referred to by | |
109 | .I lock | |
110 | is undefined. | |
7f5f8925 MK |
111 | .SH RETURN VALUE |
112 | On success, there functions return zero. | |
113 | On failure, they return an error number. | |
114 | In the event that | |
115 | .BR pthread_spin_init () | |
116 | fails, the lock is not initialized. | |
117 | .SH ERRORS | |
118 | .BR pthread_spin_init () | |
119 | may fail with the following errors: | |
120 | .\" These errors don't occur on the glibc implementation | |
121 | .TP | |
122 | .B EAGAIN | |
123 | The system has insufficient resources to initialize | |
124 | a new spin lock. | |
125 | .TP | |
126 | .B ENOMEM | |
127 | Insufficient memory to initialize the spin lock. | |
128 | .SH VERSIONS | |
129 | These functions first appeared in glibc in version 2.2. | |
130 | .SH CONFORMING TO | |
131 | POSIX.1-2001. | |
132 | .PP | |
133 | Support for process-shared spin locks is a POSIX option. | |
134 | The option is supported in the glibc implementation. | |
2dea7241 MK |
135 | .SH NOTES |
136 | Spin locks should be employed in conjunction with | |
137 | real-time scheduling policies | |
138 | .RB ( SCHED_FIFO , | |
139 | or possibly | |
140 | .BR SCHED_RR ). | |
141 | Use of spin locks with nondeterministic scheduling policies such as | |
142 | .BR SCHED_OTHER | |
143 | probably indicates a design mistake. | |
144 | The problem is that if a thread operating under such a policy | |
145 | is scheduled off the CPU while it holds a spin lock, | |
146 | then other threads will waste time spinning on the lock | |
147 | until the lock holder is once more rescheduled and releases the lock. | |
8cbd1d9e | 148 | .PP |
28c15b63 | 149 | If threads create a deadlock situation while employing spin locks, |
8cbd1d9e | 150 | those threads will spin forever consuming CPU time. |
28c15b63 | 151 | .PP |
5017fc28 MK |
152 | User-space spin locks are |
153 | .I not | |
154 | applicable as a general locking solution. | |
155 | They are, by definition, | |
156 | prone to priority inversion and unbounded spin times. | |
28c15b63 MK |
157 | A programmer using spin locks must be exceptionally careful not |
158 | only in the code, but also in terms of system configuration, | |
159 | thread placement, and priority assignment. | |
b8584951 MK |
160 | .\" FIXME . When PTHREAD_MUTEX_ADAPTIVE_NP is one day document |
161 | .\" make reference to it here | |
7f5f8925 MK |
162 | .SH SEE ALSO |
163 | .ad l | |
164 | .nh | |
34d46b81 MK |
165 | .BR pthread_mutex_init (3), |
166 | .BR pthread_mutex_lock (3), | |
7f5f8925 MK |
167 | .BR pthread_spin_lock (3), |
168 | .BR pthread_spin_unlock (3), | |
169 | .BR pthreads (7) |