[threads-standard-discuss] bordeaux-mp Specification,1.3,1.4

[Daniel Barlow,,,]

Update of /usr/local/src/cvs/bordeaux-mp
In directory loaclhost.telent.net:/tmp/cvs-serv1515

Modified Files:
	Specification 
Log Message:
rewrite explanation of condition variables

Index: Specification
===================================================================
RCS file: /usr/local/src/cvs/bordeaux-mp/Specification,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- Specification	10 Jul 2004 23:18:45 -0000	1.3
+++ Specification	12 Jul 2004 01:22:01 -0000	1.4
@@ -170,22 +170,18 @@
 
 * Resource contention: condition variables
 
-Condition variables are for use when you have a shared resource with
-some kind of state, and the decision as to which process may run next
-is dependent on that state.  For example: a buffer with readers and a
-writer, where the readers can only run when there is data in the
-buffer, and the writer can only refill the buffer when it is empty.
-
-There are three parts to any system involving a condition variable
-
- - the condition itself.  In this example it would be "buffer is (not)
-empty" and "buffer is not empty".  This is not apparent in the actual
-code.
-
- - a lock to protect the sections of code that evaluate the condition.
+A condition variable is a queue of processes which are waiting for
+some event.  When the event occurs, the queue will be notified,
+causing one or more of the stopped processes to be resumed.
 
- - a condition-variable object; this is essentially a queue of
-processes waiting for the condition to change.
+Condition variables are used to signal events when the state of some
+shared resource changes: for example, consider a buffer with readers
+and a writer, where the readers can only run when there is data in the
+buffer, and the writer can only refill the buffer when it is empty.
+By providing an atomic "release lock and sleep" operation, a condition
+variable guards against the "lost notification" problem, which is
+where the writer adds data to the buffer in between the time that a
+reader tests it (finding it empty) and goes to sleep.
 
 make-condition-variable () [function]
 
@@ -194,11 +190,11 @@
 
 condition-wait (condition-variable lock)  [function]
 
-Atomically release LOCK and enqueue ourselves waiting for
+Atomically release LOCK and enqueue the calling process waiting for
 CONDITION-VARIABLE.  The process will resume when another thread has
-notified us using CONDITION-NOTIFY, or we are interrupted, or in other
+notified it using CONDITION-NOTIFY, or we are interrupted, or in other
 implementation-dependent circumstances: the caller must always test
-the condition on waking before continuing normal processing.
+on waking that it can proceed, before continuing normal processing.
 
 However and for whatever reason the process is resumed, the system
 always reacquires LOCK before returning to the caller.  It is an error
@@ -216,6 +212,8 @@
 In an implementation that does not support multiple processes, this
 function has no effect.
 
+* Miscellaneous
+
 process-yield [Function]
 
 Allows other processes to run.  It may be necessary or desirable to