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