Copyright (C) 2001 Shugo Maeda <shugo@ruby-lang.org>
This library is distributed under the terms of the Ruby license.
You can freely distribute/modify this library.
This is a simple example.
empty_cond = buf.new_cond
empty_cond.wait_while { buf.empty? }
The consumer thread waits for the producer thread to push a line
to buf while buf.empty?, and the producer thread (main thread)
reads a line from ARGF and push it to buf, then call
# Adds monitor functionality to an arbitrary object by mixing the module with
# +include+. For example:
# buf.extend(MonitorMixin)
# empty_cond = buf.new_cond
# empty_cond.wait_while { buf.empty? }
# The consumer thread waits for the producer thread to push a line
# to buf while buf.empty?, and the producer thread (main thread)
# reads a line from ARGF and push it to buf, then call
# FIXME: This isn't documented in Nutshell.
# Since MonitorMixin.new_cond returns a ConditionVariable, and the example
# above calls while_wait and signal, this class should be documented.
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
@monitor.instance_eval {mon_check_owner()}
timer = create_timer(timeout)
count = @monitor.instance_eval {mon_exit_for_cond()}
@waiters.push(Thread.current)
if @waiters.include?(Thread.current) # interrupted?
@waiters.delete(Thread.current)
@monitor.instance_eval {mon_enter_for_cond(count)}
# call #wait while the supplied block returns +true+.
# call #wait until the supplied block returns +true+.
# Wake up and run the next waiter
@monitor.instance_eval {mon_check_owner()}
# Wake up all the waiters.
@monitor.instance_eval {mon_check_owner()}
def create_timer(timeout)
waiter.raise(Timeout.new)
def self.extend_object(obj)
obj.instance_eval {mon_initialize()}
# Attempts to enter exclusive section. Returns +false+ if lock fails.
@mon_owner = Thread.current
if @mon_owner == Thread.current
# For backward compatibility
alias try_mon_enter mon_try_enter
# Enters exclusive section.
mon_acquire(@mon_entering_queue)
# Leaves exclusive section.
# Enters exclusive section and executes the block. Leaves the exclusive
# section automatically when the block exits. See example under
alias synchronize mon_synchronize
# 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.
return ConditionVariable.new(self)
# called by initialize method to set defaults for instance variables.
# Throw a ThreadError exception if the current thread
if @mon_owner != Thread.current
raise ThreadError, "current thread not owner"
while @mon_owner && @mon_owner != Thread.current
queue.push(Thread.current)
@mon_owner = Thread.current
# mon_release requires Thread.critical == true
while t = @mon_waiting_queue.shift || @mon_entering_queue.shift
def mon_enter_for_cond(count)
mon_acquire(@mon_waiting_queue)
# Monitors provide means of mutual exclusion for Thread programming.
# A critical region is created by means of the synchronize method,
# 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
# to access its methods more concisely.
alias try_enter try_mon_enter
# Documentation comments:
# - All documentation comes from Nutshell.
# - MonitorMixin.new_cond appears in the example, but is not documented in
# - All the internals (internal modules Accessible and Initializable, class
# ConditionVariable) appear in RDoc. It might be good to hide them, by
# making them private, or marking them :nodoc:, etc.
# - The entire example from the RD section at the top is replicated in the RDoc
# comment for MonitorMixin. Does the RD section need to remain?
# - RDoc doesn't recognise aliases, so we have mon_synchronize documented, but
# - mon_owner is in Nutshell, but appears as an accessor in a separate module
# here, so is hard/impossible to RDoc. Some other useful accessors
# (mon_count and some queue stuff) are also in this module, and don't appear
# directly in the RDoc output.
# - in short, it may be worth changing the code layout in this file to make the
It is recommended that you Edit text format, this type of Fix handles quite a lot in one request
