1.\" $NetBSD: rwlock.9,v 1.10 2008/04/30 13:10:58 martin Exp $ 2.\" 3.\" Copyright (c) 2006, 2007 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Andrew Doran. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd December 4, 2007 31.Dt RWLOCK 9 32.Os 33.Sh NAME 34.Nm rw , 35.Nm rw_init , 36.Nm rw_destroy , 37.Nm rw_enter , 38.Nm rw_exit , 39.Nm rw_tryenter , 40.Nm rw_tryupgrade , 41.Nm rw_downgrade , 42.Nm rw_read_held , 43.Nm rw_write_held , 44.Nm rw_lock_held 45.Nd reader / writer lock primitives 46.Sh SYNOPSIS 47.In sys/rwlock.h 48.Ft void 49.Fn rw_init "krwlock_t *rw" 50.Ft void 51.Fn rw_destroy "krwlock_t *rw" 52.Ft void 53.Fn rw_enter "krwlock_t *rw" "const krw_t op" 54.Ft void 55.Fn rw_exit "krwlock_t *rw" 56.Ft int 57.Fn rw_tryenter "krwlock_t *rw" "const krw_t op" 58.Ft int 59.Fn rw_tryupgrade "krwlock_t *rw" 60.Ft void 61.Fn rw_downgrade "krwlock_t *rw" 62.Ft int 63.Fn rw_read_held "krwlock_t *rw" 64.Ft int 65.Fn rw_write_held "krwlock_t *rw" 66.Ft int 67.Fn rw_lock_held "krwlock_t *rw" 68.Pp 69.Cd "options DIAGNOSTIC" 70.Cd "options LOCKDEBUG" 71.Sh DESCRIPTION 72Reader / writer locks (RW locks) are used in the kernel to synchronize access 73to an object among LWPs (lightweight processes) and soft interrupt handlers. 74.Pp 75In addition to the capabilities provided by mutexes, RW locks distinguish 76between read (shared) and write (exclusive) access. 77RW locks are intended to provide protection for kernel data 78or objects that are read much more frequently than updated. 79For objects that are updated as frequently as they are read, mutexes should 80be used to guarantee atomic access. 81.Pp 82RW locks are in one of three distinct states at any given time: 83.Bl -tag -width cdosrunrundo 84.It Dv Unlocked 85The lock is not held. 86.It Dv Read locked 87The lock holders intend to read the protected object. 88Multiple callers may hold a RW lock with 89.Dq read intent 90simultaneously. 91.It Dv Write locked 92The lock holder intends to update the protected object. 93Only one caller may hold a RW lock with 94.Dq write intent . 95.El 96.Pp 97The 98.Vt krwlock_t 99type provides storage for the RW lock object. 100This should be treated as an opaque object and not examined directly by 101consumers. 102.Pp 103Note that the these interfaces must not be used from a hardware 104interrupt handler. 105.Sh OPTIONS AND MACROS 106.Bl -tag -width abcd 107.It Cd "options DIANOSTIC" 108.Pp 109Kernels compiled with the 110.Dv DIAGNOSTIC 111option perform basic sanity checks on RW lock operations. 112.It Cd "options LOCKDEBUG" 113.Pp 114Kernels compiled with the 115.Dv LOCKDEBUG 116option perform potentially CPU intensive sanity checks 117on RW lock operations. 118.El 119.Sh FUNCTIONS 120.Bl -tag -width abcd 121.It Fn rw_init "rw" 122.Pp 123Initialize a lock for use. 124No other operations can be performed on the lock until it has been 125initialized. 126.It Fn rw_destroy "rw" 127.Pp 128Release resources used by a lock. 129The lock may not be used after it has been destroyed. 130.It Fn rw_enter "rw" "op" 131.Pp 132If 133.Dv RW_READER 134is specified as the argument to 135.Fa op , 136acquire a read lock. 137If the lock is write held, the caller will block and not return until the 138hold is acquired. 139Callers must not recursively acquire read locks. 140.Pp 141If 142.Dv RW_WRITER 143is specified, acquire a write lock. 144If the lock is already held, the caller will block and not return until the 145hold is acquired. 146.Pp 147RW locks and other types of locks must always be acquired in a 148consistent order with respect to each other. 149Otherwise, the potential for system deadlock exists. 150.It Fn rw_exit "rw" 151.Pp 152Release a lock. 153The lock must have been previously acquired by the caller. 154.It Fn rw_tryenter "rw" "op" 155.Pp 156Try to acquire a lock, but do not block if the lock is already held. 157If the lock is acquired successfully, return non-zero. 158Otherwise, return zero. 159.Pp 160Valid arguments to 161.Fa op 162are 163.Dv RW_READER 164or 165.Dv RW_WRITER . 166.It Fn rw_tryupgrade "rw" 167.Pp 168Try to upgrade a lock from one read hold to a write hold. 169If the lock is upgraded successfully, returns non-zero. 170Otherwise, returns zero. 171.It Fn rw_downgrade "rw" 172.Pp 173Downgrade a lock from a write hold to a read hold. 174.It Fn rw_write_held "rw" 175.It Fn rw_read_held "rw" 176.It Fn rw_lock_held "rw" 177.Pp 178Test the lock's condition and return non-zero if the lock is held 179(potentially by the current LWP) and matches the specified condition. 180Otherwise, return zero. 181.Pp 182These functions must never be used to make locking decisions at run time: 183they are provided only for diagnostic purposes. 184.El 185.Sh CODE REFERENCES 186This section describes places within the 187.Nx 188source tree where code implementing RW locks can be found. 189All pathnames are relative to 190.Pa /usr/src . 191.Pp 192The core of the RW lock implementation is in 193.Pa sys/kern/kern_rwlock.c . 194.Pp 195The header file 196.Pa sys/sys/rwlock.h 197describes the public interface, and interfaces that machine-dependent 198code must provide to support RW locks. 199.Sh SEE ALSO 200.Xr condvar 9 , 201.Xr mb 9 , 202.Xr mutex 9 203.Rs 204.%A Jim Mauro 205.%A Richard McDougall 206.%T Solaris Internals: Core Kernel Architecture 207.%I Prentice Hall 208.%D 2001 209.%O ISBN 0-13-022496-0 210.Re 211.Sh HISTORY 212The RW lock primitives first appeared in 213.Nx 5.0 . 214