doc-patch for monitor.

A patch against:

-rw-r--r--   1 hgs      staff    4467539 Jul 13 13:08 stable-snapshot.tar.gz
md5sum: 7e3db77a67f3b2a14e8a93229bb2d49d  stable-snapshot.tar.gz

This is an attempt to improve the docs for Monitor.  I don't fully
understand the details of how the threading is being done here, but
I think what I have written does not depend on those details and is
thus accurate.

        HTH
        Hugh

--- ruby-stable-snapshot/lib/monitor.rb.orig	2005-09-02 15:52:56.000000000 +0100
+++ ruby-stable-snapshot/lib/monitor.rb	2006-07-13 16:53:59.818832000 +0100
@@ -86,6 +86,10 @@
   class ConditionVariable
     class Timeout < Exception; end
     
+    # Create a new timer with the argument timeout, and add the
+    # current thread to the list of waiters.  Then the thread is
+    # stopped.  It will be resumed when a corresponding #signal 
+    # occurs.
     def wait(timeout = nil)
       @monitor.instance_eval {mon_check_owner()}
       timer = create_timer(timeout)
@@ -112,18 +116,22 @@
       end
     end
     
+
+    # call #wait while the supplied block returns +true+.
     def wait_while
       while yield
 	wait
       end
     end
     
+    # call #wait until the supplied block returns +true+.
     def wait_until
       until yield
 	wait
       end
     end
     
+    # Wake up and run the next waiter
     def signal
       @monitor.instance_eval {mon_check_owner()}
       Thread.critical = true
@@ -133,6 +141,7 @@
       Thread.pass
     end
     
+    # Wake up all the waiters.
     def broadcast
       @monitor.instance_eval {mon_check_owner()}
       Thread.critical = true
@@ -235,6 +244,9 @@
   
   #
   # FIXME: This isn't documented in Nutshell.
+  # 
+  # Create a new condition variable for this monitor.
+  # This facilitates control of the monitor with #signal and #wait.
   #
   def new_cond
     return ConditionVariable.new(self)
@@ -247,6 +259,7 @@
     mon_initialize
   end
 
+  # called by initialize method to set defaults for instance variables.
   def mon_initialize
     @mon_owner = nil
     @mon_count = 0
@@ -254,6 +267,8 @@
     @mon_waiting_queue = []
   end
 
+  # Throw a ThreadError exception if the current thread
+  # does't own the monitor
   def mon_check_owner
     if @mon_owner != Thread.current
       raise ThreadError, "current thread not owner"
@@ -289,6 +304,17 @@
   end
 end
 
+# Monitors provide means of mutual exclusion for Thread programming.
+# A critical region is created by means of the synchronize method,
+# which takes a block.
+# The condition variables (created with #new_cond) may be used 
+# to control the execution of a monitor with #signal and #wait.
+#
+# the Monitor class wraps MonitorMixin, and provides aliases
+#  alias try_enter try_mon_enter
+#  alias enter mon_enter
+#  alias exit mon_exit
+# to access its methods more concisely.
 class Monitor
   include MonitorMixin
   alias try_enter try_mon_enter