1.\" Copyright (c) 2000-2001 John H. Baldwin <jhb@FreeBSD.org> 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 13.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 14.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 15.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 16.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 17.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 18.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 19.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 20.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 21.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 22.\" 23.Dd August 15, 2010 24.Dt RUNQUEUE 9 25.Os 26.Sh NAME 27.Nm choosethread , 28.Nm procrunnable , 29.Nm remrunqueue , 30.Nm setrunqueue 31.Nd manage the queue of runnable processes 32.Sh SYNOPSIS 33.In sys/param.h 34.In sys/proc.h 35.Vt "extern struct rq itqueues[]" ; 36.Vt "extern struct rq rtqueues[]" ; 37.Vt "extern struct rq queues[]" ; 38.Vt "extern struct rq idqueues[]" ; 39.Ft struct thread * 40.Fn choosethread "void" 41.Ft int 42.Fn procrunnable "void" 43.Ft void 44.Fn remrunqueue "struct thread *td" 45.Ft void 46.Fn setrunqueue "struct thread *td" 47.Sh DESCRIPTION 48The run queue consists of four priority queues: 49.Va itqueues 50for interrupt threads, 51.Va rtqueues 52for realtime priority processes, 53.Va queues 54for time sharing processes, and 55.Va idqueues 56for idle priority processes. 57Each priority queue consists of an array of 58.Dv NQS 59queue header structures. 60Each queue header identifies a list of runnable processes of equal priority. 61Each queue also has a single word that contains a bit mask identifying 62non-empty queues to assist in selecting a process quickly. 63These are named 64.Va itqueuebits , 65.Va rtqueuebits , 66.Va queuebits , 67and 68.Va idqueuebits . 69The run queues are protected by the 70.Va sched_lock 71mutex. 72.Pp 73.Fn procrunnable 74returns zero if there are no runnable processes other than the idle process. 75If there is at least one runnable process other than the idle process, it 76will return a non-zero value. 77Note that the 78.Va sched_lock 79mutex does 80.Em not 81need to be held when this function is called. 82There is a small race window where one CPU may place a process on the run queue 83when there are currently no other runnable processes while another CPU is 84calling this function. 85In that case the second CPU will simply travel through the idle loop one 86additional time before noticing that there is a runnable process. 87This works because idle CPUs are not halted in SMP systems. 88If idle CPUs are halted in SMP systems, then this race condition might have 89more serious repercussions in the losing case, and 90.Fn procrunnable 91may have to require that the 92.Va sched_lock 93mutex be acquired. 94.Pp 95.Fn choosethread 96returns the highest priority runnable thread. 97If there are no runnable threads, then the idle thread is returned. 98This function is called by 99.Fn cpu_switch 100and 101.Fn cpu_throw 102to determine which thread to switch to. 103.Fn choosethread 104must be called with the 105.Va sched_lock 106mutex held. 107.Pp 108.Fn setrunqueue 109adds the thread 110.Fa td 111to the tail of the appropriate queue in the proper priority queue. 112The thread must be runnable, i.e.\& 113.Va p_stat 114must be set to 115.Dv SRUN . 116This function must be called with the 117.Va sched_lock 118mutex held. 119.Pp 120.Fn remrunqueue 121removes thread 122.Fa td 123from its run queue. 124If 125.Fa td 126is not on a run queue, then the kernel will 127.Xr panic 9 . 128This function must be called with the 129.Va sched_lock 130mutex held. 131.Sh SEE ALSO 132.Xr cpu_switch 9 , 133.Xr scheduler 9 , 134.Xr sleepqueue 9 135