comments in rdoc conventionally don't start with two # marks and don't
have a blank line before the thing (class, method) they document.
This patch against
-rw-r--r-- 1 hgs staff 4467350 Jul 17 17:39 stable-snapshot.tar.gz
md5sum: d4afdc6b4b827e269a2eac9f7aa7f434 stable-snapshot.tar.gz
attempts to fix this. Only the comment <I>Documentation?</i> before
WaitTemplateEntry has not been processed this way, as it doesn't add
anything at the moment.
HTH
Hugh
--- ./lib/rinda/tuplespace.rb.orig 2005-10-24 16:31:30.000000000 +0100
+++ ./lib/rinda/tuplespace.rb 2006-07-17 17:58:10.839431000 +0100
@@ -5,23 +5,23 @@
module Rinda
- ##
+ #
# A TupleEntry is a Tuple (i.e. a possible entry in some Tuplespace)
# together with expiry and cancellation data.
-
+ #
class TupleEntry
include DRbUndumped
attr_accessor :expires
- ##
+ #
# Creates a TupleEntry based on +ary+ with an optional renewer or expiry
# time +sec+.
#
# A renewer must implement the +renew+ method which returns a Numeric,
# nil, or true to indicate when the tuple has expired.
-
+ #
def initialize(ary, sec=nil)
@cancel = false
@expires = nil
@@ -30,37 +30,37 @@
renew(sec)
end
- ##
+ #
# Marks this TupleEntry as canceled.
-
+ #
def cancel
@cancel = true
end
- ##
+ #
# A TupleEntry is dead when it is canceled or expired.
-
+ #
def alive?
!canceled? && !expired?
end
- ##
+ #
# Return the object which makes up the tuple itself: the Array
# or Hash.
-
+ #
def value; @tuple.value; end
- ##
+ #
# Returns the canceled status.
-
+ #
def canceled?; @cancel; end
- ##
+ #
# Has this tuple expired? (true/false).
#
# A tuple has expired when its expiry timer based on the +sec+ argument to
# #initialize runs out.
-
+ #
def expired?
return true unless @expires
return false if @expires > Time.now
@@ -70,7 +70,7 @@
return @expires < Time.now
end
- ##
+ #
# Reset the expiry time according to +sec_or_renewer+.
#
# +nil+:: it is set to expire in the far future.
@@ -79,19 +79,19 @@
#
# Otherwise the argument refers to some kind of renewer object
# which will reset its expiry time.
-
+ #
def renew(sec_or_renewer)
sec, @renewer = get_renewer(sec_or_renewer)
@expires = make_expires(sec)
end
- ##
+ #
# Returns an expiry Time based on +sec+ which can be one of:
# Numeric:: +sec+ seconds into the future
# +true+:: the expiry time is the start of 1970 (i.e. expired)
# +nil+:: it is Tue Jan 19 03:14:07 GMT Standard Time 2038 (i.e. when
# UNIX clocks will die)
-
+ #
def make_expires(sec=nil)
case sec
when Numeric
@@ -103,43 +103,43 @@
end
end
- ##
+ #
# Retrieves +key+ from the tuple.
-
+ #
def [](key)
@tuple[key]
end
- ##
+ #
# Fetches +key+ from the tuple.
-
+ #
def fetch(key)
@tuple.fetch(key)
end
- ##
+ #
# The size of the tuple.
-
+ #
def size
@tuple.size
end
- ##
+ #
# Creates a Rinda::Tuple for +ary+.
-
+ #
def make_tuple(ary)
Rinda::Tuple.new(ary)
end
private
- ##
+ #
# Returns a valid argument to make_expires and the renewer or nil.
#
# Given +true+, +nil+, or Numeric, returns that value and +nil+ (no actual
# renewer). Otherwise it returns an expiry value from calling +it.renew+
# and the renewer.
-
+ #
def get_renewer(it)
case it
when Numeric, true, nil
@@ -155,14 +155,14 @@
end
- ##
+ #
# A TemplateEntry is a Template together with expiry and cancellation data.
-
+ #
class TemplateEntry < TupleEntry
- ##
+ #
# Matches this TemplateEntry against +tuple+. See Template#match for
# details on how a Template matches a Tuple.
-
+ #
def match(tuple)
@tuple.match(tuple)
end
@@ -175,7 +175,7 @@
end
- ##
+ #
# <i>Documentation?</i>
class WaitTemplateEntry < TemplateEntry
@@ -211,7 +211,7 @@
end
- ##
+ #
# A NotifyTemplateEntry is returned by TupleSpace#notify and is notified of
# TupleSpace changes. You may receive either your subscribed event or the
# 'close' event when iterating over notifications.
@@ -237,10 +237,10 @@
class NotifyTemplateEntry < TemplateEntry
- ##
+ #
# Creates a new NotifyTemplateEntry that watches +place+ for +event+s that
# match +tuple+.
-
+ #
def initialize(place, event, tuple, expires=nil)
ary = [event, Rinda::Template.new(tuple)]
super(ary, expires)
@@ -248,17 +248,17 @@
@done = false
end
- ##
+ #
# Called by TupleSpace to notify this NotifyTemplateEntry of a new event.
-
+ #
def notify(ev)
@queue.push(ev)
end
- ##
+ #
# Retrieves a notification. Raises RequestExpiredError when this
# NotifyTemplateEntry expires.
-
+ #
def pop
raise RequestExpiredError if @done
it = @queue.pop
@@ -266,9 +266,9 @@
return it
end
- ##
+ #
# Yields event/tuple pairs until this NotifyTemplateEntry expires.
-
+ #
def each # :yields: event, tuple
while !@done
it = pop
@@ -281,19 +281,19 @@
end
- ##
+ #
# TupleBag is an unordered collection of tuples. It is the basis
# of Tuplespace.
-
+ #
class TupleBag
def initialize # :nodoc:
@hash = {}
end
- ##
+ #
# +true+ if the TupleBag to see if it has any expired entries.
-
+ #
def has_expires?
@hash.each do |k, v|
v.each do |tuple|
@@ -303,55 +303,55 @@
false
end
- ##
+ #
# Add +ary+ to the TupleBag.
-
+ #
def push(ary)
size = ary.size
@hash[size] ||= []
@hash[size].push(ary)
end
- ##
+ #
# Removes +ary+ from the TupleBag.
-
+ #
def delete(ary)
size = ary.size
@hash.fetch(size, []).delete(ary)
end
- ##
+ #
# Finds all live tuples that match +template+.
-
+ #
def find_all(template)
@hash.fetch(template.size, []).find_all do |tuple|
tuple.alive? && template.match(tuple)
end
end
- ##
+ #
# Finds a live tuple that matches +template+.
-
+ #
def find(template)
@hash.fetch(template.size, []).find do |tuple|
tuple.alive? && template.match(tuple)
end
end
- ##
+ #
# Finds all tuples in the TupleBag which when treated as templates, match
# +tuple+ and are alive.
-
+ #
def find_all_template(tuple)
@hash.fetch(tuple.size, []).find_all do |template|
template.alive? && template.match(tuple)
end
end
- ##
+ #
# Delete tuples which dead tuples from the TupleBag, returning the deleted
# tuples.
-
+ #
def delete_unless_alive
deleted = []
@hash.keys.each do |size|
@@ -370,7 +370,7 @@
end
- ##
+ #
# The Tuplespace manages access to the tuples it contains,
# ensuring mutual exclusion requirements are met.
#
@@ -382,13 +382,13 @@
include DRbUndumped
include MonitorMixin
- ##
+ #
# Creates a new TupleSpace. +period+ is used to control how often to look
# for dead tuples after modifications to the TupleSpace.
#
# If no dead tuples are found +period+ seconds after the last
# modification, the TupleSpace will stop looking for dead tuples.
-
+ #
def initialize(period=60)
super()
@bag = TupleBag.new
@@ -399,9 +399,9 @@
@keeper = nil
end
- ##
+ #
# Adds +tuple+
-
+ #
def write(tuple, sec=nil)
entry = TupleEntry.new(tuple, sec)
start_keeper
@@ -426,16 +426,16 @@
entry
end
- ##
+ #
# Removes +tuple+
-
+ #
def take(tuple, sec=nil, &block)
move(nil, tuple, sec, &block)
end
- ##
+ #
# Moves +tuple+ to +port+.
-
+ #
def move(port, tuple, sec=nil)
template = WaitTemplateEntry.new(self, tuple, sec)
yield(template) if block_given?
@@ -470,9 +470,9 @@
end
end
- ##
+ #
# Reads +tuple+, but does not remove it.
-
+ #
def read(tuple, sec=nil)
template = WaitTemplateEntry.new(self, tuple, sec)
yield(template) if block_given?
@@ -494,9 +494,9 @@
end
end
- ##
+ #
# Returns all tuples matching +tuple+. Does not remove the found tuples.
-
+ #
def read_all(tuple)
template = WaitTemplateEntry.new(self, tuple, nil)
synchronize do
@@ -507,7 +507,7 @@
end
end
- ##
+ #
# Registers for notifications of +event+. Returns a NotifyTemplateEntry.
# See NotifyTemplateEntry for examples of how to listen for notifications.
#
@@ -518,7 +518,7 @@
#
# The TupleSpace will also notify you of the 'close' event when the
# NotifyTemplateEntry has expired.
-
+ #
def notify(event, tuple, sec=nil)
template = NotifyTemplateEntry.new(self, event, tuple, sec)
synchronize do
@@ -529,9 +529,9 @@
private
- ##
+ #
# Removes dead tuples.
-
+ #
def keep_clean
synchronize do
@read_waiter.delete_unless_alive.each do |e|
@@ -549,10 +549,10 @@
end
end
- ##
+ #
# Notifies all registered listeners for +event+ of a status change of
# +tuple+.
-
+ #
def notify_event(event, tuple)
ev = [event, tuple]
@notify_waiter.find_all_template(ev).each do |template|
@@ -560,9 +560,9 @@
end
end
- ##
+ #
# Creates a thread that scans the tuplespace for expired tuples.
-
+ #
def start_keeper
return if @keeper && @keeper.alive?
@keeper = Thread.new do
@@ -573,9 +573,9 @@
end
end
- ##
+ #
# Checks the tuplespace to see if it needs cleaning.
-
+ #
def need_keeper?
return true if @bag.has_expires?
return true if @read_waiter.has_expires?