Rewrite sleepqueue manpage to catch up to the new sleep queue interface.
This commit is contained in:
John Baldwin
parent
1ed3e44f22
commit
bf0e60bbbb
@ -772,9 +772,23 @@ MLINKS+=sleep.9 msleep.9 \
|
||||
sleep.9 tsleep.9 \
|
||||
sleep.9 wakeup.9 \
|
||||
sleep.9 wakeup_one.9
|
||||
MLINKS+=sleepqueue.9 endtsleep.9 \
|
||||
sleepqueue.9 sleepinit.9 \
|
||||
sleepqueue.9 unsleep.9
|
||||
MLINKS+=sleepqueue.9 init_sleepqueues.9 \
|
||||
sleepqueue.9 sleepq_abort.9 \
|
||||
sleepqueue.9 sleepq_add.9 \
|
||||
sleepqueue.9 sleepq_alloc.9 \
|
||||
sleepqueue.9 sleepq_broadcast.9 \
|
||||
sleepqueue.9 sleepq_calc_signal_retval.9 \
|
||||
sleepqueue.9 sleepq_catch_signals.9 \
|
||||
sleepqueue.9 sleepq_free.9 \
|
||||
sleepqueue.9 sleepq_lookup.9 \
|
||||
sleepqueue.9 sleepq_release.9 \
|
||||
sleepqueue.9 sleepq_remove.9 \
|
||||
sleepqueue.9 sleepq_signal.9 \
|
||||
sleepqueue.9 sleepq_set_timeout.9 \
|
||||
sleepqueue.9 sleepq_timedwait.9 \
|
||||
sleepqueue.9 sleepq_timedwait_sig.9 \
|
||||
sleepqueue.9 sleepq_wait.9 \
|
||||
sleepqueue.9 sleepq_wait_sig.9
|
||||
MLINKS+=spl.9 spl0.9 \
|
||||
spl.9 splbio.9 \
|
||||
spl.9 splclock.9 \
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
.\" Copyright (c) 2000-2001 John H. Baldwin <jhb@FreeBSD.org>
|
||||
.\" Copyright (c) 2000-2004 John H. Baldwin <jhb@FreeBSD.org>
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
@ -23,67 +23,274 @@
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd November 3, 2000
|
||||
.Dd March 10, 2004
|
||||
.Dt SLEEPQUEUE 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm endtsleep ,
|
||||
.Nm sleepinit ,
|
||||
.Nm unsleep
|
||||
.Nd manage the queues of sleeping processes
|
||||
.Nm init_sleepqueues ,
|
||||
.Nm sleepq_abort ,
|
||||
.Nm sleepq_add ,
|
||||
.Nm sleepq_alloc ,
|
||||
.Nm sleepq_broadcast ,
|
||||
.Nm sleepq_calc_signal_retval ,
|
||||
.Nm sleepq_catch_signals ,
|
||||
.Nm sleepq_free ,
|
||||
.Nm sleepq_lookup ,
|
||||
.Nm sleepq_release ,
|
||||
.Nm sleepq_remove ,
|
||||
.Nm sleepq_signal ,
|
||||
.Nm sleepq_set_timeout ,
|
||||
.Nm sleepq_timedwait ,
|
||||
.Nm sleepq_timedwait_sig ,
|
||||
.Nm sleepq_wait ,
|
||||
.Nm sleepq_wait_sig
|
||||
.Nd manage the queues of sleeping threads
|
||||
.Sh SYNOPSIS
|
||||
.In sys/param.h
|
||||
.In sys/proc.h
|
||||
.In sys/sleepqueue.h
|
||||
.Ft void
|
||||
.Fn endtsleep "void *arg"
|
||||
.Fn init_sleepqueues "void"
|
||||
.Ft void
|
||||
.Fn sleepinit "void"
|
||||
.Fn sleepq_abort "struct thread *td"
|
||||
.Ft void
|
||||
.Fn unsleep "struct thread *td"
|
||||
.Fn sleepq_add "struct sleepqueue *sq" "void *wchan" "struct mtx *lock" "const char *wmesg" "int flags"
|
||||
.Ft struct sleepqueue *
|
||||
.Fn sleepq_alloc "void"
|
||||
.Ft void
|
||||
.Fn sleepq_broadcast "void *wchan" "int flags" "int pri"
|
||||
.Ft int
|
||||
.Fn sleepq_calc_signal_retval "int sig"
|
||||
.Ft int
|
||||
.Fn sleepq_catch_signals "void *wchan"
|
||||
.Ft void
|
||||
.Fn sleepq_free "struct sleepqueue *sq"
|
||||
.Ft struct sleepqueue *
|
||||
.Fn sleepq_lookup "void *wchan"
|
||||
.Ft void
|
||||
.Fn sleepq_release "void *wchan"
|
||||
.Ft void
|
||||
.Fn sleepq_remove "struct thread *td" "void *wchan"
|
||||
.Ft void
|
||||
.Fn sleepq_signal "void *wchan" "int flags" "int pri"
|
||||
.Ft void
|
||||
.Fn sleepq_set_timeout "void *wchan" "int timo"
|
||||
.Ft int
|
||||
.Fn sleepq_timedwait "void *wchan" "int signal_caught"
|
||||
.Ft int
|
||||
.Fn sleepq_timedwait_sig "void *wchan" "int signal_caught"
|
||||
.Ft void
|
||||
.Fn sleepq_wait "void *wchan"
|
||||
.Ft int
|
||||
.Fn sleepq_wait_sig "void *wchan"
|
||||
.Sh DESCRIPTION
|
||||
The sleep queues used by
|
||||
.Xr msleep 9
|
||||
and friends are stored in a hash array.
|
||||
The address of the wait channel is used to generate an index into the array.
|
||||
Each entry in the array is a queue of processes that are sleeping on wait
|
||||
channels that hash to that index.
|
||||
.Xr msleep 9
|
||||
places processes into their appropriate queues directly.
|
||||
To handle timeouts, the
|
||||
.Fn endtsleep
|
||||
function is registered as a
|
||||
.Xr timeout 9 .
|
||||
When the process is woken by either
|
||||
.Fn wakeup
|
||||
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.
|
||||
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.
|
||||
The
|
||||
.Fn sleepq_alloc
|
||||
allocates an inactive sleep queue and is used to assign a sleep queue to a
|
||||
thread during thread creation.
|
||||
The
|
||||
.Fn sleepq_free
|
||||
function frees the resources associated with an inactive sleep queue and is
|
||||
used to free a queue during thread destruction.
|
||||
.Pp
|
||||
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
|
||||
.Fn init_sleepqueues
|
||||
function initializes the hash table of sleep queue chains.
|
||||
.Pp
|
||||
The
|
||||
.Fn sleepq_lookup
|
||||
function locks the sleep queue chain associated with
|
||||
.Fa wchan
|
||||
and returns a pointer to the current active sleep queue for that wait channel
|
||||
or
|
||||
.Fn wakeup_one ,
|
||||
the timeout is revoked via
|
||||
.Xr untimeout 9 .
|
||||
If the process is not awakened soon enough, then
|
||||
.Fn endtsleep
|
||||
is called with
|
||||
.Fa arg
|
||||
pointing to the
|
||||
.Vt "struct proc"
|
||||
of the process that timed out.
|
||||
.Fn endtsleep
|
||||
undoes the sleep and makes the process runnable if it is in the
|
||||
.Dv SSLEEP
|
||||
state.
|
||||
The sleep queues and the hash array are protected internally by the
|
||||
.Va sched_lock
|
||||
mutex.
|
||||
.Dv NULL
|
||||
if there currently is not an active sleep queue.
|
||||
The
|
||||
.Fn sleepq_release
|
||||
function unlocks the sleep queue chain associated with
|
||||
.Fn wchan
|
||||
and is primarily useful when aborting a pending sleep request before one of
|
||||
the wait functions is called.
|
||||
.Pp
|
||||
.Fn unsleep
|
||||
simply removes the thread
|
||||
The
|
||||
.Fn sleepq_add
|
||||
function places the current thread on the sleep queue associated with the
|
||||
wait channel
|
||||
.Fa wchan .
|
||||
The associated sleep queue chain must be locked by a call to
|
||||
.Fn sleepq_lookup
|
||||
when this function is called and its return value should be passed as the
|
||||
.Fa sq
|
||||
parameter.
|
||||
If a mutex is specified via the
|
||||
.Fa lock
|
||||
argument, then the sleep queue code will perform extra checks to ensure that
|
||||
the mutex is held for all threads sleeping on
|
||||
.Fa wchan .
|
||||
The
|
||||
.Fa wmesg
|
||||
parameter should be a short description of
|
||||
.Fa wchan .
|
||||
The
|
||||
.Fa flags
|
||||
parameter currently only specifies the type of sleep queue being slept on.
|
||||
A value of
|
||||
.Dv 0
|
||||
indicates a sleep queue used by
|
||||
.Xr msleep 9
|
||||
and a value of
|
||||
.Dv SLEEPQ_CONDVAR
|
||||
indicates a sleep queue used by
|
||||
.Xr condvar 9 .
|
||||
A timeout on the sleep may be specified by calling
|
||||
.Fn sleepq_set_timeout
|
||||
after
|
||||
.Fn sleepq_add .
|
||||
The
|
||||
.Fa wchan
|
||||
parameter should be the same value from the preceding call to
|
||||
.Fn sleepq_add .
|
||||
The
|
||||
.Fa timo
|
||||
parameter should specify the timeout value in ticks.
|
||||
The thread may be marked interruptible by calling
|
||||
.Fn sleepq_catch_signals
|
||||
with
|
||||
.Fa wchan
|
||||
set to the wait channel.
|
||||
The function returns a signal number if there are any pending signals for
|
||||
the current thread and 0 if there is not a pending signal.
|
||||
.Pp
|
||||
Once the thread is ready to suspend,
|
||||
one of the wait functions is called to put the thread to sleep until it is
|
||||
awakened and context switch to another thread.
|
||||
The
|
||||
.Fn sleepq_wait
|
||||
function is used for non-interruptible sleeps that do not have a timeout.
|
||||
The
|
||||
.Fn sleepq_timedwait
|
||||
function is used for non-interruptible sleeps that have had a timeout set via
|
||||
.Fn sleepq_set_timeout .
|
||||
The
|
||||
.Fn sleepq_wait_sig
|
||||
function is used for interruptible sleeps that do not have a timeout.
|
||||
The
|
||||
.Fn sleepq_timedwait_sig
|
||||
function is used for interruptible sleeps that do have a timeout set.
|
||||
The
|
||||
.Fa wchan
|
||||
argument to all of the wait functions is the wait channel being slept on.
|
||||
The
|
||||
.Fa signal_caught
|
||||
parameter to the timed wait functions specifies if a previous call to
|
||||
.Fn sleepq_catch_signals
|
||||
found a pending signal.
|
||||
.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
|
||||
.Dv EWOULDBLOCK
|
||||
is returned.
|
||||
If the sleep was interrupted by something other than a signal,
|
||||
then some other return value will be returned.
|
||||
If zero is returned after resuming from an interruptible sleep,
|
||||
then
|
||||
.Fn sleepq_calc_signal_retval
|
||||
should be called to determine if the sleep was interrupted by a signal.
|
||||
If so,
|
||||
.Fn sleepq_calc_signal_retval
|
||||
returns
|
||||
.Dv ERESTART
|
||||
if the interrupting signal is restarable and
|
||||
.Dv EINTR
|
||||
otherwise.
|
||||
If the sleep was not interrupted by a signal,
|
||||
.Fn sleepq_calc_signal_retval
|
||||
will return 0.
|
||||
.Pp
|
||||
A sleeping thread is normally resumed by the
|
||||
.Fn sleepq_broadcast
|
||||
and
|
||||
.Fn sleepq_signal
|
||||
functions.
|
||||
The
|
||||
.Fn sleepq_signal
|
||||
function awakens the highest priority thread sleeping on a wait channel while
|
||||
.Fn sleepq_broadcast
|
||||
awakends all of the threads sleeping on a wait channel.
|
||||
The
|
||||
.Fa wchan
|
||||
argument specifics which wait channel to awaken.
|
||||
The
|
||||
.Fa flags
|
||||
argument should match the
|
||||
.Fa flags
|
||||
argument passed to
|
||||
.Fn sleepq_add
|
||||
by the threads sleeping on the wait channel.
|
||||
If the
|
||||
.Fa pri
|
||||
argument does not equal -1,
|
||||
then each thread that is awakened will have its priority raised to
|
||||
.Fa pri
|
||||
if it has a lower priority.
|
||||
.Pp
|
||||
A thread in an interruptible sleep can be interrupted by another thread via
|
||||
the
|
||||
.Fn sleepq_abort
|
||||
function.
|
||||
The
|
||||
.Fa td
|
||||
from its sleep queue.
|
||||
argument specifies the thread to interrupt.
|
||||
An individual thread can also be awakened from sleeping on a specific wait
|
||||
channel via the
|
||||
.Fn sleepq_remove
|
||||
function.
|
||||
The
|
||||
.Fa td
|
||||
argument specifies the thread to awaken and the
|
||||
.Fa wchan
|
||||
argument specifies the wait channel to awaken it from.
|
||||
If the thread
|
||||
.Fa td
|
||||
is not blocked on the the wait channel
|
||||
.Fa wchan
|
||||
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.
|
||||
.Pp
|
||||
.Fn sleepinit
|
||||
is called during system startup and initializes the scheduler quantum
|
||||
.Pq Va sched_quantum
|
||||
and the sleep queues.
|
||||
The sleep queue interface is currently used to implement the
|
||||
.Xr msleep 9
|
||||
and
|
||||
.Xr condvar 9
|
||||
interfaces.
|
||||
Almost all other code in the kernel should use one of those interfaces rather
|
||||
than manipulating sleep queues directly.
|
||||
.Sh SEE ALSO
|
||||
.Xr msleep 9 ,
|
||||
.Xr condvar 9 ,
|
||||
.Xr runqueue 9 ,
|
||||
.Xr scheduler 9
|
||||
|
||||
Loading…
Reference in New Issue
Block a user