summaryrefslogtreecommitdiff
path: root/lib/rinda
diff options
context:
space:
mode:
authorgsinclair <gsinclair@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2004-02-17 22:29:07 +0000
committergsinclair <gsinclair@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2004-02-17 22:29:07 +0000
commite81b38b6d34c1959611fd4cfab6a293b07f199e9 (patch)
tree0056d7d4d83d6fb2584acd07a62401a58ef803af /lib/rinda
parent4b41d18b6ce05e48ac120274612cd76d6a1ccd54 (diff)
* lib/rinda/rinda.rb: added documentation (from Hugh Sasse)
* lib/rinda/tuplespace.rb: ditto git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@5757 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'lib/rinda')
-rw-r--r--lib/rinda/rinda.rb43
-rw-r--r--lib/rinda/tuplespace.rb74
2 files changed, 114 insertions, 3 deletions
diff --git a/lib/rinda/rinda.rb b/lib/rinda/rinda.rb
index 273560b..a29d776 100644
--- a/lib/rinda/rinda.rb
+++ b/lib/rinda/rinda.rb
@@ -1,10 +1,32 @@
+#
+# rinda.rb: A Ruby implementation of the Linda distibuted computing paradigm.
+#
+# <i>Introduction to Linda/rinda?</i>
+#
+# <i>Why is this library separate from <tt>drb</tt>?</i>
+#
+# <i>Example(s)</i>
+#
+# (See the samples directory in the Ruby distribution, from 1.8.2 onwards.)
+#
+
require 'thread'
+#
+# A module to implement the Linda programming paradigm in Ruby.
+# This is part of +drb+ (dRuby).
+#
module Rinda
class RequestCanceledError < ThreadError; end
class RequestExpiredError < ThreadError; end
+ #
+ # A tuple is the elementary object in Rinda programming.
+ # Tuples may be matched against templates if the tuple and
+ # the template are the same size.
+ #
class Tuple
+ # Initialize a tuple with an Array or a Hash.
def initialize(ary_or_hash)
if Hash === ary_or_hash
init_with_hash(ary_or_hash)
@@ -13,14 +35,18 @@ module Rinda
end
end
+ # The number of elements in the tuple.
def size
@tuple.size
end
+ # Accessor method for elements of the tuple.
def [](k)
@tuple[k]
end
+ # Iterate through the tuple, yielding the index or key, and the
+ # value, thus ensuring arrays are iterated similarly to hashes.
def each # FIXME
if Hash === @tuple
@tuple.each { |k, v| yield(k, v) }
@@ -29,6 +55,7 @@ module Rinda
end
end
+ # Return the tuple itself -- i.e the Array or hash.
def value
@tuple
end
@@ -52,7 +79,13 @@ module Rinda
end
end
+ #
+ # Templates are used to match tuples in Rinda.
+ #
class Template < Tuple
+ # Perform the matching of a tuple against a template. An
+ # element with a +nil+ value in a template acts as a wildcard,
+ # matching any value in the corresponding position in the tuple.
def match(tuple)
return false unless tuple.respond_to?(:size)
return false unless tuple.respond_to?(:[])
@@ -64,11 +97,15 @@ module Rinda
return true
end
+ # Alias for #match.
def ===(tuple)
match(tuple)
end
end
+ #
+ # <i>Documentation?</i>
+ #
class DRbObjectTemplate
def initialize(uri=nil, ref=nil)
@drb_uri = uri
@@ -87,6 +124,9 @@ module Rinda
end
end
+ #
+ # TupleSpaceProxy allows a remote Tuplespace to appear as local.
+ #
class TupleSpaceProxy
def initialize(ts)
@ts = ts
@@ -115,6 +155,9 @@ module Rinda
end
end
+ #
+ # <i>Documentation?</i>
+ #
class SimpleRenewer
include DRbUndumped
def initialize(sec=180)
diff --git a/lib/rinda/tuplespace.rb b/lib/rinda/tuplespace.rb
index e538f6b..d30a504 100644
--- a/lib/rinda/tuplespace.rb
+++ b/lib/rinda/tuplespace.rb
@@ -1,9 +1,21 @@
+#
+# = tuplespace: <i>???</i>
+#
+# <i>Overview of rinda/tuplespace.rb</i>
+#
+# <i>Example(s)</i>
+#
+
require 'monitor'
require 'thread'
require 'drb/drb'
require 'rinda/rinda'
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
@@ -23,8 +35,13 @@ module Rinda
!canceled? && !expired?
end
+ # Return the object which makes up the tuple itself: the Array
+ # or Hash.
def value; @ary.value; end
+
def canceled?; @cancel; end
+
+ # Has this tuple expired? (true/false).
def expired?
return true unless @expires
return false if @expires > Time.now
@@ -34,11 +51,28 @@ module Rinda
return @expires < Time.now
end
+ # Reset the expiry data according to the supplied argument. If
+ # the argument is:
+ #
+ # +nil+:: it is set to expire in the far future.
+ # +false+:: it has epired.
+ # Numeric:: it will expire in that many seconds.
+ #
+ # 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
+ # Create an expiry time. Called with:
+ #
+ # +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)
+ #
+ # otherwise it is +sec+ seconds into the
+ # future.
def make_expires(sec=nil)
case sec
when Numeric
@@ -50,19 +84,25 @@ module Rinda
end
end
+ # Accessor method for the tuple.
def [](key)
@ary[key]
end
+ # The size of the tuple.
def size
@ary.size
end
+ # Create a new tuple from the supplied object (array-like).
def make_tuple(ary)
Rinda::Tuple.new(ary)
end
private
+ # Given +true+, +nil+, or +Numeric+, returns that (suitable input to
+ # make_epires) and +nil+ (no actual +renewer+), else it return the
+ # time data from the supplied +renewer+.
def get_renewer(it)
case it
when Numeric, true, nil
@@ -77,6 +117,9 @@ module Rinda
end
end
+ #
+ # The same as a TupleEntry but with methods to do matching.
+ #
class TemplateEntry < TupleEntry
def initialize(ary, expires=nil)
super(ary, expires)
@@ -87,15 +130,20 @@ module Rinda
@template.match(tuple)
end
+ # An alias for #match.
def ===(tuple)
match(tuple)
end
+ # Create a new Template from the supplied object.
def make_tuple(ary)
Rinda::Template.new(ary)
end
end
+ #
+ # <i>Documenation?</i>
+ #
class WaitTemplateEntry < TemplateEntry
def initialize(place, ary, expires=nil)
super(ary, expires)
@@ -126,6 +174,9 @@ module Rinda
end
end
+ #
+ # <i>Documenation?</i>
+ #
class NotifyTemplateEntry < TemplateEntry
def initialize(place, event, tuple, expires=nil)
ary = [event, Rinda::Template.new(tuple)]
@@ -156,40 +207,52 @@ module Rinda
end
end
+ #
+ # TupleBag is an unordered collection of tuples. It is the basis
+ # of Tuplespace.
+ #
class TupleBag
def initialize
@hash = {}
end
+ # Add the object to the TupleBag.
def push(ary)
size = ary.size
@hash[size] ||= []
@hash[size].push(ary)
end
+ # Remove the object from the TupleBag.
def delete(ary)
size = ary.size
@hash.fetch(size, []).delete(ary)
end
+ # Finds all tuples that match the template and are alive.
def find_all(template)
@hash.fetch(template.size, []).find_all do |tuple|
tuple.alive? && template.match(tuple)
end
end
+ # Finds a template that matches and is alive.
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 the supplied 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 are not alive from the TupleBag. Returns
+ # the list of tuples so deleted.
def delete_unless_alive
deleted = []
@hash.keys.each do |size|
@@ -207,20 +270,24 @@ module Rinda
end
end
+ #
+ # The Tuplespace manages access to the tuples it contains,
+ # ensuring mutual exclusion requirments are met.
+ #
class TupleSpace
include DRbUndumped
include MonitorMixin
- def initialize(timeout=60)
+ def initialize(period=60)
super()
@bag = TupleBag.new
@read_waiter = TupleBag.new
@take_waiter = TupleBag.new
@notify_waiter = TupleBag.new
- @timeout = timeout
- @period = timeout * 2
+ @period = period
@keeper = keeper
end
+ # Put a tuple into the tuplespace.
def write(tuple, sec=nil)
entry = TupleEntry.new(tuple, sec)
synchronize do
@@ -244,6 +311,7 @@ module Rinda
entry
end
+ # Remove an entry from the Tuplespace.
def take(tuple, sec=nil, &block)
move(nil, tuple, sec, &block)
end