xref: /freebsd/share/man/man9/sx.9 (revision 1e413cf93298b5b97441a21d9a50fdcd0ee9945e)
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 25, 2007
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.Nd kernel shared/exclusive lock
54.Sh SYNOPSIS
55.In sys/param.h
56.In sys/lock.h
57.In sys/sx.h
58.Ft void
59.Fn sx_init "struct sx *sx" "const char *description"
60.Ft void
61.Fn sx_init_flags "struct sx *sx" "const char *description" "int opts"
62.Ft void
63.Fn sx_destroy "struct sx *sx"
64.Ft void
65.Fn sx_slock "struct sx *sx"
66.Ft void
67.Fn sx_xlock "struct sx *sx"
68.Ft int
69.Fn sx_slock_sig "struct sx *sx"
70.Ft int
71.Fn sx_xlock_sig "struct sx *sx"
72.Ft int
73.Fn sx_try_slock "struct sx *sx"
74.Ft int
75.Fn sx_try_xlock "struct sx *sx"
76.Ft void
77.Fn sx_sunlock "struct sx *sx"
78.Ft void
79.Fn sx_xunlock "struct sx *sx"
80.Ft void
81.Fn sx_unlock "struct sx *sx"
82.Ft int
83.Fn sx_try_upgrade "struct sx *sx"
84.Ft void
85.Fn sx_downgrade "struct sx *sx"
86.Ft int
87.Fn sx_sleep "void *chan" "struct sx *sx" "int priority" "const char *wmesg" "int timo"
88.Ft "struct thread *"
89.Fn sx_xholder "struct sx *sx"
90.Ft int
91.Fn sx_xlocked "struct sx *sx"
92.Pp
93.Cd "options INVARIANTS"
94.Cd "options INVARIANT_SUPPORT"
95.Ft void
96.Fn sx_assert "struct sx *sx" "int what"
97.In sys/kernel.h
98.Fn SX_SYSINIT "name" "struct sx *sx" "const char *description"
99.Sh DESCRIPTION
100Shared/exclusive locks are used to protect data that are read far more often
101than they are written.
102Shared/exclusive locks do not implement priority propagation like mutexes and
103reader/writer locks to prevent priority inversions, so
104shared/exclusive locks should be used prudently.
105.Pp
106Shared/exclusive locks are created with either
107.Fn sx_init
108or
109.Fn sx_init_flags
110where
111.Fa sx
112is a pointer to space for a
113.Vt struct sx ,
114and
115.Fa description
116is a pointer to a null-terminated character string that describes the
117shared/exclusive lock.
118The
119.Fa opts
120argument to
121.Fn sx_init_flags
122specifies a set of optional flags to alter the behavior of
123.Fa sx .
124It contains one or more of the following flags:
125.Bl -tag -width SX_ADAPTIVESPIN
126.It Dv SX_ADAPTIVESPIN
127If the kernel is compiled with
128.Cd "options ADAPTIVE_SX" ,
129then lock operations for
130.Fa sx
131will spin instead of sleeping while an exclusive lock holder is executing on
132another CPU.
133.It Dv SX_DUPOK
134Witness should not log messages about duplicate locks being acquired.
135.It Dv SX_NOWITNESS
136Instruct
137.Xr witness 4
138to ignore this lock.
139.It Dv SX_NOPROFILE
140Do not profile this lock.
141.It Dv SX_RECURSE
142Allow threads to recursively acquire exclusive locks for
143.Fa sx .
144.It Dv SX_QUIET
145Do not log any operations for this lock via
146.Xr ktr 4 .
147.El
148.Pp
149Shared/exclusive locks are destroyed with
150.Fn sx_destroy .
151The lock
152.Fa sx
153must not be locked by any thread when it is destroyed.
154.Pp
155Threads acquire and release a shared lock by calling
156.Fn sx_slock ,
157.Fn sx_slock_sig
158or
159.Fn sx_try_slock
160and
161.Fn sx_sunlock
162or
163.Fn sx_unlock .
164Threads acquire and release an exclusive lock by calling
165.Fn sx_xlock ,
166.Fn sx_xlock_sig
167or
168.Fn sx_try_xlock
169and
170.Fn sx_xunlock
171or
172.Fn sx_unlock .
173A thread can attempt to upgrade a currently held shared lock to an exclusive
174lock by calling
175.Fn sx_try_upgrade .
176A thread that has an exclusive lock can downgrade it to a shared lock by
177calling
178.Fn sx_downgrade .
179.Pp
180.Fn sx_try_slock
181and
182.Fn sx_try_xlock
183will return 0 if the shared/exclusive lock cannot be acquired immediately;
184otherwise the shared/exclusive lock will be acquired and a non-zero value will
185be returned.
186.Pp
187.Fn sx_try_upgrade
188will return 0 if the shared lock cannot be upgraded to an exclusive lock
189immediately; otherwise the exclusive lock will be acquired and a non-zero value
190will be returned.
191.Pp
192.Fn sx_slock_sig
193and
194.Fn sx_xlock_sig
195do the same as their normal versions but performing an interruptible sleep.
196They return a non-zero value if the sleep has been interrupted by a signal
197or an interrupt, otherwise 0.
198.Pp
199A thread can atomically release a shared/exclusive lock while waiting for an
200event by calling
201.Fn sx_sleep .
202For more details on the parameters to this function,
203see
204.Xr sleep 9 .
205.Pp
206When compiled with
207.Cd "options INVARIANTS"
208and
209.Cd "options INVARIANT_SUPPORT" ,
210the
211.Fn sx_assert
212function tests
213.Fa sx
214for the assertions specified in
215.Fa what ,
216and panics if they are not met.
217One of the following assertions must be specified:
218.Bl -tag -width ".Dv SA_UNLOCKED"
219.It Dv SA_LOCKED
220Assert that the current thread has either a shared or an exclusive lock on the
221.Vt sx
222lock pointed to by the first argument.
223.It Dv SA_SLOCKED
224Assert that the current thread has a shared lock on the
225.Vt sx
226lock pointed to by
227the first argument.
228.It Dv SA_XLOCKED
229Assert that the current thread has an exclusive lock on the
230.Vt sx
231lock pointed to
232by the first argument.
233.It Dv SA_UNLOCKED
234Assert that the current thread has no lock on the
235.Vt sx
236lock pointed to
237by the first argument.
238.El
239.Pp
240In addition, one of the following optional assertions may be included with
241either an
242.Dv SA_LOCKED ,
243.Dv SA_SLOCKED ,
244or
245.Dv SA_XLOCKED
246assertion:
247.Bl -tag -width ".Dv SA_NOTRECURSED"
248.It Dv SA_RECURSED
249Assert that the current thread has a recursed lock on
250.Fa sx .
251.It Dv SA_NOTRECURSED
252Assert that the current thread does not have a recursed lock on
253.Fa sx .
254.El
255.Pp
256.Fn sx_xholder
257will return a pointer to the thread which currently holds an exclusive lock on
258.Fa sx .
259If no thread holds an exclusive lock on
260.Fa sx ,
261then
262.Dv NULL
263is returned instead.
264.Pp
265.Fn sx_xlocked
266will return non-zero if the current thread holds the exclusive lock;
267otherwise, it will return zero.
268.Pp
269For ease of programming,
270.Fn sx_unlock
271is provided as a macro frontend to the respective functions,
272.Fn sx_sunlock
273and
274.Fn sx_xunlock .
275Algorithms that are aware of what state the lock is in should use either
276of the two specific functions for a minor performance benefit.
277.Pp
278The
279.Fn SX_SYSINIT
280macro is used to generate a call to the
281.Fn sx_sysinit
282routine at system startup in order to initialize a given
283.Fa sx
284lock.
285The parameters are the same as
286.Fn sx_init
287but with an additional argument,
288.Fa name ,
289that is used in generating unique variable names for the related
290structures associated with the lock and the sysinit routine.
291.Pp
292A thread may not hold both a shared lock and an exclusive lock on the same
293lock simultaneously;
294attempting to do so will result in deadlock.
295.Sh CONTEXT
296A thread may hold a shared or exclusive lock on an
297.Nm
298lock while sleeping.
299As a result, an
300.Nm
301lock may not be acquired while holding a mutex.
302Otherwise, if one thread slept while holding an
303.Nm
304lock while another thread blocked on the same
305.Nm
306lock after acquiring a mutex, then the second thread would effectively
307end up sleeping while holding a mutex, which is not allowed.
308.Sh SEE ALSO
309.Xr locking 9 ,
310.Xr lock 9 ,
311.Xr mutex 9 ,
312.Xr panic 9 ,
313.Xr rwlock 9 ,
314.Xr sema 9
315.Sh BUGS
316Currently there is no way to assert that a lock is not held.
317This is not possible in the
318.No non- Ns Dv WITNESS
319case for asserting that this thread
320does not hold a shared lock.
321In the
322.No non- Ns Dv WITNESS
323case, the
324.Dv SA_LOCKED
325and
326.Dv SA_SLOCKED
327assertions merely check that some thread holds a shared lock.
328They do not ensure that the current thread holds a shared lock.
329