1.\" Copyright (c) 2007 Stephan Uphoff <ups@FreeBSD.org> 2.\" Copyright (c) 2006 Gleb Smirnoff <glebius@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.\" Based on rwlock.9 man page 29.Dd November 10, 2007 30.Dt RMLOCK 9 31.Os 32.Sh NAME 33.Nm rmlock , 34.Nm rm_init , 35.Nm rm_destroy , 36.Nm rm_rlock , 37.Nm rm_wlock , 38.Nm rm_runlock , 39.Nm rm_wunlock , 40.Nm rm_wowned , 41.Nm RM_SYSINIT 42.Nd kernel reader/writer lock optimized for mostly read access patterns 43.Sh SYNOPSIS 44.In sys/param.h 45.In sys/lock.h 46.In sys/rmlock.h 47.Ft void 48.Fn rm_init "struct rmlock *rm" "const char *name" "int opts" 49.Ft void 50.Fn rm_destroy "struct rmlock *rm" 51.Ft void 52.Fn rm_rlock "struct rmlock *rm" "struct rm_priotracker* tracker" 53.Ft void 54.Fn rm_wlock "struct rmlock *rm" 55.Ft void 56.Fn rm_runlock "struct rmlock *rm" "struct rm_priotracker* tracker" 57.Ft void 58.Fn rm_wunlock "struct rmlock *rm" 59.Ft int 60.Fn rm_wowned "struct rmlock *rm" 61.In sys/kernel.h 62.Fn RM_SYSINIT "name" "struct rmlock *rm" "const char *desc" "int opts" 63.Sh DESCRIPTION 64Mostly reader locks allow shared access to protected data by multiple threads, 65or exclusive access by a single thread. 66The threads with shared access are known as 67.Em readers 68since they only read the protected data. 69A thread with exclusive access is known as a 70.Em writer 71since it can modify protected data. 72.Pp 73Read mostly locks are designed to be efficient for locks almost exclusively 74used as reader locks and as such should be used for protecting data that 75rarely changes. 76Acquiring an exclusive lock after the lock had been locked for shared access 77is an expensive operation. 78.Pp 79Although reader/writer locks look very similar to 80.Xr sx 9 81locks, their usage pattern is different. 82Reader/writer locks can be treated as mutexes (see 83.Xr mutex 9 ) 84with shared/exclusive semantics. 85Unlike 86.Xr sx 9 , 87an 88.Nm 89can be locked while holding a non-spin mutex, and an 90.Nm 91cannot be held while sleeping. 92The 93.Nm 94locks have full priority propagation like mutexes. 95The 96.Va rm_priotracker 97structure argument supplied in 98.Fn rm_rlock 99and 100.Fn rm_runlock 101is used to keep track of the read owner(s). 102Another important property is that shared holders of 103.Nm 104can recurse if the lock has been initialized with the 105.Dv LO_RECURSABLE 106option, however exclusive locks are not allowed to recurse. 107.Ss Macros and Functions 108.Bl -tag -width indent 109.It Fn rm_init "struct rmlock *rm" "const char *name" "int opts" 110Initialize structure located at 111.Fa rm 112as mostly reader lock, described by 113.Fa name . 114Optionally allowing readers to recurse by setting 115.Dv LO_RECURSABLE 116in 117.Fa opts . 118The name description is used solely for debugging purposes. 119This function must be called before any other operations 120on the lock. 121.It Fn rm_rlock "struct rmlock *rm" "struct rm_priotracker* tracker" 122Lock 123.Fa rm 124as a reader. 125Using 126.Fa tracker 127to track read owners of a lock for priority propagation. 128This data structure is only used internally by 129.Nm 130and must persist until 131.Fn rm_runlock 132has been called. 133This data structure can be allocated on the stack since 134rmlocks cannot be held while sleeping. 135If any thread holds this lock exclusively, the current thread blocks, 136and its priority is propagated to the exclusive holder. 137If the lock was initialized with the 138.Dv LO_RECURSABLE 139option the 140.Fn rm_rlock 141function can be called when the thread has already acquired reader 142access on 143.Fa rm . 144This is called 145.Dq "recursing on a lock" . 146.It Fn rm_wlock "struct rmlock *rm" 147Lock 148.Fa rm 149as a writer. 150If there are any shared owners of the lock, the current thread blocks. 151The 152.Fn rm_wlock 153function cannot be called recursively. 154.It Fn rm_runlock "struct rmlock *rm" "struct rm_priotracker* tracker" 155This function releases a shared lock previously acquired by 156.Fn rm_rlock . 157The 158.Fa tracker 159argument must match the 160.Fa tracker 161argument used for acquiring the shared lock 162.It Fn rm_wunlock "struct rmlock *rm" 163This function releases an exclusive lock previously acquired by 164.Fn rm_wlock . 165.It Fn rm_destroy "struct rmlock *rm" 166This functions destroys a lock previously initialized with 167.Fn rm_init . 168The 169.Fa rm 170lock must be unlocked. 171.It Fn rm_wowned "struct rmlock *rm" 172This function returns a non-zero value if the current thread owns an 173exclusive lock on 174.Fa rm . 175.El 176.Sh SEE ALSO 177.Xr locking 9 , 178.Xr mutex 9 , 179.Xr panic 9 , 180.Xr rwlock 9 , 181.Xr sema 9 , 182.Xr sx 9 183.Sh HISTORY 184These 185functions appeared in 186.Fx 7.0 . 187.Sh AUTHORS 188.An -nosplit 189The 190.Nm 191facility was written by 192.An "Stephan Uphoff" . 193This manual page was written by 194.An "Gleb Smirnoff" 195for rwlock and modified to reflect rmlock by 196.An "Stephan Uphoff" . 197.Sh BUGS 198The 199.Nm 200implementation is currently not optimized for single processor systems. 201.Pp 202The 203.Nm 204implementation uses a single per CPU list shared by all 205rmlocks in the system. 206If rmlocks become popular, hashing to multiple per CPU queues may 207be needed to speed up the writer lock process. 208.Pp 209The 210.Nm 211can currently not be used as a lock argument for condition variable 212wait functions. 213