xref: /freebsd/share/man/man9/sx.9 (revision a220d00e74dd245b4fca59c5eca0c53963686325)
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 August 14, 2001
30.Dt SX 9
31.Os
32.Sh NAME
33.Nm sx ,
34.Nm sx_init ,
35.Nm sx_destroy ,
36.Nm sx_slock ,
37.Nm sx_xlock ,
38.Nm sx_try_slock ,
39.Nm sx_try_xlock ,
40.Nm sx_sunlock ,
41.Nm sx_xunlock ,
42.Nm sx_try_upgrade ,
43.Nm sx_downgrade ,
44.Nm sx_assert
45.Nd kernel shared/exclusive lock
46.Sh SYNOPSIS
47.In sys/param.h
48.In sys/lock.h
49.In sys/mutex.h
50.In sys/sx.h
51.Ft void
52.Fn sx_init "struct sx *sx" "const char *description"
53.Ft void
54.Fn sx_destroy "struct sx *sx"
55.Ft void
56.Fn sx_slock "struct sx *sx"
57.Ft void
58.Fn sx_xlock "struct sx *sx"
59.Ft int
60.Fn sx_try_slock "struct sx *sx"
61.Ft int
62.Fn sx_try_xlock "struct sx *sx"
63.Ft void
64.Fn sx_sunlock "struct sx *sx"
65.Ft void
66.Fn sx_xunlock "struct sx *sx"
67.Ft int
68.Fn sx_try_upgrade "struct sx *sx"
69.Ft void
70.Fn sx_downgrade "struct sx *sx"
71.Ft void
72.Fn sx_assert "struct sx *sx" "int what"
73.Sh DESCRIPTION
74Shared/exclusive locks are used to protect data that are read far more often
75than they are written.
76Mutexes are inherently more efficient than shared/exclusive locks, so
77shared/exclusive locks should be used prudently.
78.Pp
79Shared/exclusive locks are created with
80.Fn sx_init ,
81where
82.Fa sx
83is a pointer to space for a
84.Vt struct sx ,
85and
86.Fa description
87is a pointer to a null-terminated character string that describes the
88shared/exclusive lock.
89Shared/exclusive locks are destroyed with
90.Fn sx_destroy .
91Threads acquire and release a shared lock by calling
92.Fn sx_slock
93or
94.Fn sx_try_slock
95and
96.Fn sx_sunlock .
97Threads acquire and release an exclusive lock by calling
98.Fn sx_xlock
99or
100.Fn sx_try_xlock
101and
102.Fn sx_xunlock .
103A thread can attempt to upgrade a currently owned shared lock to an exclusive
104lock by calling
105.Fn sx_try_upgrade .
106A thread that owns an exclusive lock can downgrade it to a shared lock by
107calling
108.Fn sx_downgrade .
109.Pp
110.Fn sx_try_slock
111and
112.Fn sx_try_xlock
113will return 0 if the shared/exclusive lock cannot be acquired immediately;
114otherwise the shared/exclusive lock will be acquired and a non-zero value will
115be returned.
116.Pp
117.Fn sx_try_upgrade
118will return 0 if the shared lock cannot be upgraded to an exclusive lock
119immediately; otherwise the exclusive lock will be acquired and a non-zero value
120will be returned.
121.Pp
122The
123.Fn sx_assert
124function tests specified conditions and panics if they are not met and the
125kernel is compiled with
126.Dv INVARIANTS .
127The following assertions are supported:
128.Bl -tag -width SX_XLOCKED
129.It Dv SX_LOCKED
130Assert that the current thread has either a shared or an exclusive lock on the
131sx lock pointed to by the first argument.
132.It Dv SX_SLOCKED
133Assert that the current thread has a shared lock on the sx lock pointed to by
134the first argument.
135.It Dv SX_XLOCKED
136Assert that the current thread has an exclusive lock on the sx lock pointed to
137by the first argument.
138.El
139.Pp
140A thread may not own a shared lock and an exclusive lock simultaneously;
141attempting to do so will result in deadlock.
142.Sh SEE ALSO
143.Xr condvar 9 ,
144.Xr mutex 9 ,
145.Xr sema 9
146.Sh BUGS
147Currently there is no way to assert that a lock is not held.
148This is not possible in the non-WITNESS case for asserting that this thread
149does not hold a shared lock.
150In the non-WITNESS case, the
151.Dv SX_LOCKED
152and
153.Dv SX_SLOCKED
154assertions merely check that some thread holds a shared lock.
155They do not ensure that the current thread holds a shared lock.
156