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 March 10, 2004 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_lookup , 39.Nm sleepq_release , 40.Nm sleepq_remove , 41.Nm sleepq_signal , 42.Nm sleepq_set_timeout , 43.Nm sleepq_timedwait , 44.Nm sleepq_timedwait_sig , 45.Nm sleepq_wait , 46.Nm sleepq_wait_sig 47.Nd manage the queues of sleeping threads 48.Sh SYNOPSIS 49.In sys/param.h 50.In sys/sleepqueue.h 51.Ft void 52.Fn init_sleepqueues "void" 53.Ft void 54.Fn sleepq_abort "struct thread *td" 55.Ft void 56.Fn sleepq_add "struct sleepqueue *sq" "void *wchan" "struct mtx *lock" "const char *wmesg" "int flags" 57.Ft struct sleepqueue * 58.Fn sleepq_alloc "void" 59.Ft void 60.Fn sleepq_broadcast "void *wchan" "int flags" "int pri" 61.Ft int 62.Fn sleepq_calc_signal_retval "int sig" 63.Ft int 64.Fn sleepq_catch_signals "void *wchan" 65.Ft void 66.Fn sleepq_free "struct sleepqueue *sq" 67.Ft struct sleepqueue * 68.Fn sleepq_lookup "void *wchan" 69.Ft void 70.Fn sleepq_release "void *wchan" 71.Ft void 72.Fn sleepq_remove "struct thread *td" "void *wchan" 73.Ft void 74.Fn sleepq_signal "void *wchan" "int flags" "int pri" 75.Ft void 76.Fn sleepq_set_timeout "void *wchan" "int timo" 77.Ft int 78.Fn sleepq_timedwait "void *wchan" "int signal_caught" 79.Ft int 80.Fn sleepq_timedwait_sig "void *wchan" "int signal_caught" 81.Ft void 82.Fn sleepq_wait "void *wchan" 83.Ft int 84.Fn sleepq_wait_sig "void *wchan" 85.Sh DESCRIPTION 86Sleep queues provide a mechanism for suspending execution of a thread until 87some condition is met. 88Each queue is associated with a specific wait channel when it is active, 89and only one queue may be associated with a wait channel at any given point 90in time. 91An active queue holds a list of threads that are blocked on the associated 92wait channel. 93Threads that are not blocked on a wait channel have an associated inactive 94sleep queue. 95When a thread blocks on a wait channel it donates its inactive sleep queue 96to the wait channel. 97When a thread is resumed, 98the wait channel that it was blocked on gives it an inactive sleep queue for 99later use. 100The 101.Fn sleepq_alloc 102allocates an inactive sleep queue and is used to assign a sleep queue to a 103thread during thread creation. 104The 105.Fn sleepq_free 106function frees the resources associated with an inactive sleep queue and is 107used to free a queue during thread destruction. 108.Pp 109Active sleep queues are stored in a hash table hashed on the addresses pointed 110to by wait channels. 111Each bucket in the hash table contains a sleep queue chain. 112A sleep queue chain contains a spin mutex and a list of sleep queues that hash 113to that specific chain. 114Active sleep queues are protected by their chain's spin mutex. 115The 116.Fn init_sleepqueues 117function initializes the hash table of sleep queue chains. 118.Pp 119The 120.Fn sleepq_lookup 121function locks the sleep queue chain associated with 122.Fa wchan 123and returns a pointer to the current active sleep queue for that wait channel 124or 125.Dv NULL 126if there currently is not an active sleep queue. 127The 128.Fn sleepq_release 129function unlocks the sleep queue chain associated with 130.Fn wchan 131and is primarily useful when aborting a pending sleep request before one of 132the wait functions is called. 133.Pp 134The 135.Fn sleepq_add 136function places the current thread on the sleep queue associated with the 137wait channel 138.Fa wchan . 139The associated sleep queue chain must be locked by a call to 140.Fn sleepq_lookup 141when this function is called and its return value should be passed as the 142.Fa sq 143parameter. 144If a mutex is specified via the 145.Fa lock 146argument, then the sleep queue code will perform extra checks to ensure that 147the mutex is held for all threads sleeping on 148.Fa wchan . 149The 150.Fa wmesg 151parameter should be a short description of 152.Fa wchan . 153The 154.Fa flags 155parameter currently only specifies the type of sleep queue being slept on. 156A value of 1570 158indicates a sleep queue used by 159.Xr msleep 9 160and a value of 161.Dv SLEEPQ_CONDVAR 162indicates a sleep queue used by 163.Xr condvar 9 . 164A timeout on the sleep may be specified by calling 165.Fn sleepq_set_timeout 166after 167.Fn sleepq_add . 168The 169.Fa wchan 170parameter should be the same value from the preceding call to 171.Fn sleepq_add . 172The 173.Fa timo 174parameter should specify the timeout value in ticks. 175The thread may be marked interruptible by calling 176.Fn sleepq_catch_signals 177with 178.Fa wchan 179set to the wait channel. 180The function returns a signal number if there are any pending signals for 181the current thread and 0 if there is not a pending signal. 182.Pp 183Once the thread is ready to suspend, 184one of the wait functions is called to put the thread to sleep until it is 185awakened and context switch to another thread. 186The 187.Fn sleepq_wait 188function is used for non-interruptible sleeps that do not have a timeout. 189The 190.Fn sleepq_timedwait 191function is used for non-interruptible sleeps that have had a timeout set via 192.Fn sleepq_set_timeout . 193The 194.Fn sleepq_wait_sig 195function is used for interruptible sleeps that do not have a timeout. 196The 197.Fn sleepq_timedwait_sig 198function is used for interruptible sleeps that do have a timeout set. 199The 200.Fa wchan 201argument to all of the wait functions is the wait channel being slept on. 202The 203.Fa signal_caught 204parameter to the timed wait functions specifies if a previous call to 205.Fn sleepq_catch_signals 206found a pending signal. 207.Pp 208When the thread is resumed, 209the wait functions return a non-zero value if the thread was awakened due to 210an interrupt other than a signal or a timeout. 211If the sleep timed out, then 212.Er EWOULDBLOCK 213is returned. 214If the sleep was interrupted by something other than a signal, 215then some other return value will be returned. 216If zero is returned after resuming from an interruptible sleep, 217then 218.Fn sleepq_calc_signal_retval 219should be called to determine if the sleep was interrupted by a signal. 220If so, 221.Fn sleepq_calc_signal_retval 222returns 223.Er ERESTART 224if the interrupting signal is restartable and 225.Er EINTR 226otherwise. 227If the sleep was not interrupted by a signal, 228.Fn sleepq_calc_signal_retval 229will return 0. 230.Pp 231A sleeping thread is normally resumed by the 232.Fn sleepq_broadcast 233and 234.Fn sleepq_signal 235functions. 236The 237.Fn sleepq_signal 238function awakens the highest priority thread sleeping on a wait channel while 239.Fn sleepq_broadcast 240awakens all of the threads sleeping on a wait channel. 241The 242.Fa wchan 243argument specifics which wait channel to awaken. 244The 245.Fa flags 246argument should match the 247.Fa flags 248argument passed to 249.Fn sleepq_add 250by the threads sleeping on the wait channel. 251If the 252.Fa pri 253argument does not equal \-1, 254then each thread that is awakened will have its priority raised to 255.Fa pri 256if it has a lower priority. 257.Pp 258A thread in an interruptible sleep can be interrupted by another thread via 259the 260.Fn sleepq_abort 261function. 262The 263.Fa td 264argument specifies the thread to interrupt. 265An individual thread can also be awakened from sleeping on a specific wait 266channel via the 267.Fn sleepq_remove 268function. 269The 270.Fa td 271argument specifies the thread to awaken and the 272.Fa wchan 273argument specifies the wait channel to awaken it from. 274If the thread 275.Fa td 276is not blocked on the the wait channel 277.Fa wchan 278then this function will not do anything, 279even if the thread is asleep on a different wait channel. 280This function should only be used if one of the other functions above is not 281sufficient. 282One possible use is waking up a specific thread from a widely shared sleep 283channel. 284.Pp 285The sleep queue interface is currently used to implement the 286.Xr msleep 9 287and 288.Xr condvar 9 289interfaces. 290Almost all other code in the kernel should use one of those interfaces rather 291than manipulating sleep queues directly. 292.Sh SEE ALSO 293.Xr condvar 9 , 294.Xr msleep 9 , 295.Xr runqueue 9 , 296.Xr scheduler 9 297