eventmachine 0.7.2 → 0.8.0

data/ext/project.h

@@ -1,6 +1,6 @@
 /*****************************************************************************
 
-$Id: project.h 318 2007-05-22 22:06:24Z blackhedd $
+$Id: project.h 401 2007-07-11 12:54:06Z blackhedd $
 
 File:     project.h
 Date:     06Apr06
@@ -28,6 +28,7 @@ See the file COPYING for complete licensing information.
 
 #include <iostream>
 #include <map>
+#include <set>
 #include <vector>
 #include <deque>
 #include <string>
@@ -41,6 +42,8 @@ See the file COPYING for complete licensing information.
 #include <sys/types.h>
 #include <sys/socket.h>
 #include <sys/un.h>
+#include <sys/resource.h>
+#include <sys/wait.h>
 #include <assert.h>
 #include <unistd.h>
 #include <fcntl.h>
@@ -73,6 +76,7 @@ typedef int SOCKET;
 #include <fcntl.h>
 #include <assert.h>
 typedef int socklen_t;
+typedef int pid_t;
 #endif
 
 
@@ -83,13 +87,19 @@ using namespace std;
 #include <openssl/err.h>
 #endif
 
+#ifdef HAVE_EPOLL
+#include <sys/epoll.h>
+#endif
+
 #include "binder.h"
 #include "em.h"
+#include "epoll.h"
 #include "sigs.h"
 #include "ed.h"
 #include "files.h"
 #include "page.h"
 #include "ssl.h"
+#include "eventmachine.h"
 
 
 

data/ext/rubymain.cpp

@@ -1,6 +1,6 @@
 /*****************************************************************************
 
-$Id: rubymain.cpp 318 2007-05-22 22:06:24Z blackhedd $
+$Id: rubymain.cpp 377 2007-06-13 01:05:56Z blackhedd $
 
 File:     rubymain.cpp
 Date:     06Apr06
@@ -28,6 +28,9 @@ Statics
 *******/
 
 static VALUE EmModule;
+static VALUE EmConnection;
+
+static VALUE Intern_at_signature;
 
 
 /****************
@@ -139,6 +142,20 @@ static VALUE t_get_peername (VALUE self, VALUE signature)
 	return Qnil;
 }
 
+/********************
+t_get_subprocess_pid
+********************/
+
+static VALUE t_get_subprocess_pid (VALUE self, VALUE signature)
+{
+	pid_t pid;
+	if (evma_get_subprocess_pid (StringValuePtr (signature), &pid)) {
+		return INT2NUM (pid);
+	}
+
+	return Qnil;
+}
+
 /*****************************
 t_get_comm_inactivity_timeout
 *****************************/
@@ -305,6 +322,68 @@ static VALUE t__write_file (VALUE self, VALUE filename)
 	return rb_str_new2 (f);
 }
 
+/**************
+t_invoke_popen
+**************/
+
+static VALUE t_invoke_popen (VALUE self, VALUE cmd)
+{
+	int len = RARRAY (cmd)->len;
+	if (len > 98)
+		rb_raise (rb_eRuntimeError, "too many arguments to popen");
+	char *strings [100];
+	for (int i=0; i < len; i++) {
+		VALUE ix = INT2FIX (i);
+		VALUE s = rb_ary_aref (1, &ix, cmd);
+		strings[i] = StringValuePtr (s);
+	}
+	strings[len] = NULL;
+
+	const char *f = evma_popen (strings);
+	if (!f || !*f) {
+		char *err = strerror (errno);
+		char buf[100];
+		memset (buf, 0, sizeof(buf));
+		snprintf (buf, sizeof(buf)-1, "no popen: %s", (err?err:"???"));
+		rb_raise (rb_eRuntimeError, buf);
+	}
+	return rb_str_new2 (f);
+}
+
+
+/********
+t__epoll
+********/
+
+static VALUE t__epoll (VALUE self)
+{
+	// Temporary.
+	evma__epoll();
+	return Qnil;
+}
+
+
+/*******************
+t_set_rlimit_nofile
+*******************/
+
+static VALUE t_set_rlimit_nofile (VALUE self, VALUE arg)
+{
+	arg = (NIL_P(arg)) ? -1 : NUM2INT (arg);
+	return INT2NUM (evma_set_rlimit_nofile (arg));
+}
+
+/***************************
+conn_get_outbound_data_size
+***************************/
+
+static VALUE conn_get_outbound_data_size (VALUE self)
+{
+	VALUE sig = rb_ivar_get (self, Intern_at_signature);
+	return INT2NUM (evma_get_outbound_data_size (StringValuePtr(sig)));
+}
+
+
 
 /*********************
 Init_rubyeventmachine
@@ -312,10 +391,19 @@ Init_rubyeventmachine
 
 extern "C" void Init_rubyeventmachine()
 {
+	// Tuck away some symbol values so we don't have to look 'em up every time we need 'em.
+	Intern_at_signature = rb_intern ("@signature");
+
 	// INCOMPLETE, we need to define class Connections inside module EventMachine
 	// run_machine and run_machine_without_threads are now identical.
 	// Must deprecate the without_threads variant.
 	EmModule = rb_define_module ("EventMachine");
+	EmConnection = rb_define_class_under (EmModule, "Connection", rb_cObject);
+
+	rb_define_class_under (EmModule, "ConnectionNotBound", rb_eException);
+	rb_define_class_under (EmModule, "NoHandlerForAcceptedConnection", rb_eException);
+	rb_define_class_under (EmModule, "UnknownTimerFired", rb_eException);
+
 	rb_define_module_function (EmModule, "initialize_event_machine", (VALUE(*)(...))t_initialize_event_machine, 0);
 	rb_define_module_function (EmModule, "run_machine", (VALUE(*)(...))t_run_machine_without_threads, 0);
 	rb_define_module_function (EmModule, "run_machine_without_threads", (VALUE(*)(...))t_run_machine_without_threads, 0);
@@ -335,17 +423,21 @@ extern "C" void Init_rubyeventmachine()
 	rb_define_module_function (EmModule, "library_type", (VALUE(*)(...))t_library_type, 0);
 	rb_define_module_function (EmModule, "set_timer_quantum", (VALUE(*)(...))t_set_timer_quantum, 1);
 	rb_define_module_function (EmModule, "setuid_string", (VALUE(*)(...))t_setuid_string, 1);
+	rb_define_module_function (EmModule, "invoke_popen", (VALUE(*)(...))t_invoke_popen, 1);
 
-  // Provisional:
+	// Provisional:
 	rb_define_module_function (EmModule, "_write_file", (VALUE(*)(...))t__write_file, 1);
 
 	rb_define_module_function (EmModule, "get_peername", (VALUE(*)(...))t_get_peername, 1);
+	rb_define_module_function (EmModule, "get_subprocess_pid", (VALUE(*)(...))t_get_subprocess_pid, 1);
 	rb_define_module_function (EmModule, "get_comm_inactivity_timeout", (VALUE(*)(...))t_get_comm_inactivity_timeout, 1);
 	rb_define_module_function (EmModule, "set_comm_inactivity_timeout", (VALUE(*)(...))t_set_comm_inactivity_timeout, 2);
+	rb_define_module_function (EmModule, "set_rlimit_nofile", (VALUE(*)(...))t_set_rlimit_nofile, 1);
 
-	rb_define_class_under (EmModule, "ConnectionNotBound", rb_eException);
-	rb_define_class_under (EmModule, "NoHandlerForAcceptedConnection", rb_eException);
-	rb_define_class_under (EmModule, "UnknownTimerFired", rb_eException);
+	// Temporary:
+	rb_define_module_function (EmModule, "epoll", (VALUE(*)(...))t__epoll, 0);
+
+	rb_define_method (EmConnection, "get_outbound_data_size", (VALUE(*)(...))conn_get_outbound_data_size, 0);
 
 	rb_define_const (EmModule, "TimerFired", INT2NUM(100));
 	rb_define_const (EmModule, "ConnectionData", INT2NUM(101));

data/lib/em/messages.rb

@@ -0,0 +1,66 @@
+# $Id: messages.rb 349 2007-06-04 17:10:17Z blackhedd $
+#
+# Author:: Francis Cianfrocca (gmail: blackhedd)
+# Homepage::  http://rubyeventmachine.com
+# Date:: 16 Jul 2006
+# 
+# See EventMachine and EventMachine::Connection for documentation and
+# usage examples.
+#
+#----------------------------------------------------------------------------
+#
+# Copyright (C) 2006-07 by Francis Cianfrocca. All Rights Reserved.
+# Gmail: blackhedd
+# 
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of either: 1) the GNU General Public License
+# as published by the Free Software Foundation; either version 2 of the
+# License, or (at your option) any later version; or 2) Ruby's License.
+# 
+# See the file COPYING for complete licensing information.
+#
+#---------------------------------------------------------------------------
+#
+# 
+
+=begin
+
+Message Routing in EventMachine.
+
+The goal here is to enable "routing points," objects that can send and receive
+"messages," which are delimited streams of bytes. The boundaries of a message
+are preserved as it passes through the reactor system.
+
+There will be several module methods defined in EventMachine to create route-point
+objects (which will probably have a base class of EventMachine::MessageRouter
+until someone suggests a better name).
+
+As with I/O objects, routing objects will receive events by having the router
+core call methods on them. And of course user code can and will define handlers
+to deal with events of interest.
+
+The message router base class only really needs a receive_message method. There will
+be an EM module-method to send messages, in addition to the module methods to create
+the various kinds of message receivers.
+
+The simplest kind of message receiver object can receive messages by being named 
+explicitly in a parameter to EM#send_message. More sophisticated receivers can define
+pub-sub selectors and message-queue names. And they can also define channels for
+route-points in other processes or even on other machines.
+
+A message is NOT a marshallable entity. Rather, it's a chunk of flat content more like
+an Erlang message. Initially, all content submitted for transmission as a message will
+have the to_s method called on it. Eventually, we'll be able to transmit certain structured
+data types (XML and YAML documents, Structs within limits) and have them reconstructed
+on the other end.
+
+A fundamental goal of the message-routing capability is to interoperate seamlessly with
+external systems, including non-Ruby systems like ActiveMQ. We will define various protocol
+handlers for things like Stomp and possibly AMQP, but these will be wrapped up and hidden
+from the users of the basic routing capability.
+
+As with Erlang, a critical goal is for programs that are built to use message-passing to work
+WITHOUT CHANGE when the code is re-based on a multi-process system.
+
+=end
+

data/lib/eventmachine.rb

@@ -1,4 +1,4 @@
-# $Id: eventmachine.rb 319 2007-05-22 22:11:18Z blackhedd $
+# $Id: eventmachine.rb 393 2007-07-06 06:51:47Z blackhedd $
 #
 # Author:: Francis Cianfrocca (gmail: blackhedd)
 # Homepage::  http://rubyeventmachine.com
@@ -25,6 +25,15 @@
 
 
 #-- Select in a library based on a global variable.
+# PROVISIONALLY commented out this whole mechanism which selects
+# a pure-Ruby EM implementation if the extension is not available.
+# I expect this will cause a lot of people's code to break, as it
+# exposes misconfigurations and path problems that were masked up
+# till now. The reason I'm disabling it is because the pure-Ruby
+# code will have problems of its own, and it's not nearly as fast
+# anyway. Suggested by a problem report from Moshe Litvin. 05Jun07.
+
+=begin
 $eventmachine_library ||= nil
 case $eventmachine_library
 when :pure_ruby
@@ -40,12 +49,18 @@ else
     require 'pr_eventmachine'
   end
 end
+=end
+require 'rubyeventmachine'
 
 
 require "eventmachine_version"
 require 'em/deferrable'
 require 'em/future'
 require 'em/eventable'
+require 'em/messages'
+
+require 'shellwords'
+
 #-- Additional requires are at the BOTTOM of this file, because they
 #-- depend on stuff defined in here. Refactor that someday.
 
@@ -633,220 +648,315 @@ module EventMachine
 	end
 
 
-  # EventMachine#open_datagram_socket is for support of UDP-based
-  # protocols. Its usage is similar to that of EventMachine#start_server.
-  # It takes three parameters: an IP address (which must be valid
-  # on the machine which executes the method), a port number,
-  # and an optional Module name which will handle the data.
-  # This method will create a new UDP (datagram) socket and
-  # bind it to the address and port that you specify.
-  # The normal callbacks (see EventMachine#start_server) will
-  # be called as events of interest occur on the newly-created
-  # socket, but there are some differences in how they behave.
-  #
-  # Connection#receive_data will be called when a datagram packet
-  # is received on the socket, but unlike TCP sockets, the message
-  # boundaries of the received data will be respected. In other words,
-  # if the remote peer sent you a datagram of a particular size,
-  # you may rely on Connection#receive_data to give you the
-  # exact data in the packet, with the original data length.
-  # Also observe that Connection#receive_data may be called with a
-  # <i>zero-length</i> data payload, since empty datagrams are permitted
-  # in UDP.
-  #
-  # Connection#send_data is available with UDP packets as with TCP,
-  # but there is an important difference. Because UDP communications
-  # are <i>connectionless,</i> there is no implicit recipient for the packets you
-  # send. Ordinarily you must specify the recipient for each packet you send.
-  # However, EventMachine
-  # provides for the typical pattern of receiving a UDP datagram
-  # from a remote peer, performing some operation, and then sending
-  # one or more packets in response to the same remote peer.
-  # To support this model easily, just use Connection#send_data
-  # in the code that you supply for Connection:receive_data.
-  # EventMachine will
-  # provide an implicit return address for any messages sent to
-  # Connection#send_data within the context of a Connection#receive_data callback,
-  # and your response will automatically go to the correct remote peer.
-  # (TODO: Example-code needed!)
-  #
-  # Observe that the port number that you supply to EventMachine#open_datagram_socket
-  # may be zero. In this case, EventMachine will create a UDP socket
-  # that is bound to an <i>ephemeral</i> (not well-known) port.
-  # This is not appropriate for servers that must publish a well-known
-  # port to which remote peers may send datagrams. But it can be useful
-  # for clients that send datagrams to other servers.
-  # If you do this, you will receive any responses from the remote
-  # servers through the normal Connection#receive_data callback.
-  # Observe that you will probably have issues with firewalls blocking
-  # the ephemeral port numbers, so this technique is most appropriate for LANs.
-  # (TODO: Need an example!)
-  #
-  # If you wish to send datagrams to arbitrary remote peers (not
-  # necessarily ones that have sent data to which you are responding),
-  # then see Connection#send_datagram.
-  #
-  #--
-  # Replaced the implementation on 01Oct06. Thanks to Tobias Gustafsson for pointing
-  # out that this originally did not take a class but only a module.
-  #
-  def self::open_datagram_socket address, port, handler=nil
-    klass = if (handler and handler.is_a?(Class))
-      handler
-    else
-      Class.new( Connection ) {handler and include handler}
-    end
+	# EventMachine#open_datagram_socket is for support of UDP-based
+	# protocols. Its usage is similar to that of EventMachine#start_server.
+	# It takes three parameters: an IP address (which must be valid
+	# on the machine which executes the method), a port number,
+	# and an optional Module name which will handle the data.
+	# This method will create a new UDP (datagram) socket and
+	# bind it to the address and port that you specify.
+	# The normal callbacks (see EventMachine#start_server) will
+	# be called as events of interest occur on the newly-created
+	# socket, but there are some differences in how they behave.
+	#
+	# Connection#receive_data will be called when a datagram packet
+	# is received on the socket, but unlike TCP sockets, the message
+	# boundaries of the received data will be respected. In other words,
+	# if the remote peer sent you a datagram of a particular size,
+	# you may rely on Connection#receive_data to give you the
+	# exact data in the packet, with the original data length.
+	# Also observe that Connection#receive_data may be called with a
+	# <i>zero-length</i> data payload, since empty datagrams are permitted
+	# in UDP.
+	#
+	# Connection#send_data is available with UDP packets as with TCP,
+	# but there is an important difference. Because UDP communications
+	# are <i>connectionless,</i> there is no implicit recipient for the packets you
+	# send. Ordinarily you must specify the recipient for each packet you send.
+	# However, EventMachine
+	# provides for the typical pattern of receiving a UDP datagram
+	# from a remote peer, performing some operation, and then sending
+	# one or more packets in response to the same remote peer.
+	# To support this model easily, just use Connection#send_data
+	# in the code that you supply for Connection:receive_data.
+	# EventMachine will
+	# provide an implicit return address for any messages sent to
+	# Connection#send_data within the context of a Connection#receive_data callback,
+	# and your response will automatically go to the correct remote peer.
+	# (TODO: Example-code needed!)
+	#
+	# Observe that the port number that you supply to EventMachine#open_datagram_socket
+	# may be zero. In this case, EventMachine will create a UDP socket
+	# that is bound to an <i>ephemeral</i> (not well-known) port.
+	# This is not appropriate for servers that must publish a well-known
+	# port to which remote peers may send datagrams. But it can be useful
+	# for clients that send datagrams to other servers.
+	# If you do this, you will receive any responses from the remote
+	# servers through the normal Connection#receive_data callback.
+	# Observe that you will probably have issues with firewalls blocking
+	# the ephemeral port numbers, so this technique is most appropriate for LANs.
+	# (TODO: Need an example!)
+	#
+	# If you wish to send datagrams to arbitrary remote peers (not
+	# necessarily ones that have sent data to which you are responding),
+	# then see Connection#send_datagram.
+	#
+	# DO NOT call send_data from a datagram socket
+	# outside of a #receive_data method. Use #send_datagram. If you do use #send_data
+	# outside of a #receive_data method, you'll get a confusing error
+	# because there is no "peer," as #send_data requires. (Inside of #receive_data,
+	# #send_data "fakes" the peer as described above.)
+	#
+	#--
+	# Replaced the implementation on 01Oct06. Thanks to Tobias Gustafsson for pointing
+	# out that this originally did not take a class but only a module.
+	#
+	def self::open_datagram_socket address, port, handler=nil
+		klass = if (handler and handler.is_a?(Class))
+			handler
+		else
+			Class.new( Connection ) {handler and include handler}
+		end
 
-    s = open_udp_socket address, port
-    c = klass.new s
-    @conns[s] = c
-    block_given? and yield c
-    c
-  end
+		s = open_udp_socket address, port
+		c = klass.new s
+		@conns[s] = c
+		block_given? and yield c
+		c
+	end
+
+
+	# For advanced users. This function sets the default timer granularity, which by default is
+	# slightly smaller than 100 milliseconds. Call this function to set a higher or lower granularity.
+	# The function affects the behavior of #add_timer and #add_periodic_timer. Most applications
+	# will not need to call this function.
+	#
+	# The argument is a number of milliseconds. Avoid setting the quantum to very low values because
+	# that may reduce performance under some extreme conditions. We recommend that you not set a quantum
+	# lower than 10.
+	#
+	# You may only call this function while an EventMachine loop is running (that is, after a call to
+	# EventMachine#run and before a subsequent call to EventMachine#stop).
+	#
+	def self::set_quantum mills
+		set_timer_quantum mills.to_i
+	end
+
+
+	#--
+	# The is the responder for the loopback-signalled event.
+	# It can be fired either by code running on a separate thread (EM#defer) or on
+	# the main thread (EM#next_tick).
+	# It will often happen that a next_tick handler will reschedule itself. We
+	# consume a duplicate of the tick queue so that tick events scheduled by tick events
+	# have to wait for the next pass through the reactor core.
+	#
+	def self::run_deferred_callbacks # :nodoc:
+		if @resultqueue
+			until @resultqueue.empty?
+				result,cback = @resultqueue.pop
+				cback.call result if cback
+			end
+		end
+
+		if (@next_tick_queue ||= []) and @next_tick_queue.length > 0
+			ary = @next_tick_queue.dup
+			@next_tick_queue.clear
+			until ary.empty?
+				cback=ary.pop and cback.call
+			end
+		end
+	end
+
+
+	# #defer is for integrating blocking operations into EventMachine's control flow.
+	# Call #defer with one or two blocks, as shown below (the second block is <i>optional</i>):
+	#  
+	#  operation = proc {
+	#    # perform a long-running operation here, such as a database query.
+	#    "result" # as usual, the last expression evaluated in the block will be the return value.
+	#  }
+	#  callback = proc {|result|
+	#    # do something with result here, such as send it back to a network client.
+	#  }
+	#
+	#  EventMachine.defer( operation, callback )
+	#  
+	# The action of #defer is to take the block specified in the first parameter (the "operation")
+	# and schedule it for asynchronous execution on an internal thread pool maintained by EventMachine.
+	# When the operation completes, it will pass the result computed by the block (if any)
+	# back to the EventMachine reactor. Then, EventMachine calls the block specified in the
+	# second parameter to #defer (the "callback"), as part of its normal, synchronous
+	# event handling loop. The result computed by the operation block is passed as a parameter
+	# to the callback. You may omit the callback parameter if you don't need to execute any code
+	# after the operation completes.
+	#
+	# <i>Caveats:</i>
+	# This is a <b>provisional</b> implementation and is subject to change.
+	# Note carefully that the code in your deferred operation will be executed on a separate
+	# thread from the main EventMachine processing and all other Ruby threads that may exist in
+	# your program. Also, multiple deferred operations may be running at once! Therefore, you
+	# are responsible for ensuring that your operation code is threadsafe. [Need more explanation
+	# and examples.]
+	# Don't write a deferred operation that will block forever. If so, the current implementation will
+	# not detect the problem, and the thread will never be returned to the pool. EventMachine limits
+	# the number of threads in its pool, so if you do this enough times, your subsequent deferred
+	# operations won't get a chance to run. [We might put in a timer to detect this problem.]
+	#
+	#--
+	# OBSERVE that #next_tick hacks into this mechanism, so don't make any changes here
+	# without syncing there.
+	#
+	# Running with $VERBOSE set to true gives a warning unless all ivars are defined when
+	# they appear in rvalues. But we DON'T ever want to initialize @threadqueue unless we
+	# need it, because the Ruby threads are so heavyweight. We end up with this bizarre
+	# way of initializing @threadqueue because EventMachine is a Module, not a Class, and
+	# has no constructor.
+	#
+	def self::defer op, callback = nil
+		@need_threadqueue ||= 0
+		if @need_threadqueue == 0
+			@need_threadqueue = 1
+			require 'thread'
+			@threadqueue = Queue.new
+			@resultqueue = Queue.new
+			20.times {|ix|
+				Thread.new {
+					my_ix = ix
+					loop {
+						op,cback = @threadqueue.pop
+						result = op.call
+						@resultqueue << [result, cback]
+						EventMachine.signal_loopbreak
+					}
+				}
+			}
+		end
+
+		@threadqueue << [op,callback]
+	end
+
+  	# Schedules a proc for execution immediately after the next "turn" through the reactor
+	# core. An advanced technique, this can be useful for improving memory management and/or
+	# application responsiveness, especially when scheduling large amounts of data for
+	# writing to a network connection. TODO, we need a FAQ entry on this subject.
+	#
+	# #next_tick takes either a single argument (which must be a Proc) or a block.
+	# And I'm taking suggestions for a better name for this method.
+	#--
+	# This works by adding to the @resultqueue that's used for #defer.
+	# The general idea is that next_tick is used when we want to give the reactor a chance
+	# to let other operations run, either to balance the load out more evenly, or to let
+	# outbound network buffers drain, or both. So we probably do NOT want to block, and
+	# we probably do NOT want to be spinning any threads. A program that uses next_tick
+	# but not #defer shouldn't suffer the penalty of having Ruby threads running. They're
+	# extremely expensive even if they're just sleeping.
+	#
+	def self::next_tick pr=nil, &block
+		raise "no argument or block given" unless ((pr && pr.respond_to?(:call)) or block)
+		(@next_tick_queue ||= []) << (pr || block)
+		EventMachine.signal_loopbreak
 =begin
-  (Original, replaced 01Oct06)
-  def self::open_datagram_socket address, port, handler=nil
-    s = open_udp_socket address, port
-    klass = Class.new( Connection ) {
-      handler and include handler
-    }
-    c = klass.new s
-    @conns[s] = c
-    block_given? and yield c
-    c
-  end
+		(@next_tick_procs ||= []) << (pr || block)
+		if @next_tick_procs.length == 1
+			add_timer(0) {
+				@next_tick_procs.each {|t| t.call}
+				@next_tick_procs.clear
+			}
+		end
 =end
+	end
 
+	# A wrapper over the setuid system call. Particularly useful when opening a network
+	# server on a privileged port because you can use this call to drop privileges
+	# after opening the port. Also very useful after a call to #set_descriptor_table_size,
+	# which generally requires that you start your process with root privileges.
+	#
+	# This method has no effective implementation on Windows or in the pure-Ruby
+	# implementation of EventMachine.
+	# Call #set_effective_user by passing it a string containing the effective name
+	# of the user whose privilege-level your process should attain.
+	# This method is intended for use in enforcing security requirements, consequently
+	# it will throw a fatal error and end your program if it fails.
+	#
+	def self::set_effective_user username
+		EventMachine::setuid_string username
+	end
 
-  # For advanced users. This function sets the default timer granularity, which by default is
-  # slightly smaller than 100 milliseconds. Call this function to set a higher or lower granularity.
-  # The function affects the behavior of #add_timer and #add_periodic_timer. Most applications
-  # will not need to call this function.
-  #
-  # The argument is a number of milliseconds. Avoid setting the quantum to very low values because
-  # that may reduce performance under some extreme conditions. We recommend that you not set a quantum
-  # lower than 10.
-  #
-  # You MUST call this function while an EventMachine loop is running (that is, after a call to
-  # EventMachine#run and before a subsequent call to EventMachine#stop).
-  #
-  def self::set_quantum mills
-    set_timer_quantum mills.to_i
-  end
 
+	# Sets the maximum number of file or socket descriptors that your process may open.
+	# You can pass this method an integer specifying the new size of the descriptor table.
+	# Returns the new descriptor-table size, which may be less than the number you
+	# requested. If you call this method with no arguments, it will simply return
+	# the current size of the descriptor table without attempting to change it.
+	#
+	# The new limit on open descriptors ONLY applies to sockets and other descriptors
+	# that belong to EventMachine. It has NO EFFECT on the number of descriptors
+	# you can create in ordinary Ruby code.
+	#
+	# Not available on all platforms. Increasing the number of descriptors beyond its
+	# default limit usually requires superuser privileges. (See #set_effective_user
+	# for a way to drop superuser privileges while your program is running.)
+	#
+	def self::set_descriptor_table_size n_descriptors=nil
+		EventMachine::set_rlimit_nofile n_descriptors
+	end
 
-  def self::run_deferred_callbacks # :nodoc:
-    until @resultqueue.empty?
-      result,cback = @resultqueue.pop
-      cback.call result if cback
-    end
-  end
 
-  # #defer is for integrating blocking operations into EventMachine's control flow.
-  # Call #defer with one or two blocks, as shown below (the second block is <i>optional</i>):
-  #  
-  #  operation = proc {
-  #    # perform a long-running operation here, such as a database query.
-  #    "result" # as usual, the last expression evaluated in the block will be the return value.
-  #  }
-  #  callback = proc {|result|
-  #    # do something with result here, such as send it back to a network client.
-  #  }
-  #
-  #  EventMachine.defer( operation, callback )
-  #  
-  # The action of #defer is to take the block specified in the first parameter (the "operation")
-  # and schedule it for asynchronous execution on an internal thread pool maintained by EventMachine.
-  # When the operation completes, it will pass the result computed by the block (if any)
-  # back to the EventMachine reactor. Then, EventMachine calls the block specified in the
-  # second parameter to #defer (the "callback"), as part of its normal, synchronous
-  # event handling loop. The result computed by the operation block is passed as a parameter
-  # to the callback. You may omit the callback parameter if you don't need to execute any code
-  # after the operation completes.
-  #
-  # <i>Caveats:</i>
-  # This is a <b>provisional</b> implementation and is subject to change.
-  # Note carefully that the code in your deferred operation will be executed on a separate
-  # thread from the main EventMachine processing and all other Ruby threads that may exist in
-  # your program. Also, multiple deferred operations may be running at once! Therefore, you
-  # are responsible for ensuring that your operation code is threadsafe. [Need more explanation
-  # and examples.]
-  # Don't write a deferred operation that will block forever. If so, the current implementation will
-  # not detect the problem, and the thread will never be returned to the pool. EventMachine limits
-  # the number of threads in its pool, so if you do this enough times, your subsequent deferred
-  # operations won't get a chance to run. [We might put in a timer to detect this problem.]
-  #
-  def self::defer op, callback = nil
-    unless @threadqueue
-
-      #start_server "127.0.0.1", 29999, DeferredTrigger
-      #@deferred_trigger = connect "127.0.0.1", 29999
-
-      require 'thread'
-      @threadqueue = Queue.new
-      @resultqueue = Queue.new
-      20.times {|ix|
-        Thread.new {
-          my_ix = ix
-          loop {
-            op,cback = @threadqueue.pop
-            result = op.call
-            @resultqueue << [result, cback]
-            EventMachine.signal_loopbreak
-            #@deferred_trigger.send_data "."
-          }
-        }
-      }
-    end
 
-    @threadqueue << [op,callback]
-  end
+	# TODO, must document popen. At this moment, it's only available on Unix.
+	# This limitation is expected to go away.
+	#--
+	# Perhaps misnamed since the underlying function uses socketpair and is full-duplex.
+	#
+	def self::popen cmd, handler=nil
+		klass = if (handler and handler.is_a?(Class))
+			handler
+		else
+			Class.new( Connection ) {handler and include handler}
+		end
 
-  # A wrapper over the setuid system call. Particularly useful when opening a network
-  # server on a privileged port because you can use this call to drop privileges
-  # after opening the port.
-  # This method has no effective implementation on Windows or in the pure-Ruby
-  # implementation of EventMachine.
-  # Call #set_effective_user by passing it a string containing the effective name
-  # of the user whose privilege-level your process should attain.
-  # This method is intended for use in enforcing security requirements, consequently
-  # it will throw a fatal error and end your program if it fails.
-  def self::set_effective_user username
-      EventMachine::setuid_string username
-  end
+		w = Shellwords::shellwords( cmd )
+		w.unshift( w.first ) if w.first
+		s = invoke_popen( w )
+		c = klass.new s
+		@conns[s] = c
+		yield(c) if block_given?
+		c
+	end
 
 
-  private
-  def EventMachine::event_callback conn_binding, opcode, data
-    case opcode
-    when ConnectionData
-      c = @conns[conn_binding] or raise ConnectionNotBound
-      c.receive_data data
-    when ConnectionUnbound
-      if c = @conns.delete( conn_binding )
-        c.unbind
-      elsif c = @acceptors.delete( conn_binding )
-        # no-op
-      else
-        raise ConnectionNotBound
-      end
-    when ConnectionAccepted
-      accep,blk = @acceptors[conn_binding]
-      raise NoHandlerForAcceptedConnection unless accep
-      c = accep.new data
-      @conns[data] = c
-      blk and blk.call(c)
-      c # (needed?)
-    when TimerFired
-      t = @timers.delete( data ) or raise UnknownTimerFired
-      t.call
-    when ConnectionCompleted
-      c = @conns[conn_binding] or raise ConnectionNotBound
-      c.connection_completed
-    when LoopbreakSignalled
-      run_deferred_callbacks
-    end
-  end
+
+	private
+	def EventMachine::event_callback conn_binding, opcode, data
+		if opcode == ConnectionData
+			c = @conns[conn_binding] or raise ConnectionNotBound
+			c.receive_data data
+		elsif opcode == ConnectionUnbound
+			if c = @conns.delete( conn_binding )
+				c.unbind
+			elsif c = @acceptors.delete( conn_binding )
+				# no-op
+			else
+				raise ConnectionNotBound
+			end
+		elsif opcode == ConnectionAccepted
+			accep,blk = @acceptors[conn_binding]
+			raise NoHandlerForAcceptedConnection unless accep
+			c = accep.new data
+			@conns[data] = c
+			blk and blk.call(c)
+			c # (needed?)
+		elsif opcode == TimerFired
+			t = @timers.delete( data ) or raise UnknownTimerFired
+			t.call
+		elsif opcode == ConnectionCompleted
+			c = @conns[conn_binding] or raise ConnectionNotBound
+			c.connection_completed
+		elsif opcode == LoopbreakSignalled
+			run_deferred_callbacks
+		end
+	end
 
 
   # Documentation stub
@@ -896,220 +1006,229 @@ module EventMachine
 #
 class Connection
 
-    # EXPERIMENTAL. Added the reconnect methods, which may go away.
-    attr_accessor :signature
+	# EXPERIMENTAL. Added the reconnect methods, which may go away.
+	attr_accessor :signature
 
-  def initialize sig #:nodoc:
-    @signature = sig
-    post_init
-  end
+	def initialize sig #:nodoc:
+		@signature = sig
+		post_init
+	end
 
-  # EventMachine::Connection#post_init is called by the event loop
-  # immediately after the network connection has been established,
-  # and before resumption of the network loop.
-  # This method is generally not called by user code, but is called automatically
-  # by the event loop. The base-class implementation is a no-op.
-  # This is a very good place to initialize instance variables that will
-  # be used throughout the lifetime of the network connection.
-  #
-  def post_init
-  end
+	# EventMachine::Connection#post_init is called by the event loop
+	# immediately after the network connection has been established,
+	# and before resumption of the network loop.
+	# This method is generally not called by user code, but is called automatically
+	# by the event loop. The base-class implementation is a no-op.
+	# This is a very good place to initialize instance variables that will
+	# be used throughout the lifetime of the network connection.
+	#
+	def post_init
+	end
 
-  # EventMachine::Connection#receive_data is called by the event loop
-  # whenever data has been received by the network connection.
-  # It is never called by user code.
-  # receive_data is called with a single parameter, a String containing
-  # the network protocol data, which may of course be binary. You will
-  # generally redefine this method to perform your own processing of the incoming data.
-  #
-  # Here's a key point which is essential to understanding the event-driven
-  # programming model: <i>EventMachine knows absolutely nothing about the protocol
-  # which your code implements.</i> You must not make any assumptions about
-  # the size of the incoming data packets, or about their alignment on any
-  # particular intra-message or PDU boundaries (such as line breaks).
-  # receive_data can and will send you arbitrary chunks of data, with the
-  # only guarantee being that the data is presented to your code in the order
-  # it was collected from the network. Don't even assume that the chunks of
-  # data will correspond to network packets, as EventMachine can and will coalesce
-  # several incoming packets into one, to improve performance. The implication for your
-  # code is that you generally will need to implement some kind of a state machine
-  # in your redefined implementation of receive_data. For a better understanding
-  # of this, read through the examples of specific protocol handlers given
-  # elsewhere in this package. (STUB, WE MUST ADD THESE!)
-  #
-  # The base-class implementation of receive_data (which will be invoked if
-  # you don't redefine it) simply prints the size of each incoming data packet
-  # to stdout.
-  #
-  def receive_data data
-    puts "............>>>#{data.length}"
-  end
+	# EventMachine::Connection#receive_data is called by the event loop
+	# whenever data has been received by the network connection.
+	# It is never called by user code.
+	# receive_data is called with a single parameter, a String containing
+	# the network protocol data, which may of course be binary. You will
+	# generally redefine this method to perform your own processing of the incoming data.
+	#
+	# Here's a key point which is essential to understanding the event-driven
+	# programming model: <i>EventMachine knows absolutely nothing about the protocol
+	# which your code implements.</i> You must not make any assumptions about
+	# the size of the incoming data packets, or about their alignment on any
+	# particular intra-message or PDU boundaries (such as line breaks).
+	# receive_data can and will send you arbitrary chunks of data, with the
+	# only guarantee being that the data is presented to your code in the order
+	# it was collected from the network. Don't even assume that the chunks of
+	# data will correspond to network packets, as EventMachine can and will coalesce
+	# several incoming packets into one, to improve performance. The implication for your
+	# code is that you generally will need to implement some kind of a state machine
+	# in your redefined implementation of receive_data. For a better understanding
+	# of this, read through the examples of specific protocol handlers given
+	# elsewhere in this package. (STUB, WE MUST ADD THESE!)
+	#
+	# The base-class implementation of receive_data (which will be invoked if
+	# you don't redefine it) simply prints the size of each incoming data packet
+	# to stdout.
+	#
+	def receive_data data
+		puts "............>>>#{data.length}"
+	end
 
-  # EventMachine::Connection#unbind is called by the framework whenever a connection
-  # (either a server or client connection) is closed. The close can occur because
-  # your code intentionally closes it (see close_connection and close_connection_after_writing),
-  # because the remote peer closed the connection, or because of a network error.
-  # You may not assume that the network connection is still open and able to send or
-  # receive data when the callback to unbind is made. This is intended only to give
-  # you a chance to clean up associations your code may have made to the connection
-  # object while it was open.
-  #
-  def unbind
-  end
+	# EventMachine::Connection#unbind is called by the framework whenever a connection
+	# (either a server or client connection) is closed. The close can occur because
+	# your code intentionally closes it (see close_connection and close_connection_after_writing),
+	# because the remote peer closed the connection, or because of a network error.
+	# You may not assume that the network connection is still open and able to send or
+	# receive data when the callback to unbind is made. This is intended only to give
+	# you a chance to clean up associations your code may have made to the connection
+	# object while it was open.
+	#
+	def unbind
+	end
 
-  # EventMachine::Connection#close_connection is called only by user code, and never
-  # by the event loop. You may call this method against a connection object in any
-  # callback handler, whether or not the callback was made against the connection
-  # you want to close. close_connection <i>schedules</i> the connection to be closed
-  # at the next available opportunity within the event loop. You may not assume that
-  # the connection is closed when close_connection returns. In particular, the framework
-  # will callback the unbind method for the particular connection at a point shortly
-  # after you call close_connection. You may assume that the unbind callback will
-  # take place sometime after your call to close_connection completes. In other words,
-  # the unbind callback will not re-enter your code "inside" of your call to close_connection.
-  # However, it's not guaranteed that a future version of EventMachine will not change
-  # this behavior.
-  #
-  # close_connection will <i>silently discard</i> any outbound data which you have
-  # sent to the connection using EventMachine::Connection#send_data but which has not
-  # yet been sent across the network. If you want to avoid this behavior, use
-  # EventMachine::Connection#close_connection_after_writing.
-  #
-  def close_connection after_writing = false
-    EventMachine::close_connection @signature, after_writing
-  end
+	# EventMachine::Connection#close_connection is called only by user code, and never
+	# by the event loop. You may call this method against a connection object in any
+	# callback handler, whether or not the callback was made against the connection
+	# you want to close. close_connection <i>schedules</i> the connection to be closed
+	# at the next available opportunity within the event loop. You may not assume that
+	# the connection is closed when close_connection returns. In particular, the framework
+	# will callback the unbind method for the particular connection at a point shortly
+	# after you call close_connection. You may assume that the unbind callback will
+	# take place sometime after your call to close_connection completes. In other words,
+	# the unbind callback will not re-enter your code "inside" of your call to close_connection.
+	# However, it's not guaranteed that a future version of EventMachine will not change
+	# this behavior.
+	#
+	# close_connection will <i>silently discard</i> any outbound data which you have
+	# sent to the connection using EventMachine::Connection#send_data but which has not
+	# yet been sent across the network. If you want to avoid this behavior, use
+	# EventMachine::Connection#close_connection_after_writing.
+	#
+	def close_connection after_writing = false
+		EventMachine::close_connection @signature, after_writing
+	end
 
-  # EventMachine::Connection#close_connection_after_writing is a variant of close_connection.
-  # All of the descriptive comments given for close_connection also apply to
-  # close_connection_after_writing, <i>with one exception:</i> If the connection has
-  # outbound data sent using send_dat but which has not yet been sent across the network,
-  # close_connection_after_writing will schedule the connection to be closed <i>after</i>
-  # all of the outbound data has been safely written to the remote peer.
-  #
-  # Depending on the amount of outgoing data and the speed of the network,
-  # considerable time may elapse between your call to close_connection_after_writing
-  # and the actual closing of the socket (at which time the unbind callback will be called
-  # by the event loop). During this time, you <i>may not</i> call send_data to transmit
-  # additional data (that is, the connection is closed for further writes). In very
-  # rare cases, you may experience a receive_data callback after your call to close_connection_after_writing,
-  # depending on whether incoming data was in the process of being received on the connection
-  # at the moment when you called close_connection_after_writing. Your protocol handler must
-  # be prepared to properly deal with such data (probably by ignoring it).
-  #
-  def close_connection_after_writing
-    close_connection true
-  end
+	# EventMachine::Connection#close_connection_after_writing is a variant of close_connection.
+	# All of the descriptive comments given for close_connection also apply to
+	# close_connection_after_writing, <i>with one exception:</i> If the connection has
+	# outbound data sent using send_dat but which has not yet been sent across the network,
+	# close_connection_after_writing will schedule the connection to be closed <i>after</i>
+	# all of the outbound data has been safely written to the remote peer.
+	#
+	# Depending on the amount of outgoing data and the speed of the network,
+	# considerable time may elapse between your call to close_connection_after_writing
+	# and the actual closing of the socket (at which time the unbind callback will be called
+	# by the event loop). During this time, you <i>may not</i> call send_data to transmit
+	# additional data (that is, the connection is closed for further writes). In very
+	# rare cases, you may experience a receive_data callback after your call to close_connection_after_writing,
+	# depending on whether incoming data was in the process of being received on the connection
+	# at the moment when you called close_connection_after_writing. Your protocol handler must
+	# be prepared to properly deal with such data (probably by ignoring it).
+	#
+	def close_connection_after_writing
+		close_connection true
+	end
 
-  # EventMachine::Connection#send_data is only called by user code, never by
-  # the event loop. You call this method to send data to the remote end of the
-  # network connection. send_data is called with a single String argument, which
-  # may of course contain binary data. You can call send_data any number of times.
-  # send_data is an instance method of an object derived from EventMachine::Connection
-  # and containing your mixed-in handler code), so if you call it without qualification
-  # within a callback function, the data will be sent to the same network connection
-  # that generated the callback. Calling self.send_data is exactly equivalent.
-  #
-  # You can also call send_data to write to a connection <i>other than the one
-  # whose callback you are calling send_data from.</i> This is done by recording
-  # the value of the connection in any callback function (the value self), in any
-  # variable visible to other callback invocations on the same or different
-  # connection objects. (Need an example to make that clear.)
-  #
-  def send_data data
-    EventMachine::send_data @signature, data, data.length
-  end
+	# EventMachine::Connection#send_data is only called by user code, never by
+	# the event loop. You call this method to send data to the remote end of the
+	# network connection. send_data is called with a single String argument, which
+	# may of course contain binary data. You can call send_data any number of times.
+	# send_data is an instance method of an object derived from EventMachine::Connection
+	# and containing your mixed-in handler code), so if you call it without qualification
+	# within a callback function, the data will be sent to the same network connection
+	# that generated the callback. Calling self.send_data is exactly equivalent.
+	#
+	# You can also call send_data to write to a connection <i>other than the one
+	# whose callback you are calling send_data from.</i> This is done by recording
+	# the value of the connection in any callback function (the value self), in any
+	# variable visible to other callback invocations on the same or different
+	# connection objects. (Need an example to make that clear.)
+	#
+	def send_data data
+		EventMachine::send_data @signature, data, data.length
+	end
 
-  # #connection_completed is called by the event loop when a remote TCP connection
-  # attempt completes successfully. You can expect to get this notification after calls
-  # to EventMachine#connect. Remember that EventMachine makes remote connections
-  # asynchronously, just as with any other kind of network event. #connection_completed
-  # is intended primarily to assist with network diagnostics. For normal protocol
-  # handling, use #post_init to perform initial work on a new connection (such as
-  # send an initial set of data).
-  # #post_init will always be called. #connection_completed will only be called in case
-  # of a successful completion. A connection-attempt which fails will receive a call
-  # to #unbind after the failure.
-  def connection_completed
-  end
+	# #connection_completed is called by the event loop when a remote TCP connection
+	# attempt completes successfully. You can expect to get this notification after calls
+	# to EventMachine#connect. Remember that EventMachine makes remote connections
+	# asynchronously, just as with any other kind of network event. #connection_completed
+	# is intended primarily to assist with network diagnostics. For normal protocol
+	# handling, use #post_init to perform initial work on a new connection (such as
+	# send an initial set of data).
+	# #post_init will always be called. #connection_completed will only be called in case
+	# of a successful completion. A connection-attempt which fails will receive a call
+	# to #unbind after the failure.
+	def connection_completed
+	end
 
-  # Call #start_tls at any point to initiate TLS encryption on connected streams.
-  # The method is smart enough to know whether it should perform a server-side
-  # or a client-side handshake. An appropriate place to call #start_tls is in
-  # your redefined #post_init method.
-  #
-  def start_tls
-    EventMachine::start_tls @signature
-  end
+	# Call #start_tls at any point to initiate TLS encryption on connected streams.
+	# The method is smart enough to know whether it should perform a server-side
+	# or a client-side handshake. An appropriate place to call #start_tls is in
+	# your redefined #post_init method.
+	#
+	def start_tls
+		EventMachine::start_tls @signature
+	end
 
 
-  # send_datagram is for sending UDP messages.
-  # This method may be called from any Connection object that refers
-  # to an open datagram socket (see EventMachine#open_datagram_socket).
-  # The method sends a UDP (datagram) packet containing the data you specify,
-  # to a remote peer specified by the IP address and port that you give
-  # as parameters to the method.
-  # Observe that you may send a zero-length packet (empty string).
-  # However, you may not send an arbitrarily-large data packet because
-  # your operating system will enforce a platform-specific limit on
-  # the size of the outbound packet. (Your kernel
-  # will respond in a platform-specific way if you send an overlarge
-  # packet: some will send a truncated packet, some will complain, and
-  # some will silently drop your request).
-  # On LANs, it's usually OK to send datagrams up to about 4000 bytes in length,
-  # but to be really safe, send messages smaller than the Ethernet-packet
-  # size (typically about 1400 bytes). Some very restrictive WANs
-  # will either drop or truncate packets larger than about 500 bytes.
-  #
-  def send_datagram data, recipient_address, recipient_port
-    data = data.to_s
-    EventMachine::send_datagram @signature, data, data.length, recipient_address, recipient_port
-  end
+	# send_datagram is for sending UDP messages.
+	# This method may be called from any Connection object that refers
+	# to an open datagram socket (see EventMachine#open_datagram_socket).
+	# The method sends a UDP (datagram) packet containing the data you specify,
+	# to a remote peer specified by the IP address and port that you give
+	# as parameters to the method.
+	# Observe that you may send a zero-length packet (empty string).
+	# However, you may not send an arbitrarily-large data packet because
+	# your operating system will enforce a platform-specific limit on
+	# the size of the outbound packet. (Your kernel
+	# will respond in a platform-specific way if you send an overlarge
+	# packet: some will send a truncated packet, some will complain, and
+	# some will silently drop your request).
+	# On LANs, it's usually OK to send datagrams up to about 4000 bytes in length,
+	# but to be really safe, send messages smaller than the Ethernet-packet
+	# size (typically about 1400 bytes). Some very restrictive WANs
+	# will either drop or truncate packets larger than about 500 bytes.
+	#
+	def send_datagram data, recipient_address, recipient_port
+		data = data.to_s
+		EventMachine::send_datagram @signature, data, data.length, recipient_address, recipient_port
+	end
 
 
-  # #get_peername is used with stream-connections to obtain the identity
-  # of the remotely-connected peer. If a peername is available, this method
-  # returns a sockaddr structure. The method returns nil if no peername is available.
-  # You can use Socket#unpack_sockaddr_in and its variants to obtain the
-  # values contained in the peername structure returned from #get_peername.
-  def get_peername
-    EventMachine::get_peername @signature
-  end
+	# #get_peername is used with stream-connections to obtain the identity
+	# of the remotely-connected peer. If a peername is available, this method
+	# returns a sockaddr structure. The method returns nil if no peername is available.
+	# You can use Socket#unpack_sockaddr_in and its variants to obtain the
+	# values contained in the peername structure returned from #get_peername.
+	def get_peername
+		EventMachine::get_peername @signature
+	end
 
-  # comm_inactivity_timeout returns the current value (in seconds) of the inactivity-timeout
-  # property of network-connection and datagram-socket objects. A nonzero value
-  # indicates that the connection or socket will automatically be closed if no read or write
-  # activity takes place for at least that number of seconds.
-  # A zero value (the default) specifies that no automatic timeout will take place.
-  def comm_inactivity_timeout
-    EventMachine::get_comm_inactivity_timeout @signature
-  end
+	# Returns the PID (kernel process identifier) of a subprocess
+	# associated with this Connection object. For use with EventMachine#popen
+	# and similar methods. Returns nil when there is no meaningful subprocess.
+	#--
+	#
+	def get_pid
+		EventMachine::get_subprocess_pid @signature
+	end
 
-  # Alias for #set_comm_inactivity_timeout.
-  def comm_inactivity_timeout= value
-      self.send :set_comm_inactivity_timeout, value
-  end
+	# comm_inactivity_timeout returns the current value (in seconds) of the inactivity-timeout
+	# property of network-connection and datagram-socket objects. A nonzero value
+	# indicates that the connection or socket will automatically be closed if no read or write
+	# activity takes place for at least that number of seconds.
+	# A zero value (the default) specifies that no automatic timeout will take place.
+	def comm_inactivity_timeout
+		EventMachine::get_comm_inactivity_timeout @signature
+	end
 
-  # comm_inactivity_timeout= allows you to set the inactivity-timeout property for
-  # a network connection or datagram socket. Specify a non-negative numeric value in seconds.
-  # If the value is greater than zero, the connection or socket will automatically be closed
-  # if no read or write activity takes place for at least that number of seconds.
-  # Specify a value of zero to indicate that no automatic timeout should take place.
-  # Zero is the default value.
-  def set_comm_inactivity_timeout value
-    EventMachine::set_comm_inactivity_timeout @signature, value
-  end
+	# Alias for #set_comm_inactivity_timeout.
+	def comm_inactivity_timeout= value
+		self.send :set_comm_inactivity_timeout, value
+	end
 
-  #--
-  # EXPERIMENTAL. DO NOT RELY ON THIS METHOD TO REMAIN SUPPORTED.
-  # (03Nov06)
-  def reconnect server, port
-      EventMachine::reconnect server, port, self
-  end
+	# comm_inactivity_timeout= allows you to set the inactivity-timeout property for
+	# a network connection or datagram socket. Specify a non-negative numeric value in seconds.
+	# If the value is greater than zero, the connection or socket will automatically be closed
+	# if no read or write activity takes place for at least that number of seconds.
+	# Specify a value of zero to indicate that no automatic timeout should take place.
+	# Zero is the default value.
+	def set_comm_inactivity_timeout value
+		EventMachine::set_comm_inactivity_timeout @signature, value
+	end
+
+	#--
+	# EXPERIMENTAL. DO NOT RELY ON THIS METHOD TO REMAIN SUPPORTED.
+	# (03Nov06)
+	def reconnect server, port
+		EventMachine::reconnect server, port, self
+	end
 
 
 
 
-	#
+	# TODO, document this
 	#
 	#
 	class EventMachine::PeriodicTimer
@@ -1130,7 +1249,7 @@ class Connection
 		end
 	end
 
-	#
+	# TODO, document this
 	#
 	#
 	class EventMachine::Timer
@@ -1150,6 +1269,12 @@ end
 
 end # module EventMachine
 
+
+
+# Save everyone some typing.
+EM = EventMachine
+
+
 # At the bottom of this module, we load up protocol handlers that depend on some
 # of the classes defined here. Eventually we should refactor this out so it's
 # laid out in a more logical way.