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 May 28, 2009 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_NOADAPTIVE 126.It Dv SX_NOADAPTIVE 127If the kernel is not compiled with 128.Cd "options NO_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