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 June 8, 2012 30.Dt RMLOCK 9 31.Os 32.Sh NAME 33.Nm rmlock , 34.Nm rm_init , 35.Nm rm_init_flags , 36.Nm rm_destroy , 37.Nm rm_rlock , 38.Nm rm_try_rlock , 39.Nm rm_wlock , 40.Nm rm_runlock , 41.Nm rm_wunlock , 42.Nm rm_wowned , 43.Nm RM_SYSINIT 44.Nd kernel reader/writer lock optimized for read-mostly access patterns 45.Sh SYNOPSIS 46.In sys/param.h 47.In sys/lock.h 48.In sys/rmlock.h 49.Ft void 50.Fn rm_init "struct rmlock *rm" "const char *name" 51.Ft void 52.Fn rm_init_flags "struct rmlock *rm" "const char *name" "int opts" 53.Ft void 54.Fn rm_destroy "struct rmlock *rm" 55.Ft void 56.Fn rm_rlock "struct rmlock *rm" "struct rm_priotracker* tracker" 57.Ft int 58.Fn rm_try_rlock "struct rmlock *rm" "struct rm_priotracker* tracker" 59.Ft void 60.Fn rm_wlock "struct rmlock *rm" 61.Ft void 62.Fn rm_runlock "struct rmlock *rm" "struct rm_priotracker* tracker" 63.Ft void 64.Fn rm_wunlock "struct rmlock *rm" 65.Ft int 66.Fn rm_wowned "const struct rmlock *rm" 67.In sys/kernel.h 68.Fn RM_SYSINIT "name" "struct rmlock *rm" "const char *desc" "int opts" 69.Sh DESCRIPTION 70Read-mostly locks allow shared access to protected data by multiple threads, 71or exclusive access by a single thread. 72The threads with shared access are known as 73.Em readers 74since they only read the protected data. 75A thread with exclusive access is known as a 76.Em writer 77since it can modify protected data. 78.Pp 79Read-mostly locks are designed to be efficient for locks almost exclusively 80used as reader locks and as such should be used for protecting data that 81rarely changes. 82Acquiring an exclusive lock after the lock has been locked for shared access 83is an expensive operation. 84.Pp 85Normal read-mostly locks are similar to 86.Xr rwlock 9 87locks and follow the same lock ordering rules as 88.Xr rwlock 9 89locks. 90Read-mostly locks have full priority propagation like mutexes. 91Unlike 92.Xr rwlock 9 , 93read-mostly locks propagate priority to both readers and writers. 94This is implemented via the 95.Va rm_priotracker 96structure argument supplied to 97.Fn rm_rlock 98and 99.Fn rm_runlock . 100Readers can recurse if the lock is initialized with the 101.Dv RM_RECURSE 102option; 103however, writers are never allowed to recurse. 104.Pp 105Sleepable read-mostly locks are created by passing 106.Dv RM_SLEEPABLE 107to 108.Fn rm_init_flags . 109Unlike normal read-mostly locks, 110sleepable read-mostly locks follow the same lock ordering rules as 111.Xr sx 9 112locks. 113Sleepable read-mostly locks do not propagate priority to writers, 114but they do propagate priority to readers. 115Writers are permitted to sleep while holding a read-mostly lock, 116but readers are not. 117Unlike other sleepable locks such as 118.Xr sx 9 119locks, 120readers must use try operations on other sleepable locks to avoid sleeping. 121.Ss Macros and Functions 122.Bl -tag -width indent 123.It Fn rm_init "struct rmlock *rm" "const char *name" 124Initialize the read-mostly lock 125.Fa rm . 126The 127.Fa name 128description is used solely for debugging purposes. 129This function must be called before any other operations 130on the lock. 131.It Fn rm_init_flags "struct rmlock *rm" "const char *name" "int opts" 132Similar to 133.Fn rm_init , 134initialize the read-mostly lock 135.Fa rm 136with a set of optional flags. 137The 138.Fa opts 139arguments contains one or more of the following flags: 140.Bl -tag -width ".Dv RM_NOWITNESS" 141.It Dv RM_NOWITNESS 142Instruct 143.Xr witness 4 144to ignore this lock. 145.It Dv RM_RECURSE 146Allow threads to recursively acquire shared locks for 147.Fa rm . 148.It Dv RM_SLEEPABLE 149Create a sleepable read-mostly lock. 150.El 151.It Fn rm_rlock "struct rmlock *rm" "struct rm_priotracker* tracker" 152Lock 153.Fa rm 154as a reader using 155.Fa tracker 156to track read owners of a lock for priority propagation. 157This data structure is only used internally by 158.Nm 159and must persist until 160.Fn rm_runlock 161has been called. 162This data structure can be allocated on the stack since 163readers cannot sleep. 164If any thread holds this lock exclusively, the current thread blocks, 165and its priority is propagated to the exclusive holder. 166If the lock was initialized with the 167.Dv RM_RECURSE 168option the 169.Fn rm_rlock 170function can be called when the current thread has already acquired reader 171access on 172.Fa rm . 173.It Fn rm_try_rlock "struct rmlock *rm" "struct rm_priotracker* tracker" 174Try to lock 175.Fa rm 176as a reader. 177.Fn rm_try_rlock 178will return 0 if the lock cannot be acquired immediately; 179otherwise, 180the lock will be acquired and a non-zero value will be returned. 181Note that 182.Fn rm_try_rlock 183may fail even while the lock is not currently held by a writer. 184If the lock was initialized with the 185.Dv RM_RECURSE 186option, 187.Fn rm_try_rlock 188will succeed if the current thread has already acquired reader access. 189.It Fn rm_wlock "struct rmlock *rm" 190Lock 191.Fa rm 192as a writer. 193If there are any shared owners of the lock, the current thread blocks. 194The 195.Fn rm_wlock 196function cannot be called recursively. 197.It Fn rm_runlock "struct rmlock *rm" "struct rm_priotracker* tracker" 198This function releases a shared lock previously acquired by 199.Fn rm_rlock . 200The 201.Fa tracker 202argument must match the 203.Fa tracker 204argument used for acquiring the shared lock 205.It Fn rm_wunlock "struct rmlock *rm" 206This function releases an exclusive lock previously acquired by 207.Fn rm_wlock . 208.It Fn rm_destroy "struct rmlock *rm" 209This functions destroys a lock previously initialized with 210.Fn rm_init . 211The 212.Fa rm 213lock must be unlocked. 214.It Fn rm_wowned "const struct rmlock *rm" 215This function returns a non-zero value if the current thread owns an 216exclusive lock on 217.Fa rm . 218.El 219.Sh SEE ALSO 220.Xr locking 9 , 221.Xr mutex 9 , 222.Xr panic 9 , 223.Xr rwlock 9 , 224.Xr sema 9 , 225.Xr sx 9 226.Sh HISTORY 227These 228functions appeared in 229.Fx 7.0 . 230.Sh AUTHORS 231.An -nosplit 232The 233.Nm 234facility was written by 235.An "Stephan Uphoff" . 236This manual page was written by 237.An "Gleb Smirnoff" 238for rwlock and modified to reflect rmlock by 239.An "Stephan Uphoff" . 240.Sh BUGS 241The 242.Nm 243implementation is currently not optimized for single processor systems. 244.Pp 245.Fn rm_try_rlock 246can fail transiently even when there is no writer, while another reader 247updates the state on the local CPU. 248.Pp 249The 250.Nm 251implementation uses a single per CPU list shared by all 252rmlocks in the system. 253If rmlocks become popular, hashing to multiple per CPU queues may 254be needed to speed up the writer lock process. 255.Pp 256The 257.Nm 258can currently not be used as a lock argument for condition variable 259wait functions. 260