diff options
Diffstat (limited to 'static/netbsd/man9/ltsleep.9 3.html')
| -rw-r--r-- | static/netbsd/man9/ltsleep.9 3.html | 203 |
1 files changed, 0 insertions, 203 deletions
diff --git a/static/netbsd/man9/ltsleep.9 3.html b/static/netbsd/man9/ltsleep.9 3.html deleted file mode 100644 index 852103ea..00000000 --- a/static/netbsd/man9/ltsleep.9 3.html +++ /dev/null @@ -1,203 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">LTSLEEP(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">LTSLEEP(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">ltsleep</code>, <code class="Nm">mtsleep</code>, - <code class="Nm">tsleep</code>, <code class="Nm">wakeup</code> — - <span class="Nd">process context sleep and wakeup</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/proc.h</a>></code></p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">mtsleep</code>(<var class="Fa" style="white-space: nowrap;">wchan_t - ident</var>, <var class="Fa" style="white-space: nowrap;">pri_t - priority</var>, <var class="Fa" style="white-space: nowrap;">const char - *wmesg</var>, <var class="Fa" style="white-space: nowrap;">int timo</var>, - <var class="Fa" style="white-space: nowrap;">kmutex_t *mtx</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">tsleep</code>(<var class="Fa" style="white-space: nowrap;">wchan_t - ident</var>, <var class="Fa" style="white-space: nowrap;">pri_t - priority</var>, <var class="Fa" style="white-space: nowrap;">const char - *wmesg</var>, <var class="Fa" style="white-space: nowrap;">int - timo</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">wakeup</code>(<var class="Fa" style="white-space: nowrap;">wchan_t - ident</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp"><i class="Em">The interfaces described in this manual page are - obsolete</i> <i class="Em">and will be removed from a future version of the - system.</i></p> -<p class="Pp" id="ltsleep"><i class="Em">The</i> - <a class="permalink" href="#ltsleep"><code class="Fn">ltsleep</code></a>() - <a class="permalink" href="#interface"><i class="Em" id="interface">interface - has been obsoleted and removed from the system.</i></a></p> -<p class="Pp" id="Please"><a class="permalink" href="#Please"><i class="Em">Please - see the</i></a> <a class="Xr">condvar(9)</a>, <a class="Xr">mutex(9)</a>, - <i class="Em">and</i> <a class="Xr">rwlock(9)</a> - <a class="permalink" href="#manual"><i class="Em" id="manual">manual pages - for information on kernel synchronisation primitives.</i></a></p> -<p class="Pp" id="tsleep">These functions implement voluntary context switching. - <a class="permalink" href="#tsleep"><code class="Fn">tsleep</code></a>() and - <code class="Fn">mtsleep</code>() are used throughout the kernel whenever - processing in the current context can not continue for any of the following - reasons:</p> -<ul class="Bl-bullet Bd-indent"> - <li>The current process needs to await the results of a pending I/O - operation.</li> - <li>The current process needs resources (e.g., memory) which are temporarily - unavailable.</li> -</ul> -<p class="Pp" id="wakeup">The function - <a class="permalink" href="#wakeup"><code class="Fn">wakeup</code></a>() is - used to notify sleeping processes of possible changes to the condition that - caused them to go to sleep. Typically, an awakened process will — - after it has acquired a context again — retry the action that blocked - its operation to see if the “blocking” condition has - cleared.</p> -<p class="Pp" id="tsleep~2">The - <a class="permalink" href="#tsleep~2"><code class="Fn">tsleep</code></a>() - and <code class="Fn">mtsleep</code>() functions take the following - arguments:</p> -<dl class="Bl-tag"> - <dt><var class="Fa">ident</var></dt> - <dd>An identifier of the “wait channel” representing the - resource for which the current process needs to wait. This typically is - the virtual address of some kernel data-structure related to the resource - for which the process is contending. The same identifier must be used in a - call to <code class="Fn">wakeup</code>() to get the process going again. - <var class="Fa">ident</var> should not be - <code class="Dv">NULL</code>.</dd> - <dt><var class="Fa">priority</var></dt> - <dd>The process priority to be used when the process is awakened and put on - the queue of runnable processes. This mechanism is used to optimize - “throughput” of processes executing in kernel mode. If the - flag <code class="Dv">PCATCH</code> is OR'ed into - <var class="Fa">priority</var> the process checks for posted signals - before and after sleeping.</dd> - <dt><var class="Fa">wmesg</var></dt> - <dd>A pointer to a character string indicating the reason a process is - sleeping. The kernel does not use the string, but makes it available - (through the process structure field <code class="Li">p_wmesg</code>) for - user level utilities such as <a class="Xr">ps(1)</a>.</dd> - <dt><var class="Fa">timo</var></dt> - <dd>If non-zero, the process will sleep for at most - <code class="Li">timo/hz</code> seconds. If this amount of time elapses - and no <code class="Fn">wakeup</code>(<var class="Fa">ident</var>) has - occurred, and no signal (if <code class="Dv">PCATCH</code> - <span class="No">was set</span>) was posted, - <code class="Fn">tsleep</code>() will return - <code class="Er">EWOULDBLOCK</code>.</dd> -</dl> -<p class="Pp" id="mtsleep">The - <a class="permalink" href="#mtsleep"><code class="Fn">mtsleep</code></a>() - function takes an additional argument and flag:</p> -<dl class="Bl-tag"> - <dt><var class="Fa">mtx</var></dt> - <dd>A <a class="Xr">mutex(9)</a> representing the lock protecting the - data-structures. On entry <code class="Fn">mtsleep</code>() will release - the lock and re-acquire the lock on return.</dd> - <dt><var class="Fa">priority</var></dt> - <dd>If the flag <code class="Dv">PNORELOCK</code> is OR'ed into - <var class="Fa">priority</var> then <code class="Fn">mtsleep</code>() will - not re-acquire the lock.</dd> -</dl> -<p class="Pp" id="wakeup~2">The - <a class="permalink" href="#wakeup~2"><code class="Fn">wakeup</code></a>() - function will mark all processes which are currently sleeping on the - identifier <var class="Fa">ident</var> as runnable. Eventually, each of the - processes will resume execution in the kernel context, causing a return from - <code class="Fn">tsleep</code>() or <code class="Fn">mtsleep</code>(). Note - that processes returning from sleep should always re-evaluate the conditions - that blocked them, since a call to <code class="Fn">wakeup</code>() merely - signals a - <a class="permalink" href="#possible"><i class="Em" id="possible">possible</i></a> - change to the blocking conditions.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN - VALUES</a></h1> -<p class="Pp"><code class="Fn">tsleep</code>() and - <code class="Fn">mtsleep</code>() return 0 if they return as a result of a - <code class="Fn">wakeup</code>(). If a <code class="Fn">tsleep</code>() and - <code class="Fn">mtsleep</code>() return as a result of a signal, the return - value is <code class="Er">ERESTART</code> if the signal has the - <code class="Dv">SA_RESTART</code> property (see - <a class="Xr">sigaction(2)</a>), and <code class="Er">EINTR</code> - otherwise. If <code class="Fn">tsleep</code>() and - <code class="Fn">mtsleep</code>() return because of a timeout, the return - value is <code class="Er">EWOULDBLOCK</code>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="MIGRATING_TO_CONDVAR"><a class="permalink" href="#MIGRATING_TO_CONDVAR">MIGRATING - TO CONDVAR</a></h1> -<p class="Pp">Note the conversion from tsleep/wakeup into - <a class="Xr">condvar(9)</a> should not be done mechanically i.e. - “blindly”. Code logic should be understood before changing, - and it may also need to be revisited for the change. Please also read the - <a class="Xr">condvar(9)</a> man page.</p> -<p class="Pp" id="tsleep~3">The - <a class="permalink" href="#tsleep~3"><code class="Fn">tsleep</code></a>() - and <code class="Fn">mtsleep</code>(), and <code class="Fn">wakeup</code>() - pairs should generally be replaced by <a class="Xr">cv_wait(9)</a> / - <a class="Xr">cv_wait_sig(9)</a> / <a class="Xr">cv_timedwait(9)</a> / - <a class="Xr">cv_timedwait_sig(9)</a> and <a class="Xr">cv_signal(9)</a> / - <a class="Xr">cv_broadcast(9)</a> pairs. The - <a class="permalink" href="#cv_wait*"><code class="Fn" id="cv_wait*">cv_wait*</code></a>() - variant to use can be determined from looking at the corresponding - <code class="Fn">tsleep</code>() usage.</p> -<p class="Pp">There are two arguments of interest: <var class="Ar">timo</var> - and <var class="Ar">priority</var>. The <var class="Ar">priority</var> value - may have OR'ed the flag <code class="Dv">PCATCH</code>.</p> -<p class="Pp">The <code class="Dv">PCATCH</code> flag means that the blocking - thread should be awoken on signal, and the sleep call should be replaced - with <a class="Xr">cv_wait_sig(9)</a>.</p> -<p class="Pp">The <var class="Ar">timo</var> value, if it is not zero, indicates - how long to sleep, and the sleep call should be replaced with - <a class="Xr">cv_timedwait(9)</a>.</p> -<p class="Pp">If both the <code class="Dv">PCATCH</code> flag and a non-zero - <var class="Ar">timo</var> value are specified, then - <a class="Xr">cv_timedwait_sig(9)</a> should be used.</p> -<p class="Pp" id="cv_wait">A <a class="Xr">mutex(9)</a> (interlock) must be held - across - <a class="permalink" href="#cv_wait"><code class="Fn">cv_wait</code></a>() - and - <a class="permalink" href="#cv_broadcast"><code class="Fn" id="cv_broadcast">cv_broadcast</code></a>() - calls, in order to protect state. Most old code will require the addition of - locking, whereas some will require amending to remove - <code class="Dv">PNORELOCK</code>.</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">sigaction(2)</a>, <a class="Xr">condvar(9)</a>, - <a class="Xr">hz(9)</a>, <a class="Xr">kpause(9)</a>, - <a class="Xr">mutex(9)</a>, <a class="Xr">rwlock(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The sleep/wakeup process synchronization mechanism is very old. It - appeared in a very early version of Unix. <code class="Fn">tsleep</code>() - appeared in <span class="Ux">4.4BSD</span>. - <code class="Fn">ltsleep</code>() appeared in <span class="Ux">NetBSD - 1.5</span>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">May 7, 2024</td> - <td class="foot-os">NetBSD 10.1</td> - </tr> -</table> |