share/man/man9/vm_page_busy.9

   1 .\"
   2 .\" Copyright (c) 2013 EMC Corp.
   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 OR
  20 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  21 .\" 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 SUCH
  24 .\" DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .Dd August 07, 2013
  28 .Dt VM_PAGE_BUSY 9
  29 .Os
  30 .Sh NAME
  31 .Nm vm_page_busied ,
  32 .Nm vm_page_busy_downgrade ,
  33 .Nm vm_page_busy_sleep ,
  34 .Nm vm_page_sbusied ,
  35 .Nm vm_page_sbusy ,
  36 .Nm vm_page_sleep_if_busy ,
  37 .Nm vm_page_sunbusy ,
  38 .Nm vm_page_trysbusy ,
  39 .Nm vm_page_tryxbusy ,
  40 .Nm vm_page_xbusied ,
  41 .Nm vm_page_xbusy ,
  42 .Nm vm_page_xunbusy ,
  43 .Nm vm_page_assert_sbusied ,
  44 .Nm vm_page_assert_unbusied ,
  45 .Nm vm_page_assert_xbusied
  46 .Nd protect page identity changes and page content references
  47 .Sh SYNOPSIS
  48 .In sys/param.h
  49 .In vm/vm.h
  50 .In vm/vm_page.h
  51 .Ft int
  52 .Fn vm_page_busied "vm_page_t m"
  53 .Ft void
  54 .Fn vm_page_busy_downgrade "vm_page_t m"
  55 .Ft void
  56 .Fn vm_page_busy_sleep "vm_page_t m" "const char *msg"
  57 .Ft int
  58 .Fn vm_page_sbusied "vm_page_t m"
  59 .Ft void
  60 .Fn vm_page_sbusy "vm_page_t m"
  61 .Ft int
  62 .Fn vm_page_sleep_if_busy "vm_page_t m" "const char *msg"
  63 .Ft void
  64 .Fn vm_page_sunbusy "vm_page_t m"
  65 .Ft int
  66 .Fn vm_page_trysbusy "vm_page_t m"
  67 .Ft int
  68 .Fn vm_page_tryxbusy "vm_page_t m"
  69 .Ft int
  70 .Fn vm_page_xbusied "vm_page_t m"
  71 .Ft void
  72 .Fn vm_page_xbusy "vm_page_t m"
  73 .Ft void
  74 .Fn vm_page_xunbusy "vm_page_t m"
  75 .Pp
  76 .Cd "options INVARIANTS"
  77 .Cd "options INVARIANT_SUPPORT"
  78 .Ft void
  79 .Fn vm_page_assert_sbusied "vm_page_t m"
  80 .Ft void
  81 .Fn vm_page_assert_unbusied "vm_page_t m"
  82 .Ft void
  83 .Fn vm_page_assert_xbusied "vm_page_t m"
  84 .Sh DESCRIPTION
  85 Page identity is usually protected by higher level locks like vm_object
  86 locks and vm page locks.
  87 However, sometimes it is not possible to hold such locks for the time
  88 necessary to complete the identity change.
  89 In such case the page can be exclusively busied by a thread which needs
  90 to own the identity for a certain amount of time.
  91 .Pp
  92 In other situations, threads do not need to change the identity of the
  93 page but they want to prevent other threads from changing the identity
  94 themselves.
  95 For example, when a thread wants to access or update page contents
  96 without a lock held the page is shared busied.
  97 .Pp
  98 Before busing a page the vm_object lock must be held.
  99 The same rule applies when a page is unbusied.
 100 This makes the vm_object lock a real busy interlock.
 101 .Pp
 102 The
 103 .Fn vm_page_busied
 104 function returns non-zero if the current thread busied
 105 .Fa m
 106 in either exclusive or shared mode.
 107 Returns zero otherwise.
 108 .Pp
 109 The
 110 .Fn vm_page_busy_downgrade
 111 function must be used to downgrade
 112 .Fa m
 113 from an exclusive busy state to a shared busy state.
 114 .Pp
 115 The
 116 .Fn vm_page_busy_sleep
 117 function puts the invoking thread to sleep using the appropriate
 118 waitchannels for the busy mechanism.
 119 The parameter
 120 .Fa msg
 121 is a string describing the sleep condition for userland tools.
 122 .Pp
 123 The
 124 .Fn vm_page_busied
 125 function returns non-zero if the current thread busied
 126 .Fa m
 127 in shared mode.
 128 Returns zero otherwise.
 129 .Pp
 130 The
 131 .Fn vm_page_sbusy
 132 function shared busies
 133 .Fa m .
 134 .Pp
 135 The
 136 .Fn vm_page_sleep_if_busy
 137 function puts the invoking thread to sleep, using the appropriate
 138 waitchannels for the busy mechanism, if
 139 .Fa m .
 140 is busied in either exclusive or shared mode.
 141 If the invoking thread slept a non-zero value is returned, otherwise
 142 0 is returned.
 143 The parameter
 144 .Fa msg
 145 is a string describing the sleep condition for userland tools.
 146 .Pp
 147 The
 148 .Fn vm_page_sunbusy
 149 function shared unbusies
 150 .Fa m .
 151 .Pp
 152 The
 153 .Fn vm_page_trysbusy
 154 attempts to shared busy
 155 .Fa m .
 156 If the operation cannot immediately succeed
 157 .Fn vm_page_trysbusy
 158 returns 0, otherwise a non-zero value is returned.
 159 .Pp
 160 The
 161 .Fn vm_page_tryxbusy
 162 attempts to exclusive busy
 163 .Fa m .
 164 If the operation cannot immediately succeed
 165 .Fn vm_page_tryxbusy
 166 returns 0, otherwise a non-zero value is returned.
 167 .Pp
 168 The
 169 .Fn vm_page_xbusied
 170 function returns non-zero if the current thread busied
 171 .Fa m
 172 in exclusive mode.
 173 Returns zero otherwise.
 174 .Pp
 175 The
 176 .Fn vm_page_xbusy
 177 function exclusive busies
 178 .Fa m .
 179 .Pp
 180 The
 181 .Fn vm_page_xunbusy
 182 function exclusive unbusies
 183 .Fa m .
 184 Assertions on the busy state allow kernels compiled with
 185 .Cd "options INVARIANTS"
 186 and
 187 .Cd "options INVARIANT_SUPPORT"
 188 to panic if they are not respected.
 189 .Pp
 190 The
 191 .Fn vm_page_assert_sbusied
 192 function panics if
 193 .Fa m
 194 is not shared busied.
 195 .Pp
 196 The
 197 .Fn vm_page_assert_unbusied
 198 function panics if
 199 .Fa m
 200 is not unbusied.
 201 .Pp
 202 The
 203 .Fn vm_page_assert_xbusied
 204 function panics if
 205 .Fa m
 206 is not exclusive busied.
 207 .Sh SEE ALSO
 208 .Xr VOP_GETPAGES 9 ,
 209 .Xr vm_page_aflag 9 ,
 210 .Xr vm_page_alloc 9 ,
 211 .Xr vm_page_deactivate 9 ,
 212 .Xr vm_page_free 9 ,
 213 .Xr vm_page_grab 9 ,
 214 .Xr vm_page_insert 9 ,
 215 .Xr vm_page_lookup 9 ,
 216 .Xr vm_page_rename 9