2 .\" Copyright (C) 2001 Jason Evans <jasone@FreeBSD.org>. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
53 .Nd kernel shared/exclusive lock
59 .Fn sx_init "struct sx *sx" "const char *description"
61 .Fn sx_init_flags "struct sx *sx" "const char *description" "int opts"
63 .Fn sx_destroy "struct sx *sx"
65 .Fn sx_slock "struct sx *sx"
67 .Fn sx_xlock "struct sx *sx"
69 .Fn sx_slock_sig "struct sx *sx"
71 .Fn sx_xlock_sig "struct sx *sx"
73 .Fn sx_try_slock "struct sx *sx"
75 .Fn sx_try_xlock "struct sx *sx"
77 .Fn sx_sunlock "struct sx *sx"
79 .Fn sx_xunlock "struct sx *sx"
81 .Fn sx_unlock "struct sx *sx"
83 .Fn sx_try_upgrade "struct sx *sx"
85 .Fn sx_downgrade "struct sx *sx"
87 .Fn sx_sleep "void *chan" "struct sx *sx" "int priority" "const char *wmesg" "int timo"
89 .Fn sx_xholder "struct sx *sx"
91 .Fn sx_xlocked "const struct sx *sx"
93 .Cd "options INVARIANTS"
94 .Cd "options INVARIANT_SUPPORT"
96 .Fn sx_assert "const struct sx *sx" "int what"
98 .Fn SX_SYSINIT "name" "struct sx *sx" "const char *description"
100 Shared/exclusive locks are used to protect data that are read far more often
101 than they are written.
102 Shared/exclusive locks do not implement priority propagation like mutexes and
103 reader/writer locks to prevent priority inversions, so
104 shared/exclusive locks should be used prudently.
106 Shared/exclusive locks are created with either
112 is a pointer to space for a
116 is a pointer to a null-terminated character string that describes the
117 shared/exclusive lock.
122 specifies a set of optional flags to alter the behavior of
124 It contains one or more of the following flags:
125 .Bl -tag -width SX_NOADAPTIVE
127 Disable adaptive spinning, rather than sleeping, for lock operations
128 while an exclusive lock holder is executing on another CPU.
129 Adaptive spinning is the default unless the kernel is compiled with
130 .Cd "options NO_ADAPTIVE_SX" .
132 Witness should not log messages about duplicate locks being acquired.
138 Do not profile this lock.
140 Allow threads to recursively acquire exclusive locks for
143 Do not log any operations for this lock via
147 Shared/exclusive locks are destroyed with
151 must not be locked by any thread when it is destroyed.
153 Threads acquire and release a shared lock by calling
162 Threads acquire and release an exclusive lock by calling
171 A thread can attempt to upgrade a currently held shared lock to an exclusive
174 A thread that has an exclusive lock can downgrade it to a shared lock by
181 will return 0 if the shared/exclusive lock cannot be acquired immediately;
182 otherwise the shared/exclusive lock will be acquired and a non-zero value will
186 will return 0 if the shared lock cannot be upgraded to an exclusive lock
187 immediately; otherwise the exclusive lock will be acquired and a non-zero value
193 do the same as their normal versions but performing an interruptible sleep.
194 They return a non-zero value if the sleep has been interrupted by a signal
195 or an interrupt, otherwise 0.
197 A thread can atomically release a shared/exclusive lock while waiting for an
200 For more details on the parameters to this function,
205 .Cd "options INVARIANTS"
207 .Cd "options INVARIANT_SUPPORT" ,
212 for the assertions specified in
214 and panics if they are not met.
215 One of the following assertions must be specified:
216 .Bl -tag -width ".Dv SA_UNLOCKED"
218 Assert that the current thread has either a shared or an exclusive lock on the
220 lock pointed to by the first argument.
222 Assert that the current thread has a shared lock on the
227 Assert that the current thread has an exclusive lock on the
230 by the first argument.
232 Assert that the current thread has no lock on the
235 by the first argument.
238 In addition, one of the following optional assertions may be included with
245 .Bl -tag -width ".Dv SA_NOTRECURSED"
247 Assert that the current thread has a recursed lock on
249 .It Dv SA_NOTRECURSED
250 Assert that the current thread does not have a recursed lock on
255 will return a pointer to the thread which currently holds an exclusive lock on
257 If no thread holds an exclusive lock on
264 will return non-zero if the current thread holds the exclusive lock;
265 otherwise, it will return zero.
267 For ease of programming,
269 is provided as a macro frontend to the respective functions,
273 Algorithms that are aware of what state the lock is in should use either
274 of the two specific functions for a minor performance benefit.
278 macro is used to generate a call to the
280 routine at system startup in order to initialize a given
283 The parameters are the same as
285 but with an additional argument,
287 that is used in generating unique variable names for the related
288 structures associated with the lock and the sysinit routine.
290 A thread may not hold both a shared lock and an exclusive lock on the same
292 attempting to do so will result in deadlock.
294 A thread may hold a shared or exclusive lock on an
299 lock may not be acquired while holding a mutex.
300 Otherwise, if one thread slept while holding an
302 lock while another thread blocked on the same
304 lock after acquiring a mutex, then the second thread would effectively
305 end up sleeping while holding a mutex, which is not allowed.
314 Currently there is no way to assert that a lock is not held.
315 This is not possible in the
316 .No non- Ns Dv WITNESS
317 case for asserting that this thread
318 does not hold a shared lock.
320 .No non- Ns Dv WITNESS
325 assertions merely check that some thread holds a shared lock.
326 They do not ensure that the current thread holds a shared lock.