summaryrefslogtreecommitdiff
path: root/lib/monitor.rb
diff options
context:
space:
mode:
authormatz <matz@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2006-07-13 17:33:04 +0000
committermatz <matz@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2006-07-13 17:33:04 +0000
commitcbc0ede66143d3ce69989949192322491f8de22a (patch)
treeac2825ba0ef5fd7b00ffc7da10eec944efc634d3 /lib/monitor.rb
parent45d5c467b3b393832804efa031c0a2649bfd8027 (diff)
* 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/branches/ruby_1_8@10528 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'lib/monitor.rb')
-rw-r--r--lib/monitor.rb26
1 files changed, 26 insertions, 0 deletions
diff --git a/lib/monitor.rb b/lib/monitor.rb
index 6bd14d0..4ed4e41 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.instance_eval {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.instance_eval {mon_check_owner()}
Thread.critical = true
@@ -133,6 +141,7 @@ module MonitorMixin
Thread.pass
end
+ # Wake up all the waiters.
def broadcast
@monitor.instance_eval {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