- Sleep/wakeup operate on threads now, not processes.

- Describe msleep() as the primary sleep function now rather than tsleep()
  and describe tsleep() and msleep_spin() as variations.
- Try to make the description of msleep() a bit closer to English
  (sentences with actual subjects, etc.)
- Document that a priority of 0 now prevents the thread's priority from
  being altered.
- Add a history note for wakeup_one().

1 files changed, 62 insertions, 40 deletions

diff --git a/share/man/man9/sleep.9 b/share/man/man9/sleep.9
index 1e2cc730395e..1562c55aefd1 100644
--- a/share/man/man9/sleep.9
+++ b/share/man/man9/sleep.9
@@ -50,23 +50,29 @@
 .Fn wakeup_one "void *chan"
 .Sh DESCRIPTION
 The functions
-.Fn tsleep
+.Fn tsleep ,
+.Fn msleep ,
+.Fn msleep_spin ,
+.Fn wakeup ,
 and
-.Fn wakeup
-handle event-based process blocking.
-If a process must wait for an
-external event, it is put on sleep by
-.Fn tsleep .
+.Fn wakeup_one
+handle event-based thread blocking.
+If a thread must wait for an
+external event, it is put to sleep by
+.Fn tsleep ,
+.Fn msleep ,
+or
+.Fn msleep_spin .
 The parameter
 .Fa chan
 is an arbitrary address that uniquely identifies the event on which
-the process is being asleep.
-All processes sleeping on a single
+the thread is being asleep.
+All threads sleeping on a single
 .Fa chan
 are woken up later by
 .Fn wakeup ,
 often called from inside an interrupt routine, to indicate that the
-resource the process was blocking on is available now.
+resource the thread was blocking on is available now.
 .Pp
 The parameter
 .Fa wmesg
@@ -77,26 +83,49 @@ this message should not be longer than 6 characters.
 .Pp
 The
 .Fn wakeup_one
-function is used to make the first process in the queue that is
+function is used to make the first thread in the queue that is
 sleeping on the parameter
 .Fa chan
 runnable.
 This can prevent the system from becoming saturated
-when a large number of processes are sleeping on the same address,
+when a large number of threads are sleeping on the same address,
 but only one of them can actually do any useful work when made
 runnable.
 .Pp
 The
-.Fn tsleep
+.Fn msleep
 function is the general sleep call.
-Suspends the current process until a wakeup is
+It suspends the current thread until a wakeup is
 performed on the specified identifier.
-The process will then be made
+The
+.Fa mtx
+parameter is a mutex which will be released before sleeping and reacquired
+before
+.Fn msleep
+returns.
+If
+.Fa priority
+includes the
+.Dv PDROP
+flag, the
+.Fa mtx
+parameter will not be reacquired before returning.
+The mutex is used to ensure that a condition can be checked atomically,
+and that the current thread can be suspended without missing a
+change to the condition, or an associated wakeup.
+If
+.Fa priority
+is not 0,
+then the thread will be made
 runnable with the specified
-.Fa priority .
-Sleeps at most
+.Fa priority
+when it resumes.
+If
 .Fa timo
-\&/ hz seconds (0 means no timeout).
+is not 0,
+then the thread will sleep for at most
+.Fa timo
+\&/ hz seconds.
 If the
 .Va Giant
 lock is not held and
@@ -112,7 +141,9 @@ includes the
 .Dv PCATCH
 flag, signals are checked before and after sleeping, otherwise signals are
 not checked.
-Returns 0 if awakened,
+The
+.Fn msleep
+function returns 0 if awakened,
 .Er EWOULDBLOCK
 if the timeout expires.
 If
@@ -127,34 +158,21 @@ is returned if the system call should be interrupted by the signal
 .Er EINTR ) .
 .Pp
 The
+.Fn tsleep
+function is a variation on
+.Fn msleep .
+It is identical to invoking
 .Fn msleep
-function is a variation on tsleep.
-The parameter
-.Fa mtx
-is a mutex which will be released before sleeping and reacquired before
-.Fn msleep
-returns.
-If
-.Fa priority
-includes the
-.Dv PDROP
-flag, the
+with a
+.Dv NULL
 .Fa mtx
-parameter will not be reacquired before returning.
-The mutex is
-used to ensure that a condition can be checked atomically, and
-that the current process can be suspended without missing a
-change to the condition, or an associated wakeup.
+parameter.
 .Pp
 The
 .Fn msleep_spin
 function is another variation on
-.Fn tsleep
-similar to
 .Fn msleep .
-Unlike
-.Fn msleep ,
-this function accepts a spin mutex rather than a default mutex for its
+This function accepts a spin mutex rather than a default mutex for its
 .Fa mtx
 parameter.
 It is also more limited in that it does not accept a
@@ -173,7 +191,7 @@ See above.
 .Xr malloc 9 ,
 .Xr mi_switch 9
 .Sh HISTORY
-The sleep/wakeup process synchronization mechanism is very old.
+The sleep/wakeup thread synchronization mechanism is very old.
 It
 appeared in a very early version of
 .Ux .
@@ -183,6 +201,10 @@ The
 function appeared in
 .Bx 4.4 .
 The
+.Fn wakeup_one
+function appeared in
+.Fx 2.2 .
+The
 .Fn msleep
 function appeared in
 .Fx 5.0 ,