diff options
| author | Jacob McDonnell <jacob@jacobmcdonnell.com> | 2026-04-25 19:59:05 -0400 |
|---|---|---|
| committer | Jacob McDonnell <jacob@jacobmcdonnell.com> | 2026-04-25 19:59:05 -0400 |
| commit | 1f19f33e45791ea59aed048796fc68672c6723a5 (patch) | |
| tree | 54625fba89e91d1c2177801ec635e8528bba937f /static/freebsd/man9/sleepqueue.9 4.html | |
| parent | ac5e55f5f2af5b92794c2aded46c6bae85b5f5ed (diff) | |
docs: Removed Precompiled HTML
Diffstat (limited to 'static/freebsd/man9/sleepqueue.9 4.html')
| -rw-r--r-- | static/freebsd/man9/sleepqueue.9 4.html | 326 |
1 files changed, 0 insertions, 326 deletions
diff --git a/static/freebsd/man9/sleepqueue.9 4.html b/static/freebsd/man9/sleepqueue.9 4.html deleted file mode 100644 index bb93c74b..00000000 --- a/static/freebsd/man9/sleepqueue.9 4.html +++ /dev/null @@ -1,326 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">SLEEPQUEUE(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">SLEEPQUEUE(9)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">init_sleepqueues</code>, - <code class="Nm">sleepq_abort</code>, <code class="Nm">sleepq_add</code>, - <code class="Nm">sleepq_alloc</code>, - <code class="Nm">sleepq_broadcast</code>, - <code class="Nm">sleepq_free</code>, <code class="Nm">sleepq_lock</code>, - <code class="Nm">sleepq_lookup</code>, - <code class="Nm">sleepq_release</code>, - <code class="Nm">sleepq_remove</code>, - <code class="Nm">sleepq_signal</code>, - <code class="Nm">sleepq_set_timeout</code>, - <code class="Nm">sleepq_set_timeout_sbt</code>, - <code class="Nm">sleepq_sleepcnt</code>, - <code class="Nm">sleepq_timedwait</code>, - <code class="Nm">sleepq_timedwait_sig</code>, - <code class="Nm">sleepq_type</code>, <code class="Nm">sleepq_wait</code>, - <code class="Nm">sleepq_wait_sig</code> — <span class="Nd">manage the - queues of sleeping threads</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">sys/param.h</a>></code> - <br/> - <code class="In">#include - <<a class="In">sys/sleepqueue.h</a>></code></p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">init_sleepqueues</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sleepq_abort</code>(<var class="Fa" style="white-space: nowrap;">struct - thread *td</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">sleepq_add</code>(<var class="Fa" style="white-space: nowrap;">const - void *wchan</var>, <var class="Fa" style="white-space: nowrap;">struct - lock_object *lock</var>, <var class="Fa" style="white-space: nowrap;">const - char *wmesg</var>, <var class="Fa" style="white-space: nowrap;">int - flags</var>, <var class="Fa" style="white-space: nowrap;">int - queue</var>);</p> -<p class="Pp"><var class="Ft">struct sleepqueue *</var> - <br/> - <code class="Fn">sleepq_alloc</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sleepq_broadcast</code>(<var class="Fa" style="white-space: nowrap;">const - void *wchan</var>, <var class="Fa" style="white-space: nowrap;">int - flags</var>, <var class="Fa" style="white-space: nowrap;">int pri</var>, - <var class="Fa" style="white-space: nowrap;">int queue</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">sleepq_free</code>(<var class="Fa" style="white-space: nowrap;">struct - sleepqueue *sq</var>);</p> -<p class="Pp"><var class="Ft">struct sleepqueue *</var> - <br/> - <code class="Fn">sleepq_lookup</code>(<var class="Fa" style="white-space: nowrap;">const - void *wchan</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">sleepq_lock</code>(<var class="Fa" style="white-space: nowrap;">const - void *wchan</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">sleepq_release</code>(<var class="Fa" style="white-space: nowrap;">const - void *wchan</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">sleepq_remove</code>(<var class="Fa" style="white-space: nowrap;">struct - thread *td</var>, <var class="Fa" style="white-space: nowrap;">const void - *wchan</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sleepq_signal</code>(<var class="Fa" style="white-space: nowrap;">const - void *wchan</var>, <var class="Fa" style="white-space: nowrap;">int - flags</var>, <var class="Fa" style="white-space: nowrap;">int pri</var>, - <var class="Fa" style="white-space: nowrap;">int queue</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">sleepq_set_timeout</code>(<var class="Fa" style="white-space: nowrap;">const - void *wchan</var>, <var class="Fa" style="white-space: nowrap;">int - timo</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">sleepq_set_timeout_sbt</code>(<var class="Fa" style="white-space: nowrap;">const - void *wchan</var>, <var class="Fa" style="white-space: nowrap;">sbintime_t - sbt</var>, <var class="Fa" style="white-space: nowrap;">sbintime_t pr</var>, - <var class="Fa" style="white-space: nowrap;">int flags</var>);</p> -<p class="Pp"><var class="Ft">u_int</var> - <br/> - <code class="Fn">sleepq_sleepcnt</code>(<var class="Fa" style="white-space: nowrap;">const - void *wchan</var>, <var class="Fa" style="white-space: nowrap;">int - queue</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sleepq_timedwait</code>(<var class="Fa" style="white-space: nowrap;">const - void *wchan</var>, <var class="Fa" style="white-space: nowrap;">int - pri</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sleepq_timedwait_sig</code>(<var class="Fa" style="white-space: nowrap;">const - void *wchan</var>, <var class="Fa" style="white-space: nowrap;">int - pri</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sleepq_type</code>(<var class="Fa" style="white-space: nowrap;">const - void *wchan</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">sleepq_wait</code>(<var class="Fa" style="white-space: nowrap;">const - void *wchan</var>, <var class="Fa" style="white-space: nowrap;">int - pri</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sleepq_wait_sig</code>(<var class="Fa" style="white-space: nowrap;">const - void *wchan</var>, <var class="Fa" style="white-space: nowrap;">int - pri</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">Sleep queues provide a mechanism for suspending execution of a - thread until some condition is met. Each queue is associated with a specific - wait channel when it is active, and only one queue may be associated with a - wait channel at any given point in time. The implementation of each wait - channel splits its sleepqueue into 2 sub-queues in order to enable some - optimizations on threads' wakeups. An active queue holds a list of threads - that are blocked on the associated wait channel. Threads that are not - blocked on a wait channel have an associated inactive sleep queue. When a - thread blocks on a wait channel it donates its inactive sleep queue to the - wait channel. When a thread is resumed, the wait channel that it was blocked - on gives it an inactive sleep queue for later use.</p> -<p class="Pp" id="sleepq_alloc">The - <a class="permalink" href="#sleepq_alloc"><code class="Fn">sleepq_alloc</code></a>() - function allocates an inactive sleep queue and is used to assign a sleep - queue to a thread during thread creation. The - <a class="permalink" href="#sleepq_free"><code class="Fn" id="sleepq_free">sleepq_free</code></a>() - function frees the resources associated with an inactive sleep queue and is - used to free a queue during thread destruction.</p> -<p class="Pp" id="init_sleepqueues">Active sleep queues are stored in a hash - table hashed on the addresses pointed to by wait channels. Each bucket in - the hash table contains a sleep queue chain. A sleep queue chain contains a - spin mutex and a list of sleep queues that hash to that specific chain. - Active sleep queues are protected by their chain's spin mutex. The - <a class="permalink" href="#init_sleepqueues"><code class="Fn">init_sleepqueues</code></a>() - function initializes the hash table of sleep queue chains.</p> -<p class="Pp" id="sleepq_lock">The - <a class="permalink" href="#sleepq_lock"><code class="Fn">sleepq_lock</code></a>() - function locks the sleep queue chain associated with wait channel - <var class="Fa">wchan</var>.</p> -<p class="Pp" id="sleepq_lookup">The - <a class="permalink" href="#sleepq_lookup"><code class="Fn">sleepq_lookup</code></a>() - returns a pointer to the currently active sleep queue for that wait channel - associated with <var class="Fa">wchan</var> or <code class="Dv">NULL</code> - if there is no active sleep queue associated with argument - <var class="Fa">wchan</var>. It requires the sleep queue chain associated - with <var class="Fa">wchan</var> to have been locked by a prior call to - <code class="Fn">sleepq_lock</code>().</p> -<p class="Pp" id="sleepq_release">The - <a class="permalink" href="#sleepq_release"><code class="Fn">sleepq_release</code></a>() - function unlocks the sleep queue chain associated with - <a class="permalink" href="#wchan"><code class="Fn" id="wchan">wchan</code></a>() - and is primarily useful when aborting a pending sleep request before one of - the wait functions is called.</p> -<p class="Pp" id="sleepq_add">The - <a class="permalink" href="#sleepq_add"><code class="Fn">sleepq_add</code></a>() - function places the current thread on the sleep queue associated with the - wait channel <var class="Fa">wchan</var>. The sleep queue chain associated - with argument <var class="Fa">wchan</var> must be locked by a prior call to - <code class="Fn">sleepq_lock</code>() when this function is called. If a - lock is specified via the <var class="Fa">lock</var> argument, and if the - kernel was compiled with <code class="Cd">options INVARIANTS</code>, then - the sleep queue code will perform extra checks to ensure that the lock is - used by all threads sleeping on <var class="Fa">wchan</var>. The - <var class="Fa">wmesg</var> parameter should be a short description of - <var class="Fa">wchan</var>. The <var class="Fa">flags</var> parameter is a - bitmask consisting of the type of sleep queue being slept on and zero or - more optional flags. The <var class="Fa">queue</var> parameter specifies the - sub-queue, in which the contending thread will be inserted.</p> -<p class="Pp">There are currently three types of sleep queues:</p> -<p class="Pp"></p> -<dl class="Bl-tag Bl-compact"> - <dt id="SLEEPQ_CONDVAR"><a class="permalink" href="#SLEEPQ_CONDVAR"><code class="Dv">SLEEPQ_CONDVAR</code></a></dt> - <dd>A sleep queue used to implement condition variables.</dd> - <dt id="SLEEPQ_SLEEP"><a class="permalink" href="#SLEEPQ_SLEEP"><code class="Dv">SLEEPQ_SLEEP</code></a></dt> - <dd>A sleep queue used to implement <a class="Xr">sleep(9)</a>, - <a class="Xr">wakeup(9)</a> and <a class="Xr">wakeup_one(9)</a>.</dd> - <dt id="SLEEPQ_PAUSE"><a class="permalink" href="#SLEEPQ_PAUSE"><code class="Dv">SLEEPQ_PAUSE</code></a></dt> - <dd>A sleep queue used to implement <a class="Xr">pause(9)</a>.</dd> -</dl> -<p class="Pp">There are currently two optional flag:</p> -<p class="Pp"></p> -<dl class="Bl-tag Bl-compact"> - <dt id="SLEEPQ_INTERRUPTIBLE"><a class="permalink" href="#SLEEPQ_INTERRUPTIBLE"><code class="Dv">SLEEPQ_INTERRUPTIBLE</code></a></dt> - <dd>The current thread is entering an interruptible sleep.</dd> -</dl> -<dl class="Bl-tag Bl-compact"> - <dt id="SLEEPQ_STOP_ON_BDRY"><a class="permalink" href="#SLEEPQ_STOP_ON_BDRY"><code class="Dv">SLEEPQ_STOP_ON_BDRY</code></a></dt> - <dd>When thread is entering an interruptible sleep, do not stop it upon - arrival of stop action, like <code class="Dv">SIGSTOP</code>. Wake it up - instead.</dd> -</dl> -<p class="Pp" id="sleepq_set_timeout">A timeout on the sleep may be specified by - calling - <a class="permalink" href="#sleepq_set_timeout"><code class="Fn">sleepq_set_timeout</code></a>() - after <code class="Fn">sleepq_add</code>(). The <var class="Fa">wchan</var> - parameter should be the same value from the preceding call to - <code class="Fn">sleepq_add</code>(), and the sleep queue chain associated - with <var class="Fa">wchan</var> must have been locked by a prior call to - <code class="Fn">sleepq_lock</code>(). The <var class="Fa">timo</var> - parameter should specify the timeout value in ticks.</p> -<p class="Pp" id="sleepq_set_timeout_sbt"><a class="permalink" href="#sleepq_set_timeout_sbt"><code class="Fn">sleepq_set_timeout_sbt</code></a>() - function takes <var class="Fa">sbt</var> argument instead of - <var class="Fa">timo</var>. It allows to specify relative or absolute wakeup - time with higher resolution in form of <var class="Vt">sbintime_t</var>. The - parameter <var class="Fa">pr</var> allows to specify wanted absolute event - precision. The parameter <var class="Fa">flags</var> allows to pass - additional - <a class="permalink" href="#callout_reset_sbt"><code class="Fn" id="callout_reset_sbt">callout_reset_sbt</code></a>() - flags.</p> -<p class="Pp" id="sleepq_wait">Once the thread is ready to suspend, one of the - wait functions is called to put the current thread to sleep until it is - awakened and to context switch to another thread. The - <a class="permalink" href="#sleepq_wait"><code class="Fn">sleepq_wait</code></a>() - function is used for non-interruptible sleeps that do not have a timeout. - The - <a class="permalink" href="#sleepq_timedwait"><code class="Fn" id="sleepq_timedwait">sleepq_timedwait</code></a>() - function is used for non-interruptible sleeps that have had a timeout set - via <code class="Fn">sleepq_set_timeout</code>(). The - <a class="permalink" href="#sleepq_wait_sig"><code class="Fn" id="sleepq_wait_sig">sleepq_wait_sig</code></a>() - function is used for interruptible sleeps that do not have a timeout. The - <a class="permalink" href="#sleepq_timedwait_sig"><code class="Fn" id="sleepq_timedwait_sig">sleepq_timedwait_sig</code></a>() - function is used for interruptible sleeps that do have a timeout set. The - <var class="Fa">wchan</var> argument to all of the wait functions is the - wait channel being slept on. The sleep queue chain associated with argument - <var class="Fa">wchan</var> needs to have been locked with a prior call to - <code class="Fn">sleepq_lock</code>(). The <var class="Fa">pri</var> - argument is used to set the priority of the thread when it is awakened. If - it is set to zero, the thread's priority is left alone.</p> -<p class="Pp">When the thread is resumed, the wait functions return a non-zero - value if the thread was awakened due to an interrupt other than a signal or - a timeout. If the sleep timed out, then <code class="Er">EWOULDBLOCK</code> - is returned. If the sleep was interrupted by something other than a signal, - then some other return value will be returned.</p> -<p class="Pp" id="sleepq_broadcast">A sleeping thread is normally resumed by the - <a class="permalink" href="#sleepq_broadcast"><code class="Fn">sleepq_broadcast</code></a>() - and - <a class="permalink" href="#sleepq_signal"><code class="Fn" id="sleepq_signal">sleepq_signal</code></a>() - functions. The <code class="Fn">sleepq_signal</code>() function awakens the - highest priority thread sleeping on a wait channel (if SLEEPQ_UNFAIR flag is - set, thread that went to sleep recently) while - <code class="Fn">sleepq_broadcast</code>() awakens all of the threads - sleeping on a wait channel. The <var class="Fa">wchan</var> argument - specifics which wait channel to awaken. The <var class="Fa">flags</var> - argument must match the sleep queue type contained in the - <var class="Fa">flags</var> argument passed to - <code class="Fn">sleepq_add</code>() by the threads sleeping on the wait - channel. If the <var class="Fa">pri</var> argument does not equal -1, then - each thread that is awakened will have its priority raised to - <var class="Fa">pri</var> if it has a lower priority. The sleep queue chain - associated with argument <var class="Fa">wchan</var> must be locked by a - prior call to <code class="Fn">sleepq_lock</code>() before calling any of - these functions. The <var class="Fa">queue</var> argument specifies the - sub-queue, from which threads need to be woken up.</p> -<p class="Pp" id="sleepq_abort">A thread in an interruptible sleep can be - interrupted by another thread via the - <a class="permalink" href="#sleepq_abort"><code class="Fn">sleepq_abort</code></a>() - function. The <var class="Fa">td</var> argument specifies the thread to - interrupt. An individual thread can also be awakened from sleeping on a - specific wait channel via the - <a class="permalink" href="#sleepq_remove"><code class="Fn" id="sleepq_remove">sleepq_remove</code></a>() - function. The <var class="Fa">td</var> argument specifies the thread to - awaken and the <var class="Fa">wchan</var> argument specifies the wait - channel to awaken it from. If the thread <var class="Fa">td</var> is not - blocked on the wait channel <var class="Fa">wchan</var> then this function - will not do anything, even if the thread is asleep on a different wait - channel. This function should only be used if one of the other functions - above is not sufficient. One possible use is waking up a specific thread - from a widely shared sleep channel.</p> -<p class="Pp" id="sleepq_sleepcnt">The - <a class="permalink" href="#sleepq_sleepcnt"><code class="Fn">sleepq_sleepcnt</code></a>() - function offer a simple way to retrieve the number of threads sleeping for - the specified <var class="Fa">queue</var>, given a - <var class="Fa">wchan</var>.</p> -<p class="Pp" id="sleepq_type">The - <a class="permalink" href="#sleepq_type"><code class="Fn">sleepq_type</code></a>() - function returns the type of <var class="Fa">wchan</var> associated to a - sleepqueue.</p> -<p class="Pp" id="sleepq_abort~2">The - <a class="permalink" href="#sleepq_abort~2"><code class="Fn">sleepq_abort</code></a>(), - <code class="Fn">sleepq_broadcast</code>(), and - <code class="Fn">sleepq_signal</code>() functions all return a boolean - value. If the return value is true, then at least one thread was resumed - that is currently swapped out. The caller is responsible for awakening the - scheduler process so that the resumed thread will be swapped back in. This - is done by calling the - <a class="permalink" href="#kick_proc0"><code class="Fn" id="kick_proc0">kick_proc0</code></a>() - function after releasing the sleep queue chain lock via a call to - <code class="Fn">sleepq_release</code>().</p> -<p class="Pp">The sleep queue interface is currently used to implement the - <a class="Xr">sleep(9)</a> and <a class="Xr">condvar(9)</a> interfaces. - Almost all other code in the kernel should use one of those interfaces - rather than manipulating sleep queues directly.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">callout(9)</a>, <a class="Xr">condvar(9)</a>, - <a class="Xr">runqueue(9)</a>, <a class="Xr">scheduler(9)</a>, - <a class="Xr">sleep(9)</a></p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">June 19, 2019</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |
