.\"	$NetBSD: ltsleep.9,v 1.18 2017/03/18 19:01:01 riastradh Exp $
.\"
.\" Copyright (c) 1996, 2002, 2007 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Paul Kranenburg.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd March 22, 2014
.Dt LTSLEEP 9
.Os
.Sh NAME
.Nm ltsleep ,
.Nm mtsleep ,
.Nm tsleep ,
.Nm wakeup
.Nd process context sleep and wakeup
.Sh SYNOPSIS
.In sys/proc.h
.Ft int
.Fn "mtsleep" "wchan_t ident" "pri_t priority" "const char *wmesg" "int timo" "kmutex_t *mtx"
.Ft int
.Fn "tsleep" "wchan_t ident" "pri_t priority" "const char *wmesg" "int timo"
.Ft void
.Fn "wakeup" "wchan_t ident"
.Sh DESCRIPTION
.Em The interfaces described in this manual page are obsolete
.Em and will be removed from a future version of the system.
.Pp
.Em The
.Em Fn ltsleep
.Em interface has been obsoleted and removed from the system.
.Pp
.Em Please see the
.Xr condvar 9 ,
.Xr mutex 9 ,
.Em and
.Xr rwlock 9
.Em manual pages for information on kernel synchronisation primitives.
.Pp
These functions implement voluntary context switching.
.Fn tsleep
and
.Fn mtsleep
are used throughout the kernel whenever processing in the current context
can not continue for any of the following reasons:
.Bl -bullet -offset indent
.It
The current process needs to await the results of a pending I/O operation.
.It
The current process needs resources
.Pq e.g., memory
which are temporarily unavailable.
.El
.Pp
The function
.Fn wakeup
is used to notify sleeping processes of possible changes to the condition
that caused them to go to sleep.
Typically, an awakened process will \(em after it has acquired a
context again \(em retry the action that blocked its operation to see
if the
.Dq blocking
condition has cleared.
.Pp
The
.Fn tsleep
and
.Fn mtsleep
functions take the following arguments:
.Bl -tag -width priority
.It Fa ident
An identifier of the
.Dq 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
.Fn wakeup
to get the process going again.
.Fa ident
should not be
.Dv NULL .
.It Fa priority
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
.Dq throughput
of processes executing in kernel mode.
If the flag
.Dv PCATCH
is OR'ed into
.Fa priority
the process checks for posted signals before and after sleeping.
.It Fa wmesg
A pointer to a character string indicating the reason a process is sleeping.
The kernel does not use the string, but makes it available
.Pq through the process structure field Li p_wmesg
for user level utilities such as
.Xr ps 1 .
.It Fa timo
If non-zero, the process will sleep for at most
.Li timo/hz
seconds.
If this amount of time elapses and no
.Fn wakeup "ident"
has occurred, and no signal
.Pq if Dv PCATCH No was set
was posted,
.Fn tsleep
will return
.Er EWOULDBLOCK .
.El
.Pp
The
.Fn mtsleep
function takes an additional argument and flag:
.Bl -tag -width priority
.It Fa mtx
A
.Xr mutex 9
representing the lock protecting the data-structures.
On entry
.Fn mtsleep
will release the lock and re-acquire the lock on return.
.It Fa priority
If the flag
.Dv PNORELOCK
is OR'ed into
.Fa priority
then
.Fn mtsleep
will not re-acquire the lock.
.El
.Pp
The
.Fn wakeup
function will mark all processes which are currently sleeping on the identifier
.Fa ident
as runnable.
Eventually, each of the processes will resume execution in the kernel
context, causing a return from
.Fn tsleep
or
.Fn mtsleep .
Note that processes returning from sleep should always re-evaluate the
conditions that blocked them, since a call to
.Fn wakeup
merely signals a
.Em possible
change to the blocking conditions.
.Sh RETURN VALUES
.Fn tsleep
and
.Fn mtsleep
return 0 if they return as a result of a
.Fn wakeup .
If a
.Fn tsleep
and
.Fn mtsleep
return as a result of a signal, the return value is
.Er ERESTART
if the signal has the
.Dv SA_RESTART
property
.Pq see Xr sigaction 2 ,
and
.Er EINTR
otherwise.
If
.Fn tsleep
and
.Fn mtsleep
return because of a timeout, the return value is
.Er EWOULDBLOCK .
.Sh MIGRATING TO CONDVAR
Note the conversion from tsleep/wakeup into
.Xr condvar 9
should not be done mechanically i.e.
.Dq blindly .
Code logic should be understood before changing, and it may also need to be
revisited for the change.
Please also read the
.Xr condvar 9
man page.
.Pp
The
.Fn tsleep
and
.Fn mtsleep ,
and
.Fn wakeup
pairs should generally be replaced by
.Xr cv_wait 9 /
.Xr cv_wait_sig 9 /
.Xr cv_timedwait 9 /
.Xr cv_timedwait_sig 9
and
.Xr cv_signal 9 /
.Xr cv_broadcast 9
pairs.
The
.Fn cv_wait*
variant to use can be determinded from looking at the corresponding
.Fn tsleep
usage.
.Pp
There are two arguments of interest:
.Ar timo
and
.Ar priority .
The
.Ar priority
value may have OR'ed the flag
.Dv PCATCH .
.Pp
The
.Dv PCATCH
flag means that the blocking thread should be awoken on signal, and
the sleep call should be replaced with
.Xr cv_wait_sig 9 .
.Pp
The
.Ar timo
value, if it is not zero, indicates how long to sleep, and
the sleep call should be replaced with
.Xr cv_timedwait 9 .
.Pp
If both the
.Dv PCATCH
flag and a non-zero
.Ar timo
value are specified, then
.Xr cv_timedwait_sig 9
should be used.
.Pp
A
.Xr mutex 9
(interlock) must be held across
.Fn cv_wait
and
.Fn cv_broadcast
calls, in order to protect state.
Most old code will require the addition of locking, whereas some will
require amending to remove
.Dv PNORELOCK .
.Sh SEE ALSO
.Xr sigaction 2 ,
.Xr condvar 9 ,
.Xr hz 9 ,
.Xr mutex 9 ,
.Xr rwlock 9
.Sh HISTORY
The sleep/wakeup process synchronization mechanism is very old.
It appeared in a very early version of Unix.
.Fn tsleep
appeared in
.Bx 4.4 .
.Fn ltsleep
appeared in
.Nx 1.5 .