share/man/man9/sleepqueue.9

   1 .\" Copyright (c) 2000-2004 John H. Baldwin <jhb@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 DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  14 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  15 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  16 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  17 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  18 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  19 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  20 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  21 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  22 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  23 .\"
  24 .\" $FreeBSD$
  25 .\"
  26 .Dd January 18, 2010
  27 .Dt SLEEPQUEUE 9
  28 .Os
  29 .Sh NAME
  30 .Nm init_sleepqueues ,
  31 .Nm sleepq_abort ,
  32 .Nm sleepq_add ,
  33 .Nm sleepq_alloc ,
  34 .Nm sleepq_broadcast ,
  35 .Nm sleepq_calc_signal_retval ,
  36 .Nm sleepq_catch_signals ,
  37 .Nm sleepq_free ,
  38 .Nm sleepq_lock ,
  39 .Nm sleepq_lookup ,
  40 .Nm sleepq_release ,
  41 .Nm sleepq_remove ,
  42 .Nm sleepq_signal ,
  43 .Nm sleepq_set_timeout ,
  44 .Nm sleepq_sleepcnt ,
  45 .Nm sleepq_timedwait ,
  46 .Nm sleepq_timedwait_sig ,
  47 .Nm sleepq_wait ,
  48 .Nm sleepq_wait_sig
  49 .Nd manage the queues of sleeping threads
  50 .Sh SYNOPSIS
  51 .In sys/param.h
  52 .In sys/sleepqueue.h
  53 .Ft void
  54 .Fn init_sleepqueues "void"
  55 .Ft int
  56 .Fn sleepq_abort "struct thread *td"
  57 .Ft void
  58 .Fn sleepq_add "void *wchan" "struct lock_object *lock" "const char *wmesg" "int flags" "int queue"
  59 .Ft struct sleepqueue *
  60 .Fn sleepq_alloc "void"
  61 .Ft int
  62 .Fn sleepq_broadcast "void *wchan" "int flags" "int pri" "int queue"
  63 .Ft int
  64 .Fn sleepq_calc_signal_retval "int sig"
  65 .Ft int
  66 .Fn sleepq_catch_signals "void *wchan"
  67 .Ft void
  68 .Fn sleepq_free "struct sleepqueue *sq"
  69 .Ft struct sleepqueue *
  70 .Fn sleepq_lookup "void *wchan"
  71 .Ft void
  72 .Fn sleepq_lock "void *wchan"
  73 .Ft void
  74 .Fn sleepq_release "void *wchan"
  75 .Ft void
  76 .Fn sleepq_remove "struct thread *td" "void *wchan"
  77 .Ft int
  78 .Fn sleepq_signal "void *wchan" "int flags" "int pri" "int queue"
  79 .Ft void
  80 .Fn sleepq_set_timeout "void *wchan" "int timo"
  81 .Ft u_int
  82 .Fn sleepq_sleepcnt "void *wchan" "int queue"
  83 .Ft int
  84 .Fn sleepq_timedwait "void *wchan"
  85 .Ft int
  86 .Fn sleepq_timedwait_sig "void *wchan" "int signal_caught"
  87 .Ft void
  88 .Fn sleepq_wait "void *wchan"
  89 .Ft int
  90 .Fn sleepq_wait_sig "void *wchan"
  91 .Sh DESCRIPTION
  92 Sleep queues provide a mechanism for suspending execution of a thread until
  93 some condition is met.
  94 Each queue is associated with a specific wait channel when it is active,
  95 and only one queue may be associated with a wait channel at any given point
  96 in time.
  97 The implementation of each wait channel splits its sleepqueue into 2 sub-queues
  98 in order to enable some optimizations on threads' wakeups.
  99 An active queue holds a list of threads that are blocked on the associated
 100 wait channel.
 101 Threads that are not blocked on a wait channel have an associated inactive
 102 sleep queue.
 103 When a thread blocks on a wait channel it donates its inactive sleep queue
 104 to the wait channel.
 105 When a thread is resumed,
 106 the wait channel that it was blocked on gives it an inactive sleep queue for
 107 later use.
 108 .Pp
 109 The
 110 .Fn sleepq_alloc
 111 function allocates an inactive sleep queue and is used to assign a
 112 sleep queue to a thread during thread creation.
 113 The
 114 .Fn sleepq_free
 115 function frees the resources associated with an inactive sleep queue and is
 116 used to free a queue during thread destruction.
 117 .Pp
 118 Active sleep queues are stored in a hash table hashed on the addresses pointed
 119 to by wait channels.
 120 Each bucket in the hash table contains a sleep queue chain.
 121 A sleep queue chain contains a spin mutex and a list of sleep queues that hash
 122 to that specific chain.
 123 Active sleep queues are protected by their chain's spin mutex.
 124 The
 125 .Fn init_sleepqueues
 126 function initializes the hash table of sleep queue chains.
 127 .Pp
 128 The
 129 .Fn sleepq_lock
 130 function locks the sleep queue chain associated with wait channel
 131 .Fa wchan .
 132 .Pp
 133 The
 134 .Fn sleepq_lookup
 135 returns a pointer to the currently active sleep queue for that wait
 136 channel associated with
 137 .Fa wchan
 138 or
 139 .Dv NULL
 140 if there is no active sleep queue associated with
 141 argument
 142 .Fa wchan .
 143 It requires the sleep queue chain associated with
 144 .Fa wchan
 145 to have been locked by a prior call to
 146 .Fn sleepq_lock .
 147 .Pp
 148 The
 149 .Fn sleepq_release
 150 function unlocks the sleep queue chain associated with
 151 .Fn wchan
 152 and is primarily useful when aborting a pending sleep request before one of
 153 the wait functions is called.
 154 .Pp
 155 The
 156 .Fn sleepq_add
 157 function places the current thread on the sleep queue associated with the
 158 wait channel
 159 .Fa wchan .
 160 The sleep queue chain associated with argument
 161 .Fa wchan
 162 must be locked by a prior call to
 163 .Fn sleepq_lock
 164 when this function is called.
 165 If a lock is specified via the
 166 .Fa lock
 167 argument, and if the kernel was compiled with
 168 .Cd "options INVARIANTS" ,
 169 then the sleep queue code will perform extra checks to ensure that
 170 the lock is used by all threads sleeping on
 171 .Fa wchan .
 172 The
 173 .Fa wmesg
 174 parameter should be a short description of
 175 .Fa wchan .
 176 The
 177 .Fa flags
 178 parameter is a bitmask consisting of the type of sleep queue being slept on
 179 and zero or more optional flags.
 180 The
 181 .Fa queue
 182 parameter specifies the sub-queue, in which the contending thread will be
 183 inserted.
 184 .Pp
 185 There are currently three types of sleep queues:
 186 .Pp
 187 .Bl -tag -width ".Dv SLEEPQ_CONDVAR" -compact
 188 .It Dv SLEEPQ_CONDVAR
 189 A sleep queue used to implement condition variables.
 190 .It Dv SLEEPQ_SLEEP
 191 A sleep queue used to implement
 192 .Xr sleep 9 ,
 193 .Xr wakeup 9
 194 and
 195 .Xr wakeup_one 9 .
 196 .It Dv SLEEPQ_PAUSE
 197 A sleep queue used to implement
 198 .Xr pause 9 .
 199 .El
 200 .Pp
 201 There are currently two optional flag:
 202 .Pp
 203 .Bl -tag -width ".Dv SLEEPQ_INTERRUPTIBLE" -compact
 204 .It Dv SLEEPQ_INTERRUPTIBLE
 205 The current thread is entering an interruptible sleep.
 206 .El
 207 .Bl -tag -width ".Dv SLEEPQ_STOP_ON_BDRY" -compact
 208 .It Dv SLEEPQ_STOP_ON_BDRY
 209 When thread is entering an interruptible sleep, do not stop it upon
 210 arrival of stop action, like
 211 .Dv SIGSTOP .
 212 Wake it up instead.
 213 .El
 214 .Pp
 215 A timeout on the sleep may be specified by calling
 216 .Fn sleepq_set_timeout
 217 after
 218 .Fn sleepq_add .
 219 The
 220 .Fa wchan
 221 parameter should be the same value from the preceding call to
 222 .Fn sleepq_add ,
 223 and the sleep queue chain associated with
 224 .Fa wchan
 225 must have been locked by a prior call to
 226 .Fn sleepq_lock .
 227 The
 228 .Fa timo
 229 parameter should specify the timeout value in ticks.
 230 .Pp
 231 The current thread may be marked interruptible by calling
 232 .Fn sleepq_catch_signals
 233 with
 234 .Fa wchan
 235 set to the wait channel.
 236 This function returns a signal number if there are any pending signals for
 237 the current thread and 0 if there is not a pending signal.
 238 The sleep queue chain associated with argument
 239 .Fa wchan
 240 should have been locked by a prior call to
 241 .Fn sleepq_lock .
 242 .Pp
 243 Once the thread is ready to suspend,
 244 one of the wait functions is called to put the current thread to sleep
 245 until it is awakened and to context switch to another thread.
 246 The
 247 .Fn sleepq_wait
 248 function is used for non-interruptible sleeps that do not have a timeout.
 249 The
 250 .Fn sleepq_timedwait
 251 function is used for non-interruptible sleeps that have had a timeout set via
 252 .Fn sleepq_set_timeout .
 253 The
 254 .Fn sleepq_wait_sig
 255 function is used for interruptible sleeps that do not have a timeout.
 256 The
 257 .Fn sleepq_timedwait_sig
 258 function is used for interruptible sleeps that do have a timeout set.
 259 The
 260 .Fa wchan
 261 argument to all of the wait functions is the wait channel being slept
 262 on.
 263 The sleep queue chain associated with argument
 264 .Fa wchan
 265 needs to have been locked with a prior call to
 266 .Fn sleepq_lock .
 267 The
 268 .Fa signal_caught
 269 parameter to
 270 .Fn sleepq_timedwait_sig
 271 specifies if a previous call to
 272 .Fn sleepq_catch_signals
 273 found a pending signal.
 274 .Pp
 275 When the thread is resumed,
 276 the wait functions return a non-zero value if the thread was awakened due to
 277 an interrupt other than a signal or a timeout.
 278 If the sleep timed out, then
 279 .Er EWOULDBLOCK
 280 is returned.
 281 If the sleep was interrupted by something other than a signal,
 282 then some other return value will be returned.
 283 If zero is returned after resuming from an interruptible sleep,
 284 then
 285 .Fn sleepq_calc_signal_retval
 286 should be called to determine if the sleep was interrupted by a signal.
 287 If so,
 288 .Fn sleepq_calc_signal_retval
 289 returns
 290 .Er ERESTART
 291 if the interrupting signal is restartable and
 292 .Er EINTR
 293 otherwise.
 294 If the sleep was not interrupted by a signal,
 295 .Fn sleepq_calc_signal_retval
 296 will return 0.
 297 .Pp
 298 A sleeping thread is normally resumed by the
 299 .Fn sleepq_broadcast
 300 and
 301 .Fn sleepq_signal
 302 functions.
 303 The
 304 .Fn sleepq_signal
 305 function awakens the highest priority thread sleeping on a wait channel while
 306 .Fn sleepq_broadcast
 307 awakens all of the threads sleeping on a wait channel.
 308 The
 309 .Fa wchan
 310 argument specifics which wait channel to awaken.
 311 The
 312 .Fa flags
 313 argument must match the sleep queue type contained in the
 314 .Fa flags
 315 argument passed to
 316 .Fn sleepq_add
 317 by the threads sleeping on the wait channel.
 318 If the
 319 .Fa pri
 320 argument does not equal \-1,
 321 then each thread that is awakened will have its priority raised to
 322 .Fa pri
 323 if it has a lower priority.
 324 The sleep queue chain associated with argument
 325 .Fa wchan
 326 must be locked by a prior call to
 327 .Fn sleepq_lock
 328 before calling any of these functions.
 329 The
 330 .Fa queue
 331 argument specifies the sub-queue, from which threads need to be woken up.
 332 .Pp
 333 A thread in an interruptible sleep can be interrupted by another thread via
 334 the
 335 .Fn sleepq_abort
 336 function.
 337 The
 338 .Fa td
 339 argument specifies the thread to interrupt.
 340 An individual thread can also be awakened from sleeping on a specific wait
 341 channel via the
 342 .Fn sleepq_remove
 343 function.
 344 The
 345 .Fa td
 346 argument specifies the thread to awaken and the
 347 .Fa wchan
 348 argument specifies the wait channel to awaken it from.
 349 If the thread
 350 .Fa td
 351 is not blocked on the the wait channel
 352 .Fa wchan
 353 then this function will not do anything,
 354 even if the thread is asleep on a different wait channel.
 355 This function should only be used if one of the other functions above is not
 356 sufficient.
 357 One possible use is waking up a specific thread from a widely shared sleep
 358 channel.
 359 .Pp
 360 The
 361 .Fn sleepq_sleepcnt
 362 function offer a simple way to retrieve the number of threads sleeping for
 363 the specified
 364 .Fa queue ,
 365 given a
 366 .Fa wchan .
 367 .Pp
 368 The
 369 .Fn sleepq_abort ,
 370 .Fn sleepq_broadcast ,
 371 and
 372 .Fn sleepq_signal
 373 functions all return a boolean value.
 374 If the return value is true,
 375 then at least one thread was resumed that is currently swapped out.
 376 The caller is responsible for awakening the scheduler process so that the
 377 resumed thread will be swapped back in.
 378 This is done by calling the
 379 .Fn kick_proc0
 380 function after releasing the sleep queue chain lock via a call to
 381 .Fn sleepq_release .
 382 .Pp
 383 The sleep queue interface is currently used to implement the
 384 .Xr sleep 9
 385 and
 386 .Xr condvar 9
 387 interfaces.
 388 Almost all other code in the kernel should use one of those interfaces rather
 389 than manipulating sleep queues directly.
 390 .Sh SEE ALSO
 391 .Xr condvar 9 ,
 392 .Xr runqueue 9 ,
 393 .Xr scheduler 9 ,
 394 .Xr sleep 9