carats 0.3.0

data/lib/carat/io-reactor.rb

@@ -0,0 +1,657 @@
+=begin rdoc
+
+= IO-Reactor
+
+An object-oriented multiplexing asynchronous IO mechanism for Ruby.
+It is an implementation of the Reactor design pattern for multiplexed
+asynchronous single-thread IO.
+
+== Description
+
+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 'io/reactor'
+  require 'socket'
+ 
+  reactorobj = IO::Reactor::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? }
+
+== Requirements
+
+* Ruby >= 1.8.0
+
+== 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
+ 
+Michael Granger <ged@FaerieMUD.org>
+
+== License
+  
+Copyright (c) 2002, 2003 The FaerieMUD Consortium. All rights reserved.
+ 
+IO-Reactor is Open Source Software which is Copyright (c) 2001-2003 by The
+FaerieMUD Consortium.
+
+You may use, modify, and/or redistribute this software under the same terms as
+Ruby itself.
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND
+FITNESS FOR A PARTICULAR PURPOSE.
+
+== Version
+
+  $Id: reactor.rb,v 1.13 2003/08/04 23:56:14 deveiant Exp $
+
+=end 
+
+
+require 'delegate'
+require 'rbconfig'
+
+### An object-oriented multiplexing asynchronous IO reactor class.
+class IO::Reactor
+
+    ### 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