update asleep/await sections

1 files changed, 46 insertions, 31 deletions

diff --git a/share/man/man9/sleep.9 b/share/man/man9/sleep.9
index 0e352e4..2d9410b 100644
--- a/share/man/man9/sleep.9
+++ b/share/man/man9/sleep.9
@@ -23,7 +23,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.\" $Id: sleep.9,v 1.11 1998/12/21 10:29:28 dillon Exp $
+.\" $Id: sleep.9,v 1.12 1998/12/21 10:34:53 dillon Exp $
 .\" "
 .Dd December 17, 1998
 .Os
@@ -133,15 +133,18 @@ value of NULL
 to remove any previously queued condition.  
 .Pp
 .Nm Await
-implements the new asynchronous wait function.  If you 
+implements the new asynchronous wait function.  When 
 .Fn asleep
-on an identifier,
+is called on an identifier it associates the process with that
+identifier but does not block.
 .Fn await
-will actually block the process until someone calls 
+will actually block the process until
 .Fn wakeup
-on that identifier.  If someone calls 
+is called on that identifier any time after the
+.Fn asleep . 
+If 
 .Fn wakeup
-after you
+is called after you
 .Fn asleep
 but before you 
 .Fn await
@@ -151,10 +154,10 @@ call is effectively a NOP.
 If
 .Fn await
 is called multiple times without an intervening
-.Fn asleep
+.Fn asleep ,
 the 
 .Fn await
-is effective a NOP, but will call 
+is effectively a NOP but will also call
 .Fn mswitch
 for safety.  The
 .Fn await
@@ -162,13 +165,13 @@ function allows you to override the priority and timeout values to be used.
 If the value -1 is specified for an argument, the value is taken from the
 previous
 .Fn asleep
-call.  If you pass -1 for the priority you must be prepared to catch signal
+call.  If -1 is passed for the priority you must be prepared to catch signal
 conditions if the prior call to
 .Fn asleep
-specified it in its priority.  If you pass -1 for the timeout you must be
+specified it in its priority.  If -1 is passed for the timeout you must be
 prepared to catch a timeout condition if the prior call to 
 .Fn asleep
-specified a timeout.  When you use -1, you should generally not make 
+specified a timeout.  When you use -1, it is usually a good idea to not make
 assumptions as to the arguments used by the prior
 .Fn asleep
 call.
@@ -177,29 +180,39 @@ The
 .Fn asleep
 and
 .Fn await
-functions are used by the kernel code for various purposes but the main one is
-to allow complex interlocking code to 'backout' of a temporary resource failure
-(such as lack of memory or trying to access a block that is not in the buffer
-cache) in order to release major locks prior to blocking, and to then retry 
-the call that failed on wakeup.  This involves subroutines deep in the kernel
-calling
+functions are mainly used by the kernel to shift the burden of blocking
+away from extremely low level routines and to push it onto their callers.
+This in turn allows more complex interlocking code to
+.Em backout 
+of a temporary resource failure
+(such as lack of memory) in order to release major locks prior to actually
+blocking, and to then retry the operation on wakeup.  This key feature is
+expected to be heavily used in SMP situations in order to allow code to make
+better use of spinlocks.  A spinlock, by its very nature, cannot be used 
+around code that might block.  It is hoped that these capabilities will
+make it easier to migrate the SMP master locks deeper into the kernel.
+.Pp
+These routines may also be used to avoid nasty spl*() calls to get around
+race conditions with simple conditional test/wait interlocks.  You simple
+call
+.Fn asleep
+prior to your test, then conditonally
+.Fn await
+only if the test fails.  It is usually a good idea to cancel an
 .Fn asleep
-and returning a temporary failure, then popping back up through a number
-of call levels before calling
+if you wind up never calling the related
 .Fn await ,
-then retrying.    The kernel might also use these functions to avoid using 
-spinlocks in a check-condition interlock.  That is, in case the case where
-the kernel wishes to check the condition of something and then block on it.
-To avoid the race between the check and the blocking, the kernel can first
-check the condition, then call
-.Fn asleep ,
-then check the condition a second time before calling
-.Fn await .
-The overlap makes the race condition impossible.
+but it is not required.  If you do not want to waste cpu calling
+.Fn asleep
+unnecessarily, you can surround the whole thing with a second test.  The
+race condition is still handled by the inside
+.Fn asleep
+call.
 .Sh RETURN VALUES
 See above.
 .Sh SEE ALSO
-.Xr ps 1
+.Xr ps 1 ,
+.Xr malloc 9
 .Sh HISTORY
 The sleep/wakeup process synchronization mechanism is very old.  It
 appeared in a very early version of Unix.
@@ -209,8 +222,10 @@ appeared in
 .Bx 4.4 .
 .Pp
 .Nm Asleep/await 
-first appeared in FreeBSD-3.0.1
+first appeared in FreeBSD-3.0.1 and is designed to shift the burden of blocking
+away from extremely low level routines and push it up to their callers.
 .Sh AUTHORS
 This man page has been written by
 .ie t J\(:org Wunsch.
-.el Joerg Wunsch.  asleep/await portions were written by Matt Dillon
+.el Joerg Wunsch. 
+asleep/await designed and written by Matthew Dillon.