io-reactor 0.05

data/CATALOG

@@ -0,0 +1,10 @@
+#
+# Title:  IO-Reactor
+# Main:   README
+# Upload: ssh://oberon/www/devEiate.org/public/code/IO-Reactor/
+# Webcvs: http://www.deveiate.org/cgi/viewcvs.cgi/IO-Reactor/
+#
+lib/io/*
+README
+ChangeLog
+examples/*

data/ChangeLog

@@ -0,0 +1,303 @@
+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
+	

data/README

@@ -0,0 +1,77 @@
+
+= IO-Reactor
+
+An implementation of the Reactor design pattern for multiplexed asynchronous
+single-thread IO.
+
+== Authors
+
+ Michael Granger <ged@FaerieMUD.org>
+
+
+== 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>.
+
+
+== Requirements
+
+* Ruby >= 1.8.0
+
+Optional:
+
+* Dave Thomas's RDoc documentation tool to make HTML documentation.
+* The Test::Unit module, to run the included test suite.
+
+
+== Installation
+
+  $ su
+  # ruby install.rb
+
+If you have the Test::Unit module installed, you can run the test suite by
+doing:
+
+  $ ruby test.rb
+
+
+== 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
+
+
+== Legal
+
+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.
+
+
+ $Id: README,v 1.5 2003/07/21 15:04:50 deveiant Exp $
+
+
+
+
+

data/examples/chatserver.rb

@@ -0,0 +1,347 @@
+#!/usr/bin/ruby
+# = chatserver.rb
+# 
+# This is an extremely crude and simple single-threaded multiplexing chat
+# server. It (hopefully) demonstrates how to use a IO::Reactor object to do IO
+# multiplexing with events.
+#
+# == Synopsis
+#
+#   $ chatserver.rb [HOST [PORT [LOOPTIMEOUT]]]
+#
+# [HOST]
+#   The host or IP the server will bind to
+#
+# [PORT]
+#   The port the server will listen on
+#
+# [LOOPTIMEOUT]
+#   The number of floating-point seconds between polls. Specifying -1 (or any
+#   negative number, really) here will make the server's event loop block on the
+#   call to #poll.
+#
+# == Author
+# 
+# Michael Granger <ged@FaerieMUD.org>
+# 
+# Copyright (c) 2002, 2003 The FaerieMUD Consortium. All rights reserved.
+# 
+# This program is free software. You may use, modify, and/or redistribute this
+# software under the same terms as Ruby itself.
+# 
+# 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.
+#
+# == Version
+#
+#  $Id: chatserver.rb,v 1.4 2003/08/04 23:53:32 deveiant Exp $
+# 
+
+require 'io/reactor'
+require 'socket'
+
+module Example
+
+### Chatserver user class -- part of the chatserver example.
+class User
+
+	MTU	 = 4096
+	CR   = "\015"
+	LF   = "\012"
+	EOL  = CR + LF
+	
+	PROMPT = 'chat> '
+
+	### Create and return a user object which will use the specified
+	### <tt>socket</tt> and <tt>pollObj</tt>.
+	def initialize( socket, server )
+		@socket = socket
+		@server = server
+		@obuffer = ''
+		@ibuffer = ''
+		@peerHost = @socket.peeraddr[2]
+		@peerPort = @socket.peeraddr[1]
+		@connected = true
+	end
+
+	# Object attribute
+	attr_reader :socket, :server, :ibuffer, :obuffer
+
+
+	### Return a stringified version of the user
+	def to_s
+		"%s:%d" % [ @peerHost, @peerPort ]
+	end
+
+
+	### Add the specified string to the user's output buffer and turn on
+	### output events.
+	def addOutput( string )
+		@obuffer << string.chomp << EOL
+		@server.reactor.enableEvents( @socket, :write )
+	end
+	alias :<< :addOutput
+
+
+	### Write as much of the output buffer to the socket as possible, and return
+	### the number of bytes remaining to be sent.
+	def writeOutput
+		bytes = @socket.syswrite( @obuffer )
+		@obuffer[ 0, bytes ] = '' if bytes.nonzero?
+		return @obuffer.length
+	end
+
+
+	### Write a prompt to the user
+	def prompt
+		@obuffer << PROMPT
+		@server.reactor.enableEvents( @socket, :write )
+	end
+
+
+	### Read at most MTU bytes from the socket and append them to the input
+	### buffer. Split off any complete lines (one that end with EOL) and return
+	### them as an Array of Strings.
+	def readInput
+		rary = []
+		@ibuffer << @socket.sysread( MTU )
+		$stderr.puts "Input buffer for user #{self} now: #@ibuffer" if $VERBOSE
+		while (( pos = @ibuffer.index EOL ))
+			$stderr.puts "Found terminating EOL. "\
+				"Splitting off 0..#{pos} of the input buffer." if $VERBOSE
+			rary << @ibuffer[ 0, pos ]
+			@ibuffer[ 0, pos + EOL.length ] = ''
+		end
+
+		return rary
+	rescue EOFError
+		@server.disconnectUser( self )
+		return []
+	end
+
+
+	### Handle poll events on the socket
+	def handleIOEvent( io, event )
+		case event
+
+		when :error
+			@server.disconnectUser( self )
+			
+		when :read
+			input = readInput()
+			@server.processInput( self, *input ) unless input.empty?
+
+		when :write
+			bytesLeft = writeOutput()
+			@server.reactor.disableEvents( @socket, :write ) if bytesLeft.zero?
+
+		end
+
+	end
+
+
+	### Disconnect the user
+	def disconnect( msg='' )
+		@connected = false
+		unless msg.empty?
+			@obuffer = ">>> Disconnected: #{msg} <<<" + EOL
+		else
+			@obuffer = ">>> Disconnected <<<" + EOL
+		end
+		writeOutput()
+		@socket.close
+	end
+
+
+	### Returns true if the user is still connected
+	def connected?
+		@connected
+	end
+end # class User
+
+
+### Example chatserver class -- an extremely crude and simple chat server that
+### demonstrates how to use Poll to do multiplexing IO in a single thread.
+class Server
+
+	BANNER = <<-EOF
+	[[ IO::Reactor Example Chatserver ]]
+	Commands: '/quit' to quit, '/shutdown' to shut the server down
+	EOF
+
+	### Instantiate and return a chatserver on the specified host and port
+	def initialize( listenHost="0.0.0.0", listenPort=1138, interval=0.20 )
+		@socket			= TCPServer::new( listenHost, listenPort )
+		@users			= []
+		@reactor		= IO::Reactor::new
+		@pollInterval	= interval
+		@shuttingDown	= false
+
+		@reactor.register @socket, :read, &method(:handlePollEvent)
+	end
+
+	# Server attributes
+	attr_reader :reactor, :users, :socket
+
+
+	### Main server loop
+	def eventLoop
+		trap( "INT" ) { shutdown("Server caught SIGINT") }
+		trap( "TERM" ) { shutdown("Server caught SIGTERM") }
+		trap( "HUP" ) { disconnectAllUsers(">>> Server reset <<<") }
+
+		until @shuttingDown
+			eventCount = @reactor.poll( @pollInterval )
+		end
+
+	rescue StandardError => e
+		$stderr.puts "Error in server: #{e.message}"
+		$stderr.puts "\t" + e.backtrace.join( "\n\t" )
+		shutdown( "Server error: #{e.message}" )
+	rescue SignalException => e
+		shutdown( "Server caught #{e.type.name}" )
+	ensure
+		trap( "INT", "SIG_IGN" )
+		trap( "TERM", "SIG_IGN" )
+		trap( "HUP", "SIG_IGN" )
+
+		$stderr.puts "Server exiting event loop."
+	end
+
+
+	### Handle a poll event specified by <tt>event</tt> on the specified
+	### <tt>socket</tt>
+	def handlePollEvent( socket, event )
+		$stderr.puts "Got #{event.inspect} event for #{socket.inspect}"
+
+		case event
+		when :error
+			$stderr.puts "Socket error on the listener socket."
+			shutdown()
+
+		when :read
+			clSock = socket.accept
+			user = User::new( clSock, self )
+			$stderr.puts "Accepted connection from #{user}"
+			@reactor.register clSock, :read, &user.method(:handleIOEvent)
+			user.addOutput( BANNER )
+			user.prompt
+			broadcastMsg( "[New connection: #{user}]" )
+			@users << user
+
+		end
+	end
+
+
+	### Process the specified input from the specified user
+	def processInput( user, *inputStrings )
+		inputStrings.each {|str|
+			case str
+
+			when %r{^/(\w+)\s*(.*)}
+				handleCommand( user, $1, $2 )
+
+			else
+				user.addOutput( "You>> #{str}" )
+				broadcastMsgFrom( user, str )
+			end
+		}
+
+		user.prompt if user.connected?
+	end
+
+
+	### Handle the specified command from the specified user
+	def handleCommand( user, command, args )
+		case command
+
+		when /quit/
+			disconnectUser( user, 'Quit' )
+			
+		when /shutdown/
+			shutdown()
+
+		when /who/
+			user.addOutput( self.wholist(user) )
+
+		else
+			user.addOutput("Unknown command '#{command}'")
+		end
+	end
+
+
+	### Broadcast the specified message to all connected users
+	def broadcastMsg( msg )
+		@users.each {|cl|
+			cl.addOutput( msg )
+		}
+	end
+
+
+	### Broadcast the specified message from the specified user
+	def broadcastMsgFrom( user, msg )
+		userDesc = user.to_s
+
+		@users.each {|cl|
+			next if cl == user
+			cl.addOutput( "#{userDesc}>> #{msg}" )
+		}
+	end
+
+
+	### Disconnect the specified user
+	def disconnectUser( user, msg='' )
+		@users -= [ user ]
+		@reactor.unregister( user.socket )
+		user.disconnect( msg )
+		broadcastMsg( "#{user.to_s} Disconnected." )
+	end
+
+
+	### Disconnect all connected users
+	def disconnectAllUsers( msg )
+		@users.each {|user|
+			@reactor.unregister( user.socket )
+			user.disconnect( msg )
+		}
+		@users.clear
+	end
+
+
+	### Shut the server down
+	def shutdown( msg="Server shutdown" )
+		$stderr.puts "Shutting down: #{msg}"
+		@shuttingDown = true
+		@reactor.clear
+		begin
+			@socket.shutdown
+		rescue
+		end
+		disconnectAllUsers( msg )
+		begin
+			@socket.close
+		rescue
+		end
+	end
+
+	### Build and return a list of connected users for the specified user.
+	def wholist( user )
+		rval = "[Connected Users]\n" <<
+			"  *#{user}*\n"
+		@users.each {|u|
+			next if u == user
+			rval << "  #{u}\n"
+		}
+
+		return rval
+	end
+
+end # class Server
+end # module Example
+
+srv = Example::Server::new( *ARGV )
+$stderr.puts "Chat server listening on #{srv.socket.addr[2]} port #{srv.socket.addr[1]}"
+srv.eventLoop
+$stderr.puts "Chat server finished."
+