summaryrefslogtreecommitdiff
path: root/static/freebsd/man9/sleepqueue.9 4.html
diff options
context:
space:
mode:
authorJacob McDonnell <jacob@jacobmcdonnell.com>2026-04-25 19:59:05 -0400
committerJacob McDonnell <jacob@jacobmcdonnell.com>2026-04-25 19:59:05 -0400
commit1f19f33e45791ea59aed048796fc68672c6723a5 (patch)
tree54625fba89e91d1c2177801ec635e8528bba937f /static/freebsd/man9/sleepqueue.9 4.html
parentac5e55f5f2af5b92794c2aded46c6bae85b5f5ed (diff)
docs: Removed Precompiled HTML
Diffstat (limited to 'static/freebsd/man9/sleepqueue.9 4.html')
-rw-r--r--static/freebsd/man9/sleepqueue.9 4.html326
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> &#x2014; <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
- &lt;<a class="In">sys/param.h</a>&gt;</code>
- <br/>
- <code class="In">#include
- &lt;<a class="In">sys/sleepqueue.h</a>&gt;</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>