eventmachine-maglev- 0.12.10 → 1.0.0.beta.4

data/ext/rubymain.cpp

@@ -31,6 +31,8 @@ Statics
 
 static VALUE EmModule;
 static VALUE EmConnection;
+static VALUE EmConnsHash;
+static VALUE EmTimersHash;
 
 static VALUE EM_eConnectionError;
 static VALUE EM_eUnknownTimerFired;
@@ -51,89 +53,121 @@ static VALUE Intern_ssl_verify_peer;
 static VALUE Intern_notify_readable;
 static VALUE Intern_notify_writable;
 static VALUE Intern_proxy_target_unbound;
+static VALUE Intern_proxy_completed;
+static VALUE Intern_connection_completed;
 
 static VALUE rb_cProcStatus;
 
 struct em_event {
-	unsigned long a1;
-	int a2;
-	const char *a3;
-	unsigned long a4;
+	unsigned long signature;
+	int event;
+	const char *data_str;
+	unsigned long data_num;
 };
 
+static inline VALUE ensure_conn(const unsigned long signature)
+{
+	VALUE conn = rb_hash_aref (EmConnsHash, ULONG2NUM (signature));
+	if (conn == Qnil)
+		rb_raise (EM_eConnectionNotBound, "unknown connection: %lu", signature);
+	return conn;
+}
+
+
 /****************
 t_event_callback
 ****************/
 
-static void event_callback (struct em_event* e)
-{
-	const unsigned long a1 = e->a1;
-	int a2 = e->a2;
-	const char *a3 = e->a3;
-	const unsigned long a4 = e->a4;
-
-	if (a2 == EM_CONNECTION_READ) {
-		VALUE t = rb_ivar_get (EmModule, Intern_at_conns);
-		VALUE q = rb_hash_aref (t, ULONG2NUM (a1));
-		if (q == Qnil)
-			rb_raise (EM_eConnectionNotBound, "received %lu bytes of data for unknown signature: %lu", a4, a1);
-		rb_funcall (q, Intern_receive_data, 1, rb_str_new (a3, a4));
-	}
-	else if (a2 == EM_CONNECTION_NOTIFY_READABLE) {
-		VALUE t = rb_ivar_get (EmModule, Intern_at_conns);
-		VALUE q = rb_hash_aref (t, ULONG2NUM (a1));
-		if (q == Qnil)
-			rb_raise (EM_eConnectionNotBound, "unknown connection: %lu", a1);
-		rb_funcall (q, Intern_notify_readable, 0);
-	}
-	else if (a2 == EM_CONNECTION_NOTIFY_WRITABLE) {
-		VALUE t = rb_ivar_get (EmModule, Intern_at_conns);
-		VALUE q = rb_hash_aref (t, ULONG2NUM (a1));
-		if (q == Qnil)
-			rb_raise (EM_eConnectionNotBound, "unknown connection: %lu", a1);
-		rb_funcall (q, Intern_notify_writable, 0);
-	}
-	else if (a2 == EM_LOOPBREAK_SIGNAL) {
-		rb_funcall (EmModule, Intern_run_deferred_callbacks, 0);
-	}
-	else if (a2 == EM_TIMER_FIRED) {
-		VALUE t = rb_ivar_get (EmModule, Intern_at_timers);
-		VALUE q = rb_funcall (t, Intern_delete, 1, ULONG2NUM (a4));
-		if (q == Qnil) {
-			rb_raise (EM_eUnknownTimerFired, "no such timer: %lu", a4);
-		} else if (q == Qfalse) {
-			/* Timer Canceled */
-		} else {
-			rb_funcall (q, Intern_call, 0);
+static inline void event_callback (struct em_event* e)
+{
+	const unsigned long signature = e->signature;
+	int event = e->event;
+	const char *data_str = e->data_str;
+	const unsigned long data_num = e->data_num;
+
+	switch (event) {
+		case EM_CONNECTION_READ:
+		{
+			VALUE conn = rb_hash_aref (EmConnsHash, ULONG2NUM (signature));
+			if (conn == Qnil)
+				rb_raise (EM_eConnectionNotBound, "received %lu bytes of data for unknown signature: %lu", data_num, signature);
+			rb_funcall (conn, Intern_receive_data, 1, rb_str_new (data_str, data_num));
+			return;
+		}
+		case EM_CONNECTION_ACCEPTED:
+		{
+			rb_funcall (EmModule, Intern_event_callback, 3, ULONG2NUM(signature), INT2FIX(event), ULONG2NUM(data_num));
+			return;
+		}
+		case EM_CONNECTION_UNBOUND:
+		{
+			rb_funcall (EmModule, Intern_event_callback, 3, ULONG2NUM(signature), INT2FIX(event), ULONG2NUM(data_num));
+			return;
+		}
+		case EM_CONNECTION_COMPLETED:
+		{
+			VALUE conn = ensure_conn(signature);
+			rb_funcall (conn, Intern_connection_completed, 0);
+			return;
+		}
+		case EM_CONNECTION_NOTIFY_READABLE:
+		{
+			VALUE conn = ensure_conn(signature);
+			rb_funcall (conn, Intern_notify_readable, 0);
+			return;
+		}
+		case EM_CONNECTION_NOTIFY_WRITABLE:
+		{
+			VALUE conn = ensure_conn(signature);
+			rb_funcall (conn, Intern_notify_writable, 0);
+			return;
+		}
+		case EM_LOOPBREAK_SIGNAL:
+		{
+			rb_funcall (EmModule, Intern_run_deferred_callbacks, 0);
+			return;
+		}
+		case EM_TIMER_FIRED:
+		{
+			VALUE timer = rb_funcall (EmTimersHash, Intern_delete, 1, ULONG2NUM (data_num));
+			if (timer == Qnil) {
+				rb_raise (EM_eUnknownTimerFired, "no such timer: %lu", data_num);
+			} else if (timer == Qfalse) {
+				/* Timer Canceled */
+			} else {
+				rb_funcall (timer, Intern_call, 0);
+			}
+			return;
+		}
+		#ifdef WITH_SSL
+		case EM_SSL_HANDSHAKE_COMPLETED:
+		{
+			VALUE conn = ensure_conn(signature);
+			rb_funcall (conn, Intern_ssl_handshake_completed, 0);
+			return;
+		}
+		case EM_SSL_VERIFY:
+		{
+			VALUE conn = ensure_conn(signature);
+			VALUE should_accept = rb_funcall (conn, Intern_ssl_verify_peer, 1, rb_str_new(data_str, data_num));
+			if (RTEST(should_accept))
+				evma_accept_ssl_peer (signature);
+			return;
+		}
+		#endif
+		case EM_PROXY_TARGET_UNBOUND:
+		{
+			VALUE conn = ensure_conn(signature);
+			rb_funcall (conn, Intern_proxy_target_unbound, 0);
+			return;
+		}
+		case EM_PROXY_COMPLETED:
+		{
+			VALUE conn = ensure_conn(signature);
+			rb_funcall (conn, Intern_proxy_completed, 0);
+			return;
 		}
 	}
-	#ifdef WITH_SSL
-	else if (a2 == EM_SSL_HANDSHAKE_COMPLETED) {
-		VALUE t = rb_ivar_get (EmModule, Intern_at_conns);
-		VALUE q = rb_hash_aref (t, ULONG2NUM (a1));
-		if (q == Qnil)
-			rb_raise (EM_eConnectionNotBound, "unknown connection: %lu", a1);
-		rb_funcall (q, Intern_ssl_handshake_completed, 0);
-	}
-	else if (a2 == EM_SSL_VERIFY) {
-		VALUE t = rb_ivar_get (EmModule, Intern_at_conns);
-		VALUE q = rb_hash_aref (t, ULONG2NUM (a1));
-		if (q == Qnil)
-			rb_raise (EM_eConnectionNotBound, "unknown connection: %lu", a1);
-		VALUE r = rb_funcall (q, Intern_ssl_verify_peer, 1, rb_str_new(a3, a4));
-		if (RTEST(r))
-			evma_accept_ssl_peer (a1);
-	}
-	#endif
-	else if (a2 == EM_PROXY_TARGET_UNBOUND) {
-		VALUE t = rb_ivar_get (EmModule, Intern_at_conns);
-		VALUE q = rb_hash_aref (t, ULONG2NUM (a1));
-		if (q == Qnil)
-			rb_raise (EM_eConnectionNotBound, "unknown connection: %lu", a1);
-		rb_funcall (q, Intern_proxy_target_unbound, 0);
-	}
-	else
-		rb_funcall (EmModule, Intern_event_callback, 3, ULONG2NUM(a1), INT2FIX(a2), a3 ? rb_str_new(a3,a4) : ULONG2NUM(a4));
 }
 
 /*******************
@@ -150,13 +184,13 @@ static void event_error_handler(VALUE unused, VALUE err)
 event_callback_wrapper
 **********************/
 
-static void event_callback_wrapper (const unsigned long a1, int a2, const char *a3, const unsigned long a4)
+static void event_callback_wrapper (const unsigned long signature, int event, const char *data_str, const unsigned long data_num)
 {
 	struct em_event e;
-	e.a1 = a1;
-	e.a2 = a2;
-	e.a3 = a3;
-	e.a4 = a4;
+	e.signature = signature;
+	e.event = event;
+	e.data_str = data_str;
+	e.data_num = data_num;
 
 	if (!rb_ivar_defined(EmModule, Intern_at_error_handler))
 		event_callback(&e);
@@ -170,7 +204,11 @@ t_initialize_event_machine
 
 static VALUE t_initialize_event_machine (VALUE self)
 {
-	evma_initialize_library (event_callback_wrapper);
+	EmConnsHash = rb_ivar_get (EmModule, Intern_at_conns);
+	EmTimersHash = rb_ivar_get (EmModule, Intern_at_timers);
+	assert(EmConnsHash != Qnil);
+	assert(EmTimersHash != Qnil);
+	evma_initialize_library ((EMCallback)event_callback_wrapper);
 	return Qnil;
 }
 
@@ -208,7 +246,7 @@ static VALUE t_start_server (VALUE self, VALUE server, VALUE port)
 {
 	const unsigned long f = evma_create_tcp_server (StringValuePtr(server), FIX2INT(port));
 	if (!f)
-		rb_raise (rb_eRuntimeError, "no acceptor");
+		rb_raise (rb_eRuntimeError, "no acceptor (port is in use or requires root privileges)");
 	return ULONG2NUM (f);
 }
 
@@ -307,9 +345,10 @@ t_get_peername
 
 static VALUE t_get_peername (VALUE self, VALUE signature)
 {
-	struct sockaddr s;
-	if (evma_get_peername (NUM2ULONG (signature), &s)) {
-		return rb_str_new ((const char*)&s, sizeof(s));
+	char buf[1024];
+	socklen_t len = sizeof buf;
+	if (evma_get_peername (NUM2ULONG (signature), (struct sockaddr*)buf, &len)) {
+		return rb_str_new (buf, len);
 	}
 
 	return Qnil;
@@ -321,9 +360,10 @@ t_get_sockname
 
 static VALUE t_get_sockname (VALUE self, VALUE signature)
 {
-	struct sockaddr s;
-	if (evma_get_sockname (NUM2ULONG (signature), &s)) {
-		return rb_str_new ((const char*)&s, sizeof(s));
+	char buf[1024];
+	socklen_t len = sizeof buf;
+	if (evma_get_sockname (NUM2ULONG (signature), (struct sockaddr*)buf, &len)) {
+		return rb_str_new (buf, len);
 	}
 
 	return Qnil;
@@ -390,8 +430,9 @@ t_set_comm_inactivity_timeout
 static VALUE t_set_comm_inactivity_timeout (VALUE self, VALUE signature, VALUE timeout)
 {
 	float ti = RFLOAT_VALUE(timeout);
-	if (evma_set_comm_inactivity_timeout (NUM2ULONG (signature), ti));
+	if (evma_set_comm_inactivity_timeout(NUM2ULONG(signature), ti)) {
 		return Qtrue;
+	}
 	return Qfalse;
 }
 
@@ -411,8 +452,9 @@ t_set_pending_connect_timeout
 static VALUE t_set_pending_connect_timeout (VALUE self, VALUE signature, VALUE timeout)
 {
 	float ti = RFLOAT_VALUE(timeout);
-	if (evma_set_pending_connect_timeout (NUM2ULONG (signature), ti));
+	if (evma_set_pending_connect_timeout(NUM2ULONG(signature), ti)) {
 		return Qtrue;
+	}
 	return Qfalse;
 }
 
@@ -467,6 +509,7 @@ static VALUE t_connect_server (VALUE self, VALUE server, VALUE port)
 	} catch (std::runtime_error e) {
 		rb_raise (EM_eConnectionError, e.what());
 	}
+	return Qnil;
 }
 
 /*********************
@@ -487,6 +530,7 @@ static VALUE t_bind_connect_server (VALUE self, VALUE bind_addr, VALUE bind_port
 	} catch (std::runtime_error e) {
 		rb_raise (EM_eConnectionError, e.what());
 	}
+	return Qnil;
 }
 
 /*********************
@@ -701,18 +745,6 @@ static VALUE t_setuid_string (VALUE self, VALUE username)
 
 
 
-/*************
-t__write_file
-*************/
-
-static VALUE t__write_file (VALUE self, VALUE filename)
-{
-	const unsigned long f = evma__write_file (StringValuePtr (filename));
-	if (!f)
-		rb_raise (rb_eRuntimeError, "file not opened");
-	return ULONG2NUM (f);
-}
-
 /**************
 t_invoke_popen
 **************/
@@ -725,13 +757,17 @@ static VALUE t_invoke_popen (VALUE self, VALUE cmd)
 	#else
 		int len = RARRAY (cmd)->len;
 	#endif
-	if (len > 98)
+	if (len >= 2048)
 		rb_raise (rb_eRuntimeError, "too many arguments to popen");
-	char *strings [100];
+	char *strings [2048];
 	for (int i=0; i < len; i++) {
 		VALUE ix = INT2FIX (i);
 		VALUE s = rb_ary_aref (1, &ix, cmd);
+		#ifdef BUILD_FOR_MAGLEV
 		strings[i] = (char*)StringValuePtr (s);
+		#else
+		strings[i] = StringValuePtr (s);
+		#endif
 	}
 	strings[len] = NULL;
 
@@ -769,8 +805,9 @@ static VALUE t_watch_filename (VALUE self, VALUE fname)
 	try {
 		return ULONG2NUM(evma_watch_filename(StringValuePtr(fname)));
 	} catch (std::runtime_error e) {
-		rb_sys_fail(e.what());
+		rb_raise (EM_eUnsupported, e.what());
 	}
+	return Qnil;
 }
 
 
@@ -794,8 +831,9 @@ static VALUE t_watch_pid (VALUE self, VALUE pid)
 	try {
 		return ULONG2NUM(evma_watch_pid(NUM2INT(pid)));
 	} catch (std::runtime_error e) {
-		rb_sys_fail(e.what());
+		rb_raise (EM_eUnsupported, e.what());
 	}
+	return Qnil;
 }
 
 
@@ -972,11 +1010,12 @@ static VALUE t_get_loop_time (VALUE self)
   static ID at = rb_intern("at");
 #endif
 
-  if (gCurrentLoopTime != 0) {
+  uint64_t current_time = evma_get_current_loop_time();
+  if (current_time != 0) {
 #ifndef HAVE_RB_TIME_NEW
-    return rb_funcall(cTime, at, 2, INT2NUM(gCurrentLoopTime / 1000000), INT2NUM(gCurrentLoopTime % 1000000));
+    return rb_funcall(cTime, at, 2, INT2NUM(current_time / 1000000), INT2NUM(current_time % 1000000));
 #else
-    return rb_time_new(gCurrentLoopTime / 1000000, gCurrentLoopTime % 1000000);
+    return rb_time_new(current_time / 1000000, current_time % 1000000);
 #endif
   }
   return Qnil;
@@ -987,9 +1026,13 @@ static VALUE t_get_loop_time (VALUE self)
 t_start_proxy
 **************/
 
-static VALUE t_start_proxy (VALUE self, VALUE from, VALUE to, VALUE bufsize)
+static VALUE t_start_proxy (VALUE self, VALUE from, VALUE to, VALUE bufsize, VALUE length)
 {
-	evma_start_proxy(NUM2ULONG (from), NUM2ULONG (to), NUM2ULONG(bufsize));
+	try {
+		evma_start_proxy(NUM2ULONG (from), NUM2ULONG (to), NUM2ULONG(bufsize), NUM2ULONG(length));
+	} catch (std::runtime_error e) {
+		rb_raise (EM_eConnectionError, e.what());
+	}
 	return Qnil;
 }
 
@@ -1000,7 +1043,11 @@ t_stop_proxy
 
 static VALUE t_stop_proxy (VALUE self, VALUE from)
 {
-	evma_stop_proxy(NUM2ULONG (from));
+	try{
+		evma_stop_proxy(NUM2ULONG (from));
+	} catch (std::runtime_error e) {
+		rb_raise (EM_eConnectionError, e.what());
+	}
 	return Qnil;
 }
 
@@ -1054,6 +1101,8 @@ extern "C" void Init_rubyeventmachine()
 	Intern_notify_readable = rb_intern ("notify_readable");
 	Intern_notify_writable = rb_intern ("notify_writable");
 	Intern_proxy_target_unbound = rb_intern ("proxy_target_unbound");
+	Intern_proxy_completed = rb_intern ("proxy_completed");
+	Intern_connection_completed = rb_intern ("connection_completed");
 
 	// INCOMPLETE, we need to define class Connections inside module EventMachine
 	// run_machine and run_machine_without_threads are now identical.
@@ -1097,7 +1146,7 @@ extern "C" void Init_rubyeventmachine()
 	rb_define_module_function (EmModule, "resume_connection", (VALUE (*)(...))t_resume, 1);
 	rb_define_module_function (EmModule, "connection_paused?", (VALUE (*)(...))t_paused_p, 1);
 
-	rb_define_module_function (EmModule, "start_proxy", (VALUE (*)(...))t_start_proxy, 3);
+	rb_define_module_function (EmModule, "start_proxy", (VALUE (*)(...))t_start_proxy, 4);
 	rb_define_module_function (EmModule, "stop_proxy", (VALUE (*)(...))t_stop_proxy, 1);
 
 	rb_define_module_function (EmModule, "watch_filename", (VALUE (*)(...))t_watch_filename, 1);
@@ -1123,9 +1172,6 @@ extern "C" void Init_rubyeventmachine()
 	rb_define_module_function (EmModule, "get_heartbeat_interval", (VALUE(*)(...))t_get_heartbeat_interval, 0);
 	rb_define_module_function (EmModule, "set_heartbeat_interval", (VALUE(*)(...))t_set_heartbeat_interval, 1);
 
-	// 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_sockname", (VALUE(*)(...))t_get_sockname, 1);
 	rb_define_module_function (EmModule, "get_subprocess_pid", (VALUE(*)(...))t_get_subprocess_pid, 1);

data/java/src/com/rubyeventmachine/EmReactor.java

@@ -48,6 +48,7 @@ public class EmReactor {
 	public final int EM_SSL_HANDSHAKE_COMPLETED = 108;
 	public final int EM_SSL_VERIFY = 109;
 	public final int EM_PROXY_TARGET_UNBOUND = 110;
+    public final int EM_PROXY_COMPLETED = 111;
 
 	private Selector mySelector;
 	private TreeMap<Long, ArrayList<Long>> Timers;
@@ -441,8 +442,8 @@ public class EmReactor {
 		Connections.get(sig).setCommInactivityTimeout (mills);
 	}
 
-	public void sendDatagram (long sig, String data, int length, String recipAddress, int recipPort) {
-		sendDatagram (sig, ByteBuffer.wrap(data.getBytes()), recipAddress, recipPort);
+	public void sendDatagram (long sig, byte[] data, int length, String recipAddress, int recipPort) {
+		sendDatagram (sig, ByteBuffer.wrap(data), recipAddress, recipPort);
 	}
 
 	public void sendDatagram (long sig, ByteBuffer bb, String recipAddress, int recipPort) {

data/lib/em/buftok.rb

@@ -1,43 +1,29 @@
-# BufferedTokenizer - Statefully split input data by a specifiable token
-#
-# Authors:: Tony Arcieri, Martin Emde
-#
-#----------------------------------------------------------------------------
-#
-# Copyright (C) 2006-07 by Tony Arcieri and Martin Emde
-# 
-# Distributed under the Ruby license (http://www.ruby-lang.org/en/LICENSE.txt)
-#
-#---------------------------------------------------------------------------
-#
-
-# (C)2006 Tony Arcieri, Martin Emde
-# Distributed under the Ruby license (http://www.ruby-lang.org/en/LICENSE.txt)
-
 # BufferedTokenizer takes a delimiter upon instantiation, or acts line-based
 # by default.  It allows input to be spoon-fed from some outside source which
 # receives arbitrary length datagrams which may-or-may-not contain the token
 # by which entities are delimited.
 #
-# Commonly used to parse lines out of incoming data:
+# By default, new BufferedTokenizers will operate on lines delimited by "\n" by default
+# or allow you to specify any delimiter token you so choose, which will then
+# be used by String#split to tokenize the input data
 #
-#  module LineBufferedConnection
-#    def receive_data(data)
-#      (@buffer ||= BufferedTokenizer.new).extract(data).each do |line|
-#        receive_line(line)
-#      end
-#    end
-#  end
-
+# @example Using BufferedTokernizer to parse lines out of incoming data
+#
+#   module LineBufferedConnection
+#     def receive_data(data)
+#       (@buffer ||= BufferedTokenizer.new).extract(data).each do |line|
+#         receive_line(line)
+#       end
+#     end
+#   end
+#
+# @author Tony Arcieri
+# @author Martin Emde
 class BufferedTokenizer
-  # New BufferedTokenizers will operate on lines delimited by "\n" by default
-  # or allow you to specify any delimiter token you so choose, which will then
-  # be used by String#split to tokenize the input data
+  # @param [String] delimiter
+  # @param [Integer] size_limit
   def initialize(delimiter = "\n", size_limit = nil)
-    # Store the specified delimiter
-    @delimiter = delimiter
-
-    # Store the specified size limitation
+    @delimiter  = delimiter
     @size_limit = size_limit
 
     # The input buffer is stored as an array.  This is by far the most efficient
@@ -52,14 +38,18 @@ class BufferedTokenizer
   end
 
   # Extract takes an arbitrary string of input data and returns an array of
-  # tokenized entities, provided there were any available to extract.  This
-  # makes for easy processing of datagrams using a pattern like:
+  # tokenized entities, provided there were any available to extract.
   #
-  #   tokenizer.extract(data).map { |entity| Decode(entity) }.each do ...
+  # @example
+  #
+  #   tokenizer.extract(data).
+  #     map { |entity| Decode(entity) }.each { ... }
+  #
+  # @param [String] data
   def extract(data)
     # Extract token-delimited entities from the input string with the split command.
     # There's a bit of craftiness here with the -1 parameter.  Normally split would
-    # behave no differently regardless of if the token lies at the very end of the 
+    # behave no differently regardless of if the token lies at the very end of the
     # input buffer or not (i.e. a literal edge case)  Specifying -1 forces split to
     # return "" in this case, meaning that the last entry in the list represents a
     # new segment of data where the token has not been encountered
@@ -70,7 +60,7 @@ class BufferedTokenizer
       raise 'input buffer full' if @input_size + entities.first.size > @size_limit
       @input_size += entities.first.size
     end
-    
+
     # Move the first entry in the resulting array into the input buffer.  It represents
     # the last segment of a token-delimited entity unless it's the only entry in the list.
     @input << entities.shift
@@ -85,36 +75,16 @@ class BufferedTokenizer
     # and add it to our list of discovered entities.
     entities.unshift @input.join
 
-=begin
-    # Note added by FC, 10Jul07. This paragraph contains a regression. It breaks
-    # empty tokens. Think of the empty line that delimits an HTTP header. It will have
-    # two "\n" delimiters in a row, and this code mishandles the resulting empty token.
-    # It someone figures out how to fix the problem, we can re-enable this code branch.
-    # Multi-character token support.
-    # Split any tokens that were incomplete on the last iteration buf complete now.
-    entities.map! do |e|
-      e.split @delimiter, -1
-    end
-    # Flatten the resulting array.  This has the side effect of removing the empty
-    # entry at the end that was produced by passing -1 to split.  Add it again if
-    # necessary.
-    if (entities[-1] == [])
-      entities.flatten! << []
-    else
-      entities.flatten!
-    end
-=end
-
     # Now that we've hit a token, joined the input buffer and added it to the entities
     # list, we can go ahead and clear the input buffer.  All of the segments that were
     # stored before the join can now be garbage collected.
     @input.clear
-    
+
     # The last entity in the list is not token delimited, however, thanks to the -1
-    # passed to split.  It represents the beginning of a new list of as-yet-untokenized  
+    # passed to split.  It represents the beginning of a new list of as-yet-untokenized
     # data, so we add it to the start of the list.
     @input << entities.pop
-    
+
     # Set the new input buffer size, provided we're keeping track
     @input_size = @input.first.size if @size_limit
 
@@ -122,16 +92,18 @@ class BufferedTokenizer
     # in the first place.  Hooray!
     entities
   end
-  
+
   # Flush the contents of the input buffer, i.e. return the input buffer even though
-  # a token has not yet been encountered
+  # a token has not yet been encountered.
+  #
+  # @return [String]
   def flush
     buffer = @input.join
     @input.clear
     buffer
   end
 
-  # Is the buffer empty?
+  # @return [Boolean]
   def empty?
     @input.empty?
   end

data/lib/em/callback.rb

@@ -1,26 +1,58 @@
 module EventMachine
-  # Utility method for coercing arguments to an object that responds to #call
+  # Utility method for coercing arguments to an object that responds to :call.
   # Accepts an object and a method name to send to, or a block, or an object
-  # that responds to call.
+  # that responds to :call.
   #
-  #  cb = EM.Callback{ |msg| puts(msg) }
+  # @example EventMachine.Callback used with a block. Returns that block.
+  #
+  #  cb = EventMachine.Callback do |msg|
+  #    puts(msg)
+  #  end
+  #  # returned object is a callable
   #  cb.call('hello world')
   #
-  #  cb = EM.Callback(Object, :puts)
+  #
+  # @example EventMachine.Callback used with an object (to be more specific, class object) and a method name, returns an object that responds to #call
+  #
+  #  cb = EventMachine.Callback(Object, :puts)
+  #  # returned object is a callable that delegates to Kernel#puts (in this case Object.puts)
   #  cb.call('hello world')
   #
-  #  cb = EM.Callback(proc{ |msg| puts(msg) })
+  #
+  # @example EventMachine.Callback used with an object that responds to #call. Returns the argument.
+  #
+  #  cb = EventMachine.Callback(proc{ |msg| puts(msg) })
+  #  # returned object is a callable
   #  cb.call('hello world')
   #
+  #
+  # @overload Callback(object, method)
+  #   Wraps `method` invocation on `object` into an object that responds to #call that proxies all the arguments to that method
+  #   @param [Object] Object to invoke method on
+  #   @param [Symbol] Method name
+  #   @return [<#call>] An object that responds to #call that takes any number of arguments and invokes method on object with those arguments
+  #
+  # @overload Callback(object)
+  #   Returns callable object as is, without any coercion
+  #   @param [<#call>] An object that responds to #call
+  #   @return [<#call>] Its argument
+  #
+  # @overload Callback(&block)
+  #   Returns block passed to it without any coercion
+  #   @return [<#call>] Block passed to this method
+  #
+  # @raise [ArgumentError] When argument doesn't respond to #call, method name is missing or when invoked without arguments and block isn't given
+  #
+  # @return [<#call>]
   def self.Callback(object = nil, method = nil, &blk)
     if object && method
-      lambda { |*args| object.send method, *args }
+      lambda { |*args| object.__send__ method, *args }
     else
       if object.respond_to? :call
         object
-      else 
+      else
         blk || raise(ArgumentError)
-      end
-    end
-  end
-end
+      end # if
+    end # if
+  end # self.Callback
+end # EventMachine