]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - share/man/man9/sx.9
Import libxo-1.3.0:
[FreeBSD/FreeBSD.git] / share / man / man9 / sx.9
1 .\"
2 .\" Copyright (C) 2001 Jason Evans <jasone@FreeBSD.org>.  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(s), this list of conditions and the following disclaimer as
9 .\"    the first lines of this file unmodified other than the possible
10 .\"    addition of one or more copyright notices.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\"    notice(s), this list of conditions and the following disclaimer in the
13 .\"    documentation and/or other materials provided with the distribution.
14 .\"
15 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
16 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
17 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
18 .\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
19 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
20 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
21 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
25 .\" DAMAGE.
26 .\"
27 .\" $FreeBSD$
28 .\"
29 .Dd November 11, 2017
30 .Dt SX 9
31 .Os
32 .Sh NAME
33 .Nm sx ,
34 .Nm sx_init ,
35 .Nm sx_init_flags ,
36 .Nm sx_destroy ,
37 .Nm sx_slock ,
38 .Nm sx_xlock ,
39 .Nm sx_slock_sig ,
40 .Nm sx_xlock_sig ,
41 .Nm sx_try_slock ,
42 .Nm sx_try_xlock ,
43 .Nm sx_sunlock ,
44 .Nm sx_xunlock ,
45 .Nm sx_unlock ,
46 .Nm sx_try_upgrade ,
47 .Nm sx_downgrade ,
48 .Nm sx_sleep ,
49 .Nm sx_xholder ,
50 .Nm sx_xlocked ,
51 .Nm sx_assert ,
52 .Nm SX_SYSINIT ,
53 .Nm SX_SYSINIT_FLAGS
54 .Nd kernel shared/exclusive lock
55 .Sh SYNOPSIS
56 .In sys/param.h
57 .In sys/lock.h
58 .In sys/sx.h
59 .Ft void
60 .Fn sx_init "struct sx *sx" "const char *description"
61 .Ft void
62 .Fn sx_init_flags "struct sx *sx" "const char *description" "int opts"
63 .Ft void
64 .Fn sx_destroy "struct sx *sx"
65 .Ft void
66 .Fn sx_slock "struct sx *sx"
67 .Ft void
68 .Fn sx_xlock "struct sx *sx"
69 .Ft int
70 .Fn sx_slock_sig "struct sx *sx"
71 .Ft int
72 .Fn sx_xlock_sig "struct sx *sx"
73 .Ft int
74 .Fn sx_try_slock "struct sx *sx"
75 .Ft int
76 .Fn sx_try_xlock "struct sx *sx"
77 .Ft void
78 .Fn sx_sunlock "struct sx *sx"
79 .Ft void
80 .Fn sx_xunlock "struct sx *sx"
81 .Ft void
82 .Fn sx_unlock "struct sx *sx"
83 .Ft int
84 .Fn sx_try_upgrade "struct sx *sx"
85 .Ft void
86 .Fn sx_downgrade "struct sx *sx"
87 .Ft int
88 .Fn sx_sleep "void *chan" "struct sx *sx" "int priority" "const char *wmesg" "int timo"
89 .Ft "struct thread *"
90 .Fn sx_xholder "struct sx *sx"
91 .Ft int
92 .Fn sx_xlocked "const struct sx *sx"
93 .Pp
94 .Cd "options INVARIANTS"
95 .Cd "options INVARIANT_SUPPORT"
96 .Ft void
97 .Fn sx_assert "const struct sx *sx" "int what"
98 .In sys/kernel.h
99 .Fn SX_SYSINIT "name" "struct sx *sx" "const char *desc"
100 .Fn SX_SYSINIT_FLAGS "name" "struct sx *sx" "const char *desc" "int flags"
101 .Sh DESCRIPTION
102 Shared/exclusive locks are used to protect data that are read far more often
103 than they are written.
104 Shared/exclusive locks do not implement priority propagation like mutexes and
105 reader/writer locks to prevent priority inversions, so
106 shared/exclusive locks should be used prudently.
107 .Pp
108 Shared/exclusive locks are created with either
109 .Fn sx_init
110 or
111 .Fn sx_init_flags
112 where
113 .Fa sx
114 is a pointer to space for a
115 .Vt struct sx ,
116 and
117 .Fa description
118 is a pointer to a null-terminated character string that describes the
119 shared/exclusive lock.
120 The
121 .Fa opts
122 argument to
123 .Fn sx_init_flags
124 specifies a set of optional flags to alter the behavior of
125 .Fa sx .
126 It contains one or more of the following flags:
127 .Bl -tag -width SX_NOADAPTIVE
128 .It Dv SX_NOADAPTIVE
129 Disable adaptive spinning, rather than sleeping, for lock operations
130 while an exclusive lock holder is executing on another CPU.
131 Adaptive spinning is the default unless the kernel is compiled with
132 .Cd "options NO_ADAPTIVE_SX" .
133 .It Dv SX_DUPOK
134 Witness should not log messages about duplicate locks being acquired.
135 .It Dv SX_NOWITNESS
136 Instruct
137 .Xr witness 4
138 to ignore this lock.
139 .It Dv SX_NOPROFILE
140 Do not profile this lock.
141 .It Dv SX_RECURSE
142 Allow threads to recursively acquire exclusive locks for
143 .Fa sx .
144 .It Dv SX_QUIET
145 Do not log any operations for this lock via
146 .Xr ktr 4 .
147 .It Dv SX_NEW
148 If the kernel has been compiled with
149 .Cd "options INVARIANTS" ,
150 .Fn sx_init
151 will assert that the
152 .Fa sx
153 has not been initialized multiple times without intervening calls to
154 .Fn sx_destroy
155 unless this option is specified.
156 .El
157 .Pp
158 Shared/exclusive locks are destroyed with
159 .Fn sx_destroy .
160 The lock
161 .Fa sx
162 must not be locked by any thread when it is destroyed.
163 .Pp
164 Threads acquire and release a shared lock by calling
165 .Fn sx_slock ,
166 .Fn sx_slock_sig
167 or
168 .Fn sx_try_slock
169 and
170 .Fn sx_sunlock
171 or
172 .Fn sx_unlock .
173 Threads acquire and release an exclusive lock by calling
174 .Fn sx_xlock ,
175 .Fn sx_xlock_sig
176 or
177 .Fn sx_try_xlock
178 and
179 .Fn sx_xunlock
180 or
181 .Fn sx_unlock .
182 A thread can attempt to upgrade a currently held shared lock to an exclusive
183 lock by calling
184 .Fn sx_try_upgrade .
185 A thread that has an exclusive lock can downgrade it to a shared lock by
186 calling
187 .Fn sx_downgrade .
188 .Pp
189 .Fn sx_try_slock
190 and
191 .Fn sx_try_xlock
192 will return 0 if the shared/exclusive lock cannot be acquired immediately;
193 otherwise the shared/exclusive lock will be acquired and a non-zero value will
194 be returned.
195 .Pp
196 .Fn sx_try_upgrade
197 will return 0 if the shared lock cannot be upgraded to an exclusive lock
198 immediately; otherwise the exclusive lock will be acquired and a non-zero value
199 will be returned.
200 .Pp
201 .Fn sx_slock_sig
202 and
203 .Fn sx_xlock_sig
204 do the same as their normal versions but performing an interruptible sleep.
205 They return a non-zero value if the sleep has been interrupted by a signal
206 or an interrupt, otherwise 0.
207 .Pp
208 A thread can atomically release a shared/exclusive lock while waiting for an
209 event by calling
210 .Fn sx_sleep .
211 For more details on the parameters to this function,
212 see
213 .Xr sleep 9 .
214 .Pp
215 When compiled with
216 .Cd "options INVARIANTS"
217 and
218 .Cd "options INVARIANT_SUPPORT" ,
219 the
220 .Fn sx_assert
221 function tests
222 .Fa sx
223 for the assertions specified in
224 .Fa what ,
225 and panics if they are not met.
226 One of the following assertions must be specified:
227 .Bl -tag -width ".Dv SA_UNLOCKED"
228 .It Dv SA_LOCKED
229 Assert that the current thread has either a shared or an exclusive lock on the
230 .Vt sx
231 lock pointed to by the first argument.
232 .It Dv SA_SLOCKED
233 Assert that the current thread has a shared lock on the
234 .Vt sx
235 lock pointed to by
236 the first argument.
237 .It Dv SA_XLOCKED
238 Assert that the current thread has an exclusive lock on the
239 .Vt sx
240 lock pointed to
241 by the first argument.
242 .It Dv SA_UNLOCKED
243 Assert that the current thread has no lock on the
244 .Vt sx
245 lock pointed to
246 by the first argument.
247 .El
248 .Pp
249 In addition, one of the following optional assertions may be included with
250 either an
251 .Dv SA_LOCKED ,
252 .Dv SA_SLOCKED ,
253 or
254 .Dv SA_XLOCKED
255 assertion:
256 .Bl -tag -width ".Dv SA_NOTRECURSED"
257 .It Dv SA_RECURSED
258 Assert that the current thread has a recursed lock on
259 .Fa sx .
260 .It Dv SA_NOTRECURSED
261 Assert that the current thread does not have a recursed lock on
262 .Fa sx .
263 .El
264 .Pp
265 .Fn sx_xholder
266 will return a pointer to the thread which currently holds an exclusive lock on
267 .Fa sx .
268 If no thread holds an exclusive lock on
269 .Fa sx ,
270 then
271 .Dv NULL
272 is returned instead.
273 .Pp
274 .Fn sx_xlocked
275 will return non-zero if the current thread holds the exclusive lock;
276 otherwise, it will return zero.
277 .Pp
278 For ease of programming,
279 .Fn sx_unlock
280 is provided as a macro frontend to the respective functions,
281 .Fn sx_sunlock
282 and
283 .Fn sx_xunlock .
284 Algorithms that are aware of what state the lock is in should use either
285 of the two specific functions for a minor performance benefit.
286 .Pp
287 The
288 .Fn SX_SYSINIT
289 macro is used to generate a call to the
290 .Fn sx_sysinit
291 routine at system startup in order to initialize a given
292 .Fa sx
293 lock.
294 The parameters are the same as
295 .Fn sx_init
296 but with an additional argument,
297 .Fa name ,
298 that is used in generating unique variable names for the related
299 structures associated with the lock and the sysinit routine.
300 The
301 .Fn SX_SYSINIT_FLAGS
302 macro can similarly be used to initialize a given
303 .Fa sx
304 lock using
305 .Fn sx_init_flags .
306 .Pp
307 A thread may not hold both a shared lock and an exclusive lock on the same
308 lock simultaneously;
309 attempting to do so will result in deadlock.
310 .Sh CONTEXT
311 A thread may hold a shared or exclusive lock on an
312 .Nm
313 lock while sleeping.
314 As a result, an
315 .Nm
316 lock may not be acquired while holding a mutex.
317 Otherwise, if one thread slept while holding an
318 .Nm
319 lock while another thread blocked on the same
320 .Nm
321 lock after acquiring a mutex, then the second thread would effectively
322 end up sleeping while holding a mutex, which is not allowed.
323 .Sh SEE ALSO
324 .Xr lock 9 ,
325 .Xr locking 9 ,
326 .Xr mutex 9 ,
327 .Xr panic 9 ,
328 .Xr rwlock 9 ,
329 .Xr sema 9
330 .Sh BUGS
331 A kernel without
332 .Dv WITNESS
333 cannot assert whether the current thread does or does not hold a shared lock.
334 .Dv SA_LOCKED
335 and
336 .Dv SA_SLOCKED
337 can only assert that
338 .Em any
339 thread holds a shared lock.
340 They cannot ensure that the current thread holds a shared lock.
341 Further,
342 .Dv SA_UNLOCKED
343 can only assert that the current thread does not hold an exclusive lock.