facets 0.7.2 → 0.9.0

data/lib/mega/interval.rb

@@ -0,0 +1,426 @@
+#--
+# Interval
+#
+# Copyright (c) 2004,2005 Thomas Sawyer
+#
+# Ruby License
+#
+# This module is free software. You may use, modify, and/or redistribute this
+# software under the same terms as Ruby.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+#
+# ==========================================================================
+# Revision History ::
+# --------------------------------------------------------------------------
+#  04.06   Trans    * Minor modifications to documentation.
+# ==========================================================================
+#
+# :NOTE: Still need to tie in Infinity.
+#
+#++
+
+#:title: Interval
+#
+# While Ruby support the Range class out of the box, is does not quite
+# fullfil the role od a real Interval class. For instance, it does
+# not support excluding the front sentinel. This is because Range
+# also tries to do triple duty as a simple Sequence and as a simple Tuple-Pair,
+# thus limiting its potential as an Interval. The Interval class remedies
+# the situation by commiting to interval behavior, and then extends the class'
+# capabilites beyond that of the standard Range in ways that naturally
+# fall out of that.
+#
+# Range depends on two methods: #succ and #<=>. If numeric
+# ranges were the only concern, those could just as well be #+ and #<=>,
+# but esoteric forms make that unfeasible --the obvious example being a String
+# range. But a proper Interval class requires mathematical continuation,
+# thus the Interval depends on #+ and #<=>, as well as #- as the inverse of #+.
+#
+# == Synopsis
+#
+#   require 'mega/interval'
+#
+#   i = Interval.new(1,5)
+#   i.to_a       #=> [1,2,3,4,5]
+#
+#   i = Interval[0,5]
+#   i.to_a(2)    #=> [0,2,4]
+#
+#   i = Interval[1,5]
+#   i.to_a(-1)   #=> [5,4,3,2,1]
+#
+#   i = Interval[1,3]
+#   i.to_a(1,2)  #=> [1.0,1.5,2.0,2.5,3.0]
+#
+# == Author(s)
+#
+# * Thomas Sawyer
+#
+
+require 'mega/multiton'
+require 'mega/enumerable_args'
+#require 'mega/infinity'
+
+class Interval
+
+  include Multiton::New
+  include EnumerableArgs
+
+  def self.[]( *args )
+    self.new( *args )
+  end
+
+  def initialize(first, last, exclude_first=false, exclude_last=false )
+    raise ArgumentError, "bad value for interval" if first.class != last.class
+    @first = first
+    @last = last
+    @exclude_first = exclude_first
+    @exclude_last = exclude_last
+    @direction = (@last <=> @first)
+  end
+
+  # Returns a two element array of first and last sentinels.
+  #
+  #  (0..10).sentinels   #=> [0,10]
+  #
+  def sentinels
+    return [@first, @last]
+  end
+
+  # Returns the first or last sentinal of the interval.
+  def first ; @first ; end
+  def last ; @last ; end
+
+  #
+  def exclude_first? ; @exclude_first ; end
+  def exclude_last? ; @exclude_last ; end
+
+  # (IMHO) these should be deprectated
+  alias_method( :begin, :first )
+  alias_method( :end, :last )
+  alias_method( :exclude_begin?, :exclude_first? )
+  alias_method( :exclude_end?, :exclude_last? )
+
+  # Returns +true+ if the start and end sentinels are equal and the interval is closed; otherwise +false+.
+  def degenerate? ; @direction == 0 and ! (@exclusive_first or @exclusive_last) ;  end
+
+  # Returns +true+ if the start and end sentinels are equal and the interval is open; otherwise +false+.
+  def null? ; @direction == 0 and @exclusive_first and @exclusive_last ; end
+
+  # Returns the direction of the interval indicated by +1, 0 or -1.
+  #
+  #   (1..5).direction  #=> 1
+  #   (5..1).direction  #=> -1
+  #   (1..1).direction  #=> 0
+  #
+  def direction ; @direction ; end
+
+  # Returns a new interval inclusive of of both sentinels.
+  def closed; Interval.new(@first, @last, true, true) ; end
+
+  # Returns a new interval exclusive of both sentinels.
+  def opened; Interval.new(@first, @last, true, true) ; end
+
+  # Returns a new interval with either the first or the last sentinel exclusive.
+  # If the parameter is false, the deafult, then the first sentinel is excluded;
+  # if the parameter is true, the last sentinel is excluded.
+  def half_closed(e=false)
+    e ? Interval.new(@first, @last, true, false) : Interval.new(@first, @last, false, true)
+  end
+  
+  # Returns a new interval with one of the two sentinels opened or closed
+  def first_closed ; Interval.new(@first, @last, false, true) ; end
+  def last_closed ; Interval.new(@first, @last, true, false) ; end
+  def first_opened ; Interval.new(@first, @last, true, false) ; end
+  def last_opened ; Interval.new(@first, @last, false, true) ; end
+  
+  # Unary shorthands. These return a new interval exclusive of first,
+  # last or both sentinels, repectively.
+  def +@ ; Interval.new(first, last, true, false) ; end
+  def -@ ; Interval.new(first, last, false, true) ; end
+  def ~@ ; Interval.new(first, last, true, true) ; end
+
+  # Returns a new interval with the sentinels reversed.
+  #
+  #   (0..10).reversed  #=> 10..0
+  #
+  def reversed
+    Interval.new(@last, @first, true, true)
+  end
+  
+  # Returns the length of the interval as the difference between
+  # the first and last elements. Returns +nil+ if the sentinal objects
+  # do not support distance comparison (#distance).
+  # TODO: Add +n+ parameter to count segmentations like those produced by #each.
+  def distance
+    @last - @first
+    #if @last.respond_to?( :distance )
+    #  @last.distance( @first )
+    #else
+    #  #self.to_a.length
+    #end
+  end
+  alias_method( :length, :distance )
+  alias_method( :size, :distance )
+
+  # Returns the lesser of the first and last sentinals.
+  def min
+    ((@first <=> @last) == -1) ? @first : @last
+  end
+
+  # Returns the greater of the first and last sentinals.
+  def max
+    ((@first <=> @last) == 1) ? @first : @last
+  end
+
+  # Returns true or false if the element is part of the interval.
+  def include?(x)
+    # todo: infinity?   
+    tf = exclude_first? ? 1 : 0
+    tl = exclude_last? ? -1 : 0
+    (x <=> first) >= tf and (x <=> last) <= tl
+  end
+  alias_method( :===, :include? )
+  alias_method( :member?, :include? )
+
+=begin
+#     def include?(x)
+#       tf = exclude_first? ? 1 : 0
+#       tl = exclude_last? ? -1 : 0
+#       # if other classes handled Infinity in their <=> method
+#       # (which probably they should) this clause would not be required
+#       if first.kind_of?(InfinityClass)
+#         ft = ((first <=> x) <= tf)
+#       else
+#         ft = (x <=> first) >= tf
+#       end
+#       if last.kind_of?(InfinityClass)
+#         fl = ((last <=> x) >= tl)
+#       else
+#         fl = (x <=> last) <= tl
+#       end
+#       ft && fl
+#     end
+=end
+
+  # Iterates over the interval, passing each _n_th element to the block. 
+  # If n is not given then n defaults to 1. Each _n_th step is determined
+  # by invoking +\++ or +\-+ n, depending on the direction of the interval.
+  # If n is negative the iteration is preformed in reverse form end sentinal
+  # to front sentinal. A second parameter, d, can be given in which case
+  # the applied step is calculated as a fraction of the interval's length
+  # times n / d. This allows iteration over the whole interval in equal sized
+  # segments.
+  #
+  #   1..5.each { |e| ... }        #=> 1 2 3 4 5
+  #   1..5.each(2) { |e| ... }     #=> 1 3 5
+  #   1..5.each(1,2) { |e| ... }   #=> 1.0 1.5 2.0 2.5 3.0 3.5 4.0 4.5 5.0
+  #
+  def each(n=1, d=nil)  # :yield:   
+    return (n < 0 ? @last : @first) if degenerate?  # is this right for all values of n ?
+    s = d ? self.length.to_f * (n.to_f / d.to_f) : n.abs
+    raise "Cannot iterate over zero length steps." if s == 0
+    s = s * @direction
+    if n < 0
+      e = @exclude_last ? @last - s : @last
+      #e = @exclude_last ? @last.pred(s) : @last
+      t = @exlude_last ? 1 : 0
+      #while e.cmp(@first) >= t
+      while (e <=> @first) >= t
+        yield(e)
+        e -= s
+        #e = e.pred(s)
+      end
+    else
+      e = @exclude_first ? @first + s : @first
+      #e = @exclude_first ? @first.succ(s) : @first
+      t = @exlude_last ? -1 : 0
+      #while e.cmp(@last) <= t
+      while (e <=> @last) <= t
+        yield(e)
+        e += s
+        #e = e.succ(s)
+      end
+    end
+  end
+  alias_method( :step, :each )
+
+  # Should there be a #reverse_each ?
+  # Since #each can now take a negative argument, this isn't really needed.
+  # Should it exist anyway and routed to #each?
+  # Also, alias_method( :reverse_step, :reverse_each )
+
+  # Compares two intervals to see if they are equal
+  def eql?(other)
+    return false unless @first == other.first
+    return false unless @last == other.last
+    return false unless @exclude_first == other.exclude_first?
+    return false unless @exclude_last == other.exclude_last?
+    true
+  end
+
+end
+
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+
+=begin testing
+
+  require 'test/unit'
+
+  class InclusiveTest < Test::Unit::TestCase
+
+    def setup
+      @a = Interval.new( 1, 10 )
+      @b = Interval.new( 1, 10, true, false )
+      @c = Interval.new( 1, 10, false, true )
+      @d = Interval.new( 1, 10, true, true )
+    end
+
+    def test_001A ; assert_equal( false, @a.include?(0)  ) ; end
+    def test_002A ; assert_equal( true,  @a.include?(1)  ) ; end
+    def test_003A ; assert_equal( true,  @a.include?(2)  ) ; end
+    def test_004A ; assert_equal( true,  @a.include?(9)  ) ; end
+    def test_005A ; assert_equal( true,  @a.include?(10) ) ; end
+    def test_006A ; assert_equal( false, @a.include?(11) ) ; end
+
+    def test_001B ; assert_equal( false, @b.include?(0)  ) ; end
+    def test_002B ; assert_equal( false, @b.include?(1)  ) ; end
+    def test_003B ; assert_equal( true,  @b.include?(2)  ) ; end
+    def test_004B ; assert_equal( true,  @b.include?(9)  ) ; end
+    def test_005B ; assert_equal( true,  @b.include?(10) ) ; end
+    def test_006B ; assert_equal( false, @b.include?(11) ) ; end
+
+    def test_001C ; assert_equal( false, @c.include?(0)  ) ; end
+    def test_002C ; assert_equal( true,  @c.include?(1)  ) ; end
+    def test_003C ; assert_equal( true,  @c.include?(2)  ) ; end
+    def test_004C ; assert_equal( true,  @c.include?(9)  ) ; end
+    def test_005C ; assert_equal( false, @c.include?(10) ) ; end
+    def test_006C ; assert_equal( false, @c.include?(11) ) ; end
+
+    def test_001D ; assert_equal( false, @d.include?(0)  ) ; end
+    def test_002D ; assert_equal( false, @d.include?(1)  ) ; end
+    def test_003D ; assert_equal( true,  @d.include?(2)  ) ; end
+    def test_004D ; assert_equal( true,  @d.include?(9)  ) ; end
+    def test_005D ; assert_equal( false, @d.include?(10) ) ; end
+    def test_006D ; assert_equal( false, @d.include?(11) ) ; end
+
+  end
+
+  class LrgNumericTest < Test::Unit::TestCase
+
+    def setup
+      @a = Interval.new(0,100000000)
+      @b = Interval.new(0,100000000)
+    end
+
+    def test_001A ; assert_equal( true,  @a.include?(0)         ) ; end
+    def test_002A ; assert_equal( true,  @a.include?(1000)      ) ; end
+    def test_003A ; assert_equal( true,  @a.include?(1000000)   ) ; end
+    def test_004A ; assert_equal( true,  @a.include?(100000000) ) ; end
+    #def test_005A ; assert_equal( false, @a.include?(INFINITY)  ) ; end
+
+    def test_001B ; assert_equal( true,  @b.include?(0)         ) ; end
+    def test_002B ; assert_equal( true,  @b.include?(5)         ) ; end
+    def test_002B ; assert_equal( true,  @b.include?(70007)     ) ; end
+    def test_002B ; assert_equal( true,  @b.include?(5000005)   ) ; end
+    #def test_002B ; assert_equal( false, @b.include?(INFINITY)  ) ; end
+
+  end
+
+  class SelectTest < Test::Unit::TestCase
+
+    def setup
+      @a = Interval.new( 0,10 )
+    end
+
+    def test_001
+      b = @a.collect( 2 ){ |n| n }
+      assert_equal( [0,2,4,6,8,10], b )
+    end
+
+    def test_002
+      b = @a.select{ |n| n % 2 == 0 }
+      assert_equal( [0,2,4,6,8,10], b )
+    end
+
+    def test_003
+      b = @a.collect( 1,2 ){ |n| n }
+      assert_equal( [0,5,10], b )
+    end
+
+    def test_004
+      b = @a.select( 1,2 ){ |n| n % 2 == 0 }
+      assert_equal( [0,10], b )
+    end
+
+  end
+
+  class ArrayTest < Test::Unit::TestCase
+
+    def setup
+      @a = Interval.new( 0,10 ) 
+      @b = Interval.new( 0,1 ) 
+    end
+
+    def test_001A ; assert_equal( [0,5,10], @a.to_a(1,2) ) ; end
+
+    def test_001B ; assert_equal( [0, 0.25, 0.5, 0.75, 1.0], @b.to_a(1,4) ) ; end
+
+  end
+
+=end
+
+=begin
+  class InfTest < Test::Unit::TestCase
+
+    def setup
+      @a = Interval.new( -INFINITY, -3 )
+      @b = Interval.new( -INFINITY, -3, true, false )
+      @c = Interval.new( -3, INFINITY )
+      @d = Interval.new( -INFINITY, INFINITY )
+      @e = Interval.new( -3, -2 )
+    end
+
+    def test_001A ; assert_equal( true,  @a.include?(-INFINITY) ) ; end
+    def test_002A ; assert_equal( true,  @a.include?(-4)        ) ; end
+    def test_003A ; assert_equal( true,  @a.include?(-3)        ) ; end
+    def test_004A ; assert_equal( false, @a.include?(-2)        ) ; end
+    def test_005A ; assert_equal( false, @a.include?(INFINITY)  ) ; end
+
+    def test_001B ; assert_equal( true,  @b.include?(-INFINITY) ) ; end
+    def test_002B ; assert_equal( true,  @b.include?(-4)        ) ; end
+    def test_003B ; assert_equal( false, @b.include?(-3)        ) ; end
+    def test_004B ; assert_equal( false, @b.include?(-2)        ) ; end
+    def test_005B ; assert_equal( false, @b.include?(INFINITY)  ) ; end
+
+    def test_001C ; assert_equal( false, @c.include?(-INFINITY) ) ; end
+    def test_002C ; assert_equal( false, @c.include?(-4)        ) ; end
+    def test_003C ; assert_equal( true,  @c.include?(-3)        ) ; end
+    def test_004C ; assert_equal( true,  @c.include?(-2)        ) ; end
+    def test_005C ; assert_equal( true,  @c.include?(INFINITY)  ) ; end
+
+    def test_001D ; assert_equal( true,  @d.include?(-INFINITY) ) ; end
+    def test_002D ; assert_equal( true,  @d.include?(-4)        ) ; end
+    def test_003D ; assert_equal( true,  @d.include?(-3)        ) ; end
+    def test_004D ; assert_equal( true,  @d.include?(-2)        ) ; end
+    def test_005D ; assert_equal( true,  @d.include?(INFINITY)  ) ; end
+
+    def test_001E ; assert_equal( false, @e.include?(-INFINITY) ) ; end
+    def test_002E ; assert_equal( false, @e.include?(-4)        ) ; end
+    def test_003E ; assert_equal( true,  @e.include?(-3)        ) ; end
+    def test_004E ; assert_equal( true,  @e.include?(-2)        ) ; end
+    def test_005E ; assert_equal( false, @e.include?(INFINITY)  ) ; end
+
+  end
+=end

data/lib/mega/ioreactor.rb

@@ -0,0 +1,671 @@
+#--
+# IOReactor
+#
+# Copyright (c) 2002, 2003 The FaerieMUD Consortium. All rights reserved.
+#
+# Ruby License
+#
+# This module is free software. You may use, modify, and/or redistribute this
+# software under the same terms as Ruby.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+#
+# ==========================================================================
+# Revision History ::
+# --------------------------------------------------------------------------
+#  04.12  Trans    * Minor modifications to documentation.
+# ==========================================================================
+#++
+
+#:title: IOReactor
+#
+# An object-oriented multiplexing asynchronous IO mechanism for Ruby.
+# It is an implementation of the Reactor design pattern for multiplexed
+# asynchronous single-thread IO.
+#
+# == Details
+#
+# This module is a pure-Ruby implementation of an asynchronous multiplexed IO
+# Reactor which is based on the Reactor design pattern found in _Pattern-Oriented
+# Software Architecture, Volume 2: Patterns for Concurrent and Networked
+# Objects_. It allows a single thread to demultiplex and dispatch events from one
+# or more IO objects to the appropriate handler.
+#
+# This module used to be called Ruby-Poll, and used to use the poll(2) system
+# call, but this strategy was not portable, and didn't work with Ruby's
+# threads. It now uses IO::select, which should work everywhere Ruby does.
+#
+# I would greatly appreciate feedback on any aspect of this software. Suggestions,
+# feature requests, questions, design critiques, and bug reports are most
+# welcome. Relevant patches and minimal test cases are particularly helpful. I may
+# be reached by email at <ged@FaerieMUD.org>.
+#
+# == Synopsis
+#
+#   require 'mega/ioreactor'
+#   require 'socket'
+#
+#   reactorobj = IOReactor.new
+#
+#   # Open a listening socket on port 1138 and register it with the
+#   # reactor. When a :read event occurs on it, it means an incoming
+#   # connection has been established
+#   sock = TCPServer::new('localhost', 1138)
+#   reactorobj.register( sock, :read ) {|sock,event|
+#       case event
+#       # Accept the incoming connection, registering it also with
+#       # the reactor; events on client sockets are handled by the
+#       # #clientHandler method.
+#       when :read
+#           clsock = sock.accept
+#           reactorobj.register( clsock, :read, :write, &method(:clientHandler) )
+#       # Errors on the main listening socket cause the whole
+#       # reactor to be shut down
+#       when :error
+#           reactorobj.clear
+#           $stderr.puts "Server error: Shutting down"
+#       else
+#           $stderr.puts "Unhandled event: #{event}"
+#       end
+#   }
+#   # Drive the reactor until it's empty with a single thread
+#   Thread::new { reactorobj.poll until reactorobj.empty? }
+#
+# == More Information
+#
+# You can find more information about IO-Reactor, including the latest version, at
+# its project page:
+#
+#   http://www.devEiate.org/code/IO-Reactor.shtml
+#
+# == Author(s)
+#
+# * Michael Granger <ged#FaerieMUD.org>
+#
+
+require 'delegate'
+require 'rbconfig'
+
+### An object-oriented multiplexing asynchronous IO reactor class.
+class IOReactor
+
+    ### Class constants
+    Version = /([\d\.]+)/.match( %q{$Revision: 1.13 $} )[1]
+    Rcsid = %q$Id: reactor.rb,v 1.13 2003/08/04 23:56:14 deveiant Exp $
+
+    ValidEvents = [:read, :write, :error]
+
+    ### Create and return a new IO reactor object.
+    def initialize
+        @handles        = Hash::new {|hsh,key|
+            hsh[ key ] = {
+                :events        => [],
+                :handler    => nil,
+                :args        => [],
+            }
+        }
+        @pendingEvents    = Hash::new {|hsh,key| hsh[ key ] = []}
+    end
+
+
+    ######
+    public
+    ######
+
+    # The Hash of handles (instances of IO or its subclasses) associated with
+    # the reactor. The keys are the IO objects, and the values are a Hash of
+    # event/s => handler.
+    attr_reader :handles
+
+    # The Hash of unhandled events which occurred in the last call to #poll,
+    # keyed by handle.
+    attr_reader :pendingEvents
+
+
+    ### Register the specified IO object with the reactor for events given as
+    ### <tt>args</tt>. The reactor will test the given <tt>io</tt> for the
+    ### events specified whenever #poll is called. See the #poll method for a
+    ### list of valid events. If no events are specified, only <tt>:error</tt>
+    ### events will be polled for.
+    ###
+    ### If a <tt>handler</tt> is specified, it will be called whenever the
+    ### <tt>io</tt> has any of the specified <tt>events</tt> occur to it. It
+    ### should take at least two parameters: the <tt>io</tt> and the event.
+    ###
+    ### If +args+ contains any objects except the Symbols '<tt>:read</tt>',
+    ### '<tt>:write</tt>', or '<tt>:error</tt>', and a +handler+ is specified,
+    ### they will be saved and passed to handler for each event.
+    ### 
+    ### Registering a handle will unregister any previously registered
+    ### event/handler+arguments pairs associated with the handle.
+    def register( io, *args, &handler )
+        events = [:read, :write, :error] & args
+        args -= events
+
+        self.unregister( io )
+        self.enableEvents( io, *events )
+        if handler
+            self.setHandler( io, *args, &handler )
+        else
+            self.setArgs( io, *args )
+        end
+
+        return self
+    end
+    alias_method :add, :register
+
+
+    ### Add the specified +events+ to the list that will be polled for on the
+    ### given +io+ handle.
+    def enableEvents( io, *events )
+        @handles[ io ][:events] |= events
+    end
+
+
+    ### Remove the specified +events+ from the list that will be polled for on
+    ### the given +io+ handle.
+    def disableEvents( io, *events )
+        raise RuntimeError, "Cannot disable the :error event" if
+            events.include?( :error )
+        @handles[ io ][:events] -= events
+    end
+
+
+    ### Set the handler for events on the given +io+ handle to the specified
+    ### +handler+. If any +args+ are present, they will be passed as an exploded
+    ### array to the handler for each event. Returns the previously-registered
+    ### handler, if any.
+    def setHandler( io, *args, &handler )
+        rval = @handles[ io ][:handler]
+        @handles[ io ][:handler] = handler
+        self.setArgs( io, *args )
+        return rval
+    end
+
+
+    ### Remove and return the handler for events on the given +io+ handle.
+    def removeHandler( io )
+        rval = @handles[ io ][:handler]
+        @handles[ io ][:handler] = nil
+        self.removeArgs( io )
+        return rval
+    end
+
+
+    ### Set the additional arguments to pass to the handler for the given +io+
+    ### handle on each event to the given +args+.
+    def setArgs( io, *args )
+        rval = @handles[ io ][:args]
+        @handles[ io ][:args] = args
+        return rval
+    end
+
+
+    ### Remove the arguments for the given handle to the given +args+.
+    def removeArgs( io )
+        return @handles[ io ][:args].clear
+    end
+
+
+    ### Remove the specified <tt>io</tt> from the receiver's list of registered
+    ### handles, if present. Returns the handle if it was registered, or
+    ### <tt>nil</tt> if it was not.
+    def unregister( io )
+        @pendingEvents.delete( io )
+        @handles.delete( io )
+    end
+    alias_method :remove, :unregister
+
+
+    ### Returns true if the specified <tt>io</tt> is registered with the poll
+    ### object.
+    def registered?( io )
+        return @handles.has_key?( io )
+    end
+
+
+    ### Clear all registered handles from the poll object. Returns the handles
+    ### that were cleared.
+    def clear
+        rv = @handles.keys
+
+        @pendingEvents.clear
+        @handles.clear
+
+        return rv
+    end
+
+
+    
+    ### Poll the handles registered to the reactor for pending events. The
+    ### following event types are defined:
+    ###
+    ### [<tt>:read</tt>]
+    ###   Data may be read from the handle without blocking.
+    ### [<tt>:write</tt>]
+    ###   Data may be written to the handle without blocking.
+    ### [<tt>:error</tt>]
+    ###   An error has occurred on the handle. This event type is always
+    ###   enabled, regardless of whether or not it is passed as one of the
+    ###   <tt>events</tt>.
+    ###
+    ### Any handlers specified when the handles were registered are run for
+    ### those handles with events. If a block is given, it will be invoked once
+    ### for each handle which doesn't have an explicit handler. If no block is
+    ### given, events without explicit handlers are inserted into the reactor's
+    ### <tt>pendingEvents</tt> attribute.
+    ###
+    ### The <tt>timeout</tt> argument is the number of floating-point seconds to
+    ### wait for an event before returning (ie., fourth argument to the
+    ### underlying <tt>select()</tt> call); negative timeout values will cause
+    ### #poll to block until there is at least one event to report.
+    ###
+    ### This method returns the number of handles on which one or more events
+    ### occurred.
+    def poll( timeout=-1 ) # :yields: io, eventMask
+        timeout = timeout.to_f
+        @pendingEvents.clear
+        count = 0
+
+        unless @handles.empty?
+            timeout = nil if timeout < 0
+            eventedHandles = self.getPendingEvents( timeout )
+
+            # For each event of each io that had an event happen, call any
+            # associated callback, or any provided block, or failing both of
+            # those, add the event to the hash of unhandled pending events.
+            eventedHandles.each {|io,events|
+                count += 1
+                events.each {|ev|
+                    args = @handles[ io ][:args]
+
+                    if @handles[ io ][:handler]
+                        @handles[ io ][:handler].call( io, ev, *args )
+                    elsif block_given?
+                        yield( io, ev, *args )
+                    else
+                        @pendingEvents[io].push( ev )
+                    end
+                }
+            }
+        end
+
+        return count
+    end
+
+
+    ### Returns <tt>true</tt> if no handles are associated with the receiver.
+    def empty?
+        @handles.empty?
+    end
+
+
+    #########
+    protected
+    #########
+
+    ### Select on the registered handles, returning a Hash of handles => events
+    ### for handles which had events occur.
+    def getPendingEvents( timeout )
+        eventHandles = IO::select( self.getReadHandles, self.getWriteHandles,
+            @handles.keys, timeout ) or return {}
+        eventHash = Hash::new {|hsh,io| hsh[io] = []}
+
+        # Fill in the hash with pending events of each type
+        [:read, :write, :error].each_with_index {|event,i|
+            eventHandles[i].each {|io| eventHash[io].push( event )}
+        }
+        return eventHash
+    end
+
+
+    ### Return an Array of handles which have handlers for the <tt>:read</tt>
+    ### event.
+    def getReadHandles
+        @handles.
+            find_all {|io,hsh| hsh[:events].include?( :read )}.
+            collect {|io,hsh| io}
+    end
+
+
+    ### Return an Array of handles which have handlers for the <tt>:write</tt>
+    ### event.
+    def getWriteHandles
+        @handles.
+            find_all {|io,hsh| hsh[:events].include?( :write )}.
+            collect {|io,hsh| io}
+    end
+
+
+end # class IO::Reactor
+
+
+
+=begin
+
+== ChangeLog
+
+* 2003-07-21 09:04  Michael Granger <ged@FaerieMUD.org>
+
+    * README (1.5, RELEASE_0_04):
+
+    - Changed to IO::Reactor.
+    
+* 2003-07-21 08:21  Michael Granger <ged@FaerieMUD.org>
+
+    * install.rb (1.1, RELEASE_0_04):
+
+    Initial checkin.
+    
+* 2003-07-21 00:55  Michael Granger <ged@FaerieMUD.org>
+
+    * test.rb (1.7), utils.rb (1.4), examples/chatserver.rb (1.3),
+    lib/io/reactor.rb (1.11), CATALOG (1.2) (utags: RELEASE_0_04):
+
+    - Refactored into IO::Reactor from Ruby-Poll.
+    
+* 2003-07-21 00:54  Michael Granger <ged@FaerieMUD.org>
+
+    * extconf.rb (1.6), poll.c (1.6), lib/poll.rb (1.11):
+
+    - Removed for IO::Reactor, which no longer needs a C backend.
+    
+* 2003-05-08 16:49  Michael Granger <ged@FaerieMUD.org>
+
+    * makesitedocs.rb (1.3, RELEASE_0_04):
+
+    makesitedocs.rb
+    
+* 2003-04-20 22:37  Michael Granger <ged@FaerieMUD.org>
+
+    * test.rb (1.6):
+
+    Added workaround for recent versions of Test::Unit's API changes.
+    
+* 2003-04-20 22:34  Michael Granger <ged@FaerieMUD.org>
+
+    * poll.c (1.5):
+
+    Added code for simulating poll(2) with rb_thread_select() for machines without a native poll(). Based on code for Freehaven by
+    Nick Mathewson <nickm@freehaven.net>.
+    
+* 2003-04-20 22:32  Michael Granger <ged@FaerieMUD.org>
+
+    * extconf.rb (1.5):
+
+    Added fake poll code to allow machines without a poll(2) to use the library. This also might become the primary method of polling, sadly, as Ruby doesn't tolerate other async IO methods very well due to its use of select() for its threading.
+    
+* 2002-10-20 21:47  Michael Granger <ged@FaerieMUD.org>
+
+    * lib/: poll.rb (1.10), io/reactor.rb (1.10) (utags: RELEASE_0_03):
+
+    - Got rid of a type-checking statement, as it didn't account for using an IO
+      inside a wrappered or delegated object.
+    
+    - Fixed use of deprecated 'type' method.
+    
+* 2002-09-18 06:33  Michael Granger <ged@FaerieMUD.org>
+
+    * makedocs.rb (1.3, RELEASE_0_04, RELEASE_0_03, RELEASE_0_02):
+
+    - Removed dependence on as-yet-undistributed xhtml RDoc template.
+    
+* 2002-09-06 10:52  Michael Granger <ged@FaerieMUD.org>
+
+    * poll.c (1.4, RELEASE_0_03, RELEASE_0_02):
+
+    - Added interrupt-handling to the _poll call.
+    
+    - Added more-informative debugging.
+    
+* 2002-07-20 10:07  Michael Granger <ged@FaerieMUD.org>
+
+    * lib/: poll.rb (1.9), io/reactor.rb (1.9) (utags: RELEASE_0_02):
+
+    - New method: #setMask().
+    
+    - New method: #callback().
+    
+    - New method: #args().
+    
+    - Implemented the #register() method in terms of the other setter methods to
+      consolidate the maintenance of internal data structures.
+    
+    - Added missing callback *args to #setCallback().
+    
+    - Cleared up documentation for #register.
+    
+* 2002-07-20 10:03  Michael Granger <ged@FaerieMUD.org>
+
+    * examples/chatserver.rb (1.2, RELEASE_0_03, RELEASE_0_02):
+
+    - Changed name of user class to 'User' to avoid confusion about its role in the
+      server.
+    
+* 2002-07-20 10:01  Michael Granger <ged@FaerieMUD.org>
+
+    * test.rb (1.5, RELEASE_0_03, RELEASE_0_02):
+
+    - Added test for the #callback method.
+    
+* 2002-07-20 10:01  Michael Granger <ged@FaerieMUD.org>
+
+    * makedocs.rb (1.2):
+
+    - Added template argument to make it use the xhtml template.
+    
+* 2002-07-19 10:29  Michael Granger <ged@FaerieMUD.org>
+
+    * lib/: poll.rb (1.8), io/reactor.rb (1.8):
+
+    - Fixed a funny typo.
+    
+* 2002-07-18 21:58  Michael Granger <ged@FaerieMUD.org>
+
+    * CATALOG (1.1, RELEASE_0_03, RELEASE_0_02):
+
+    Initial commit.
+    
+* 2002-07-18 21:58  Michael Granger <ged@FaerieMUD.org>
+
+    * utils.rb (1.3, RELEASE_0_03, RELEASE_0_02):
+
+    - Fixed typo in vetManifest()
+    
+    - Added case to read the documentation CATALOG in the base directory if it's not
+      in the docs/ directory.
+    
+* 2002-07-18 21:55  Michael Granger <ged@FaerieMUD.org>
+
+    * makesitedocs.rb (1.2, RELEASE_0_03, RELEASE_0_02):
+
+    - Merged some of the features from the MUES doc-gen script.
+    
+* 2002-07-18 21:52  Michael Granger <ged@FaerieMUD.org>
+
+    * lib/: poll.rb (1.7), io/reactor.rb (1.7):
+
+    - Added callback arguments to the register() method.
+    
+* 2002-07-18 21:52  Michael Granger <ged@FaerieMUD.org>
+
+    * test.rb (1.4):
+
+    - Added test for new "with-args" register() method call.
+    
+* 2002-07-18 09:42  Michael Granger <ged@FaerieMUD.org>
+
+    * utils.rb (1.2):
+
+    - Added a debugMsg function.
+    
+    - Qualified all functions as module_functions.
+    
+* 2002-07-18 09:40  Michael Granger <ged@FaerieMUD.org>
+
+    * lib/: poll.rb (1.6), io/reactor.rb (1.6):
+
+    - Fixed some typos
+    
+    - Added clarification and additional documentation for some methods.
+    
+* 2002-07-18 09:35  Michael Granger <ged@FaerieMUD.org>
+
+    * README (1.4, RELEASE_0_03, RELEASE_0_02):
+
+    - Fixed a typo.
+    
+* 2002-04-18 16:53  Michael Granger <ged@FaerieMUD.org>
+
+    * extconf.rb (1.4, RELEASE_0_03, RELEASE_0_02):
+
+    - Corrected a bug in the header =:)
+    
+* 2002-04-18 12:01  Michael Granger <ged@FaerieMUD.org>
+
+    * makedist.rb (1.1, RELEASE_0_04, RELEASE_0_03, RELEASE_0_02),
+    makesitedocs.rb (1.1), utils.rb (1.1) (utags: RELEASE_0_01):
+
+    Initial commit
+    
+* 2002-04-18 11:24  Michael Granger <ged@FaerieMUD.org>
+
+    * extconf.rb (1.3, RELEASE_0_01):
+
+    - Corrected path to the docs-generation script.
+    
+* 2002-04-18 10:23  Michael Granger <ged@FaerieMUD.org>
+
+    * makedocs.rb (1.1, RELEASE_0_01):
+
+    Initial commit
+    
+* 2002-04-18 10:23  Michael Granger <ged@FaerieMUD.org>
+
+    * poll.c (1.3, RELEASE_0_01):
+
+    - Added some comments for RDoc, should it ever parse protected methods.
+    
+    - Changed the name of the second arg to _poll() to handleArray, as it wasn't
+      really an array of file descriptors.
+    
+* 2002-04-18 08:44  Michael Granger <ged@FaerieMUD.org>
+
+    * test.rb (1.3, RELEASE_0_01):
+
+    - Removed the "ext" dir from the ones being added to the LOAD_PATH, as it's gone
+      away.
+    
+    - Removed a require left over from the failed tempfile experiment.
+    
+* 2002-04-18 08:43  Michael Granger <ged@FaerieMUD.org>
+
+    * extconf.rb (1.2):
+
+    - Moved the ext/extconf.rb stuff into this one because the ext directory is
+      going away.
+    
+* 2002-04-18 08:42  Michael Granger <ged@FaerieMUD.org>
+
+    * README (1.3, RELEASE_0_01):
+
+    - Changed from alpha to beta
+    
+    - Added requirements section
+    
+    - Modified installation section to use 'site-install' instead of 'install', and
+      took stuff out that would have been redundant with the requires section.
+    
+* 2002-04-17 15:34  Michael Granger <ged@FaerieMUD.org>
+
+    * lib/: poll.rb (1.5), io/reactor.rb (1.5) (utags: RELEASE_0_01):
+
+    - Added :yeilds: RDoc construct to #poll.
+    
+* 2002-04-17 15:20  Michael Granger <ged@FaerieMUD.org>
+
+    * README (1.2):
+
+    - Separated abstract from header.
+    
+* 2002-04-17 15:18  Michael Granger <ged@FaerieMUD.org>
+
+    * lib/: poll.rb (1.4), io/reactor.rb (1.4):
+
+    - Clarified abstract.
+    
+* 2002-04-17 15:14  Michael Granger <ged@FaerieMUD.org>
+
+    * README (1.1):
+
+    Initial commit
+    
+* 2002-04-17 07:03  Michael Granger <ged@FaerieMUD.org>
+
+    * lib/: poll.rb (1.3), io/reactor.rb (1.3):
+
+    - Fixed documentation for the EventMask bitwise operators.
+    
+* 2002-04-17 06:48  Michael Granger <ged@FaerieMUD.org>
+
+    * lib/: poll.rb (1.2), io/reactor.rb (1.2):
+
+    - Re-implemented after the first one was wiped out by extconf.
+    
+* 2002-04-17 06:47  Michael Granger <ged@FaerieMUD.org>
+
+    * poll.c (1.2):
+
+    - Added shortcut constants
+    
+    - Added _GNU_SOURCE define to catch the additional poll.h constants under Linux
+    
+    - Changed _poll to a protected method.
+    
+* 2002-04-17 06:46  Michael Granger <ged@FaerieMUD.org>
+
+    * test.rb (1.2):
+
+    - Added lots of stuff, redesigned to match the new API
+
+* 2002-04-17 06:45  Michael Granger <ged@FaerieMUD.org>
+
+    * examples/chatserver.rb (1.1, RELEASE_0_01):
+
+    Initial commit
+
+* 2002-04-16 04:47  Michael Granger <ged@FaerieMUD.org>
+
+    * extconf.rb (1.1), poll.c (1.1), test.rb (1.1), lib/poll.rb (1.1),
+    lib/io/reactor.rb (1.1):
+
+    Initial revision
+
+* 2002-04-16 04:47  Michael Granger <ged@FaerieMUD.org>
+
+    * extconf.rb (1.1.1.1), poll.c (1.1.1.1), test.rb (1.1.1.1),
+    lib/poll.rb (1.1.1.1), lib/io/reactor.rb (1.1.1.1) (utags: IMPORT):
+
+    Initial import
+
+=end
+
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+
+# TODO
+
+=begin #testing
+
+  require 'test/unit'
+
+=end