/share/man/man9/rwlock.9

  1.\" Copyright (c) 2006 Gleb Smirnoff <glebius@FreeBSD.org>
  2.\" 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, this list of conditions and the following disclaimer.
  9.\" 2. Redistributions in binary form must reproduce the above copyright
 10.\"    notice, this list of conditions and the following disclaimer in the
 11.\"    documentation and/or other materials provided with the distribution.
 12.\"
 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 23.\" SUCH DAMAGE.
 24.\"
 25.\" $FreeBSD$
 26.\"
 27.Dd November 16, 2011
 28.Dt RWLOCK 9
 29.Os
 30.Sh NAME
 31.Nm rwlock ,
 32.Nm rw_init ,
 33.Nm rw_init_flags,
 34.Nm rw_destroy ,
 35.Nm rw_rlock ,
 36.Nm rw_wlock ,
 37.Nm rw_runlock ,
 38.Nm rw_wunlock ,
 39.Nm rw_unlock ,
 40.Nm rw_try_rlock ,
 41.Nm rw_try_upgrade ,
 42.Nm rw_try_wlock ,
 43.Nm rw_downgrade ,
 44.Nm rw_sleep ,
 45.Nm rw_initialized ,
 46.Nm rw_wowned ,
 47.Nm rw_assert ,
 48.Nm RW_SYSINIT
 49.Nd kernel reader/writer lock
 50.Sh SYNOPSIS
 51.In sys/param.h
 52.In sys/lock.h
 53.In sys/rwlock.h
 54.Ft void
 55.Fn rw_init "struct rwlock *rw" "const char *name"
 56.Ft void
 57.Fn rw_init_flags "struct rwlock *rw" "const char *name" "int opts"
 58.Ft void
 59.Fn rw_destroy "struct rwlock *rw"
 60.Ft void
 61.Fn rw_rlock "struct rwlock *rw"
 62.Ft void
 63.Fn rw_wlock "struct rwlock *rw"
 64.Ft int
 65.Fn rw_try_rlock "struct rwlock *rw"
 66.Ft int
 67.Fn rw_try_wlock "struct rwlock *rw"
 68.Ft void
 69.Fn rw_runlock "struct rwlock *rw"
 70.Ft void
 71.Fn rw_wunlock "struct rwlock *rw"
 72.Ft void
 73.Fn rw_unlock "struct rwlock *rw"
 74.Ft int
 75.Fn rw_try_upgrade "struct rwlock *rw"
 76.Ft void
 77.Fn rw_downgrade "struct rwlock *rw"
 78.Ft int
 79.Fn rw_sleep "void *chan" "struct rwlock *rw" "int priority" "const char *wmesg" "int timo"
 80.Ft int
 81.Fn rw_initialized "const struct rwlock *rw"
 82.Ft int
 83.Fn rw_wowned "const struct rwlock *rw"
 84.Pp
 85.Cd "options INVARIANTS"
 86.Cd "options INVARIANT_SUPPORT"
 87.Ft void
 88.Fn rw_assert "const struct rwlock *rw" "int what"
 89.In sys/kernel.h
 90.Fn RW_SYSINIT "name" "struct rwlock *rw" "const char *desc"
 91.Sh DESCRIPTION
 92Reader/writer locks allow shared access to protected data by multiple threads,
 93or exclusive access by a single thread.
 94The threads with shared access are known as
 95.Em readers
 96since they only read the protected data.
 97A thread with exclusive access is known as a
 98.Em writer
 99since it can modify protected data.
100.Pp
101Although reader/writer locks look very similar to
102.Xr sx 9
103locks, their usage pattern is different.
104Reader/writer locks can be treated as mutexes (see
105.Xr mutex 9 )
106with shared/exclusive semantics.
107Unlike
108.Xr sx 9 ,
109an
110.Nm
111can be locked while holding a non-spin mutex, and an
112.Nm
113cannot be held while sleeping.
114The
115.Nm
116locks have priority propagation like mutexes, but priority
117can be propagated only to writers.
118This limitation comes from the fact that readers
119are anonymous.
120Another important property is that readers can always recurse,
121and exclusive locks can be made recursive selectively.
122.Ss Macros and Functions
123.Bl -tag -width indent
124.It Fn rw_init "struct rwlock *rw" "const char *name"
125Initialize structure located at
126.Fa rw
127as reader/writer lock, described by name
128.Fa name .
129The description is used solely for debugging purposes.
130This function must be called before any other operations
131on the lock.
132.It Fn rw_init_flags "struct rwlock *rw" "const char *name" "int opts"
133Initialize the rw lock just like the
134.Fn rw_init
135function, but specifying a set of optional flags to alter the
136behaviour of
137.Fa rw ,
138through the
139.Fa opts
140argument.
141It contains one or more of the following flags:
142.Bl -tag -width ".Dv RW_NOPROFILE"
143.It Dv RW_DUPOK
144Witness should not log messages about duplicate locks being acquired.
145.It Dv RW_NOPROFILE
146Do not profile this lock.
147.It Dv RW_NOWITNESS
148Instruct
149.Xr witness 4
150to ignore this lock.
151.It Dv RW_QUIET
152Do not log any operations for this lock via
153.Xr ktr 4 .
154.It Dv RW_RECURSE
155Allow threads to recursively acquire exclusive locks for
156.Fa rw .
157.El
158.It Fn rw_rlock "struct rwlock *rw"
159Lock
160.Fa rw
161as a reader.
162If any thread holds this lock exclusively, the current thread blocks,
163and its priority is propagated to the exclusive holder.
164The
165.Fn rw_rlock
166function can be called when the thread has already acquired reader
167access on
168.Fa rw .
169This is called
170.Dq "recursing on a lock" .
171.It Fn rw_wlock "struct rwlock *rw"
172Lock
173.Fa rw
174as a writer.
175If there are any shared owners of the lock, the current thread blocks.
176The
177.Fn rw_wlock
178function can be called recursively only if
179.Fa rw
180has been initialized with the
181.Dv RW_RECURSE
182option enabled.
183.It Fn rw_try_rlock "struct rwlock *rw"
184Try to lock
185.Fa rw
186as a reader.
187This function will return true if the operation succeeds, otherwise 0
188will be returned.
189.It Fn rw_try_wlock "struct rwlock *rw"
190Try to lock
191.Fa rw
192as a writer.
193This function will return true if the operation succeeds, otherwise 0
194will be returned.
195.It Fn rw_runlock "struct rwlock *rw"
196This function releases a shared lock previously acquired by
197.Fn rw_rlock .
198.It Fn rw_wunlock "struct rwlock *rw"
199This function releases an exclusive lock previously acquired by
200.Fn rw_wlock .
201.It Fn rw_unlock "struct rwlock *rw"
202This function releases a shared lock previously acquired by
203.Fn rw_rlock
204or an exclusive lock previously acquired by
205.Fn rw_wlock .
206.It Fn rw_try_upgrade "struct rwlock *rw"
207Attempt to upgrade a single shared lock to an exclusive lock.
208The current thread must hold a shared lock of
209.Fa rw .
210This will only succeed if the current thread holds the only shared lock on
211.Fa rw ,
212and it only holds a single shared lock.
213If the attempt succeeds
214.Fn rw_try_upgrade
215will return a non-zero value,
216and the current thread will hold an exclusive lock.
217If the attempt fails
218.Fn rw_try_upgrade
219will return zero,
220and the current thread will still hold a shared lock.
221.It Fn rw_downgrade "struct rwlock *rw"
222Convert an exclusive lock into a single shared lock.
223The current thread must hold an exclusive lock of
224.Fa rw .
225.It Fn rw_sleep "void *chan" "struct rwlock *rw" "int priority" "const char *wmesg" "int timo"
226Atomically release
227.Fa rw
228while waiting for an event.
229For more details on the parameters to this function,
230see
231.Xr sleep 9 .
232.It Fn rw_initialized "const struct rwlock *rw"
233This function returns non-zero if
234.Fa rw
235has been initialized, and zero otherwise.
236.It Fn rw_destroy "struct rwlock *rw"
237This functions destroys a lock previously initialized with
238.Fn rw_init .
239The
240.Fa rw
241lock must be unlocked.
242.It Fn rw_wowned "const struct rwlock *rw"
243This function returns a non-zero value if the current thread owns an
244exclusive lock on
245.Fa rw .
246.It Fn rw_assert "const struct rwlock *rw" "int what"
247This function allows assertions specified in
248.Fa what
249to be made about
250.Fa rw .
251If the assertions are not true and the kernel is compiled
252with
253.Cd "options INVARIANTS"
254and
255.Cd "options INVARIANT_SUPPORT" ,
256the kernel will panic.
257Currently the following assertions are supported:
258.Bl -tag -width ".Dv RA_UNLOCKED"
259.It Dv RA_LOCKED
260Assert that current thread holds either a shared or exclusive lock
261of
262.Fa rw .
263.It Dv RA_RLOCKED
264Assert that current thread holds a shared lock of
265.Fa rw .
266.It Dv RA_WLOCKED
267Assert that current thread holds an exclusive lock of
268.Fa rw .
269.It Dv RA_UNLOCKED
270Assert that current thread holds neither a shared nor exclusive lock of
271.Fa rw .
272.El
273.El
274.Sh SEE ALSO
275.Xr locking 9 ,
276.Xr mutex 9 ,
277.Xr panic 9 ,
278.Xr sema 9 ,
279.Xr sx 9
280.Sh HISTORY
281These
282functions appeared in
283.Fx 7.0 .
284.Sh AUTHORS
285.An -nosplit
286The
287.Nm
288facility was written by
289.An "John Baldwin" .
290This manual page was written by
291.An "Gleb Smirnoff" .
292.Sh BUGS
293If
294.Dv WITNESS
295is not included in the kernel,
296then it is impossible to assert that the current thread does or does not
297hold a read lock.
298In the
299.Pf non- Dv WITNESS
300case, the
301.Dv RA_LOCKED
302and
303.Dv RA_RLOCKED
304assertions merely check that some thread holds a read lock.
305.Pp
306Reader/writer is a bit of an awkward name.
307An
308.Nm
309can also be called a
310.Dq Robert Watson
311lock if desired.