284 lines
7.0 KiB
Groff
284 lines
7.0 KiB
Groff
.\" $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 .
|