From 1378251dc19c411703dff32b9ef492a1f30a0167 Mon Sep 17 00:00:00 2001
From: matz <matz@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Thu, 13 Jul 2006 17:33:04 +0000
Subject: * lib/monitor.rb: document patch from Hugh Sasse <hgs at dmu.ac.uk>. 
  [ruby-core:08205]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@10528 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
---
 ChangeLog      |  5 +++++
 lib/monitor.rb | 26 ++++++++++++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index c108a69d98..24bc254345 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Fri Jul 14 02:30:12 2006  Yukihiro Matsumoto  <matz@ruby-lang.org>
+
+	* lib/monitor.rb: document patch from Hugh Sasse <hgs at dmu.ac.uk>.
+	  [ruby-core:08205]
+
 Fri Jul 14 00:10:15 2006  Yukihiro Matsumoto  <matz@ruby-lang.org>
 
 	* array.c (rb_ary_pop): may cause realloc oscillation.  a patch
diff --git a/lib/monitor.rb b/lib/monitor.rb
index e56480b763..f0e79d8fc8 100644
--- a/lib/monitor.rb
+++ b/lib/monitor.rb
@@ -86,6 +86,10 @@ module MonitorMixin
   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.funcall(:mon_check_owner)
       timer = create_timer(timeout)
@@ -112,18 +116,22 @@ module MonitorMixin
       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.funcall(:mon_check_owner)
       Thread.critical = true
@@ -133,6 +141,7 @@ module MonitorMixin
       Thread.pass
     end
     
+    # Wake up all the waiters.
     def broadcast
       @monitor.funcall(:mon_check_owner)
       Thread.critical = true
@@ -235,6 +244,9 @@ module MonitorMixin
   
   #
   # 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 @@ module MonitorMixin
     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 @@ module MonitorMixin
     @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 @@ module MonitorMixin
   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
-- 
cgit v1.2.3