eventmachine 0.5.3 → 0.7.0

data/lib/eventmachine.rb

@@ -1,6 +1,6 @@
-# $Id: eventmachine.rb 52 2006-05-16 01:01:46Z blackhedd $
+# $Id: eventmachine.rb 283 2006-11-22 14:44:38Z blackhedd $
 #
-# Author:: blackhedd (gmail address: garbagecat20).
+# Author:: blackhedd (gmail address: garbagecat10).
 # Date:: 8 Apr 2006
 # 
 # Copyright (C) 2006 by Francis Cianfrocca. All Rights Reserved.
@@ -34,7 +34,31 @@
 #
 # 
 
-require 'rubyeventmachine'
+
+#-- Select in a library based on a global variable.
+case $eventmachine_library
+when :pure_ruby
+  require 'pr_eventmachine'
+when :extension
+  require 'rubyeventmachine'
+else
+  # This is the case that most user code will take.
+  # Prefer the extension if available.
+  begin
+    require 'rubyeventmachine'
+  rescue LoadError
+    require 'pr_eventmachine'
+  end
+end
+
+
+require "eventmachine_version"
+require 'em/deferrable'
+require 'em/eventable'
+#-- Additional requires are at the BOTTOM of this file, because they
+#-- depend on stuff defined in here. Refactor that someday.
+
+
 
 # == Introduction
 # EventMachine provides a fast, lightweight framework for implementing
@@ -132,7 +156,6 @@ require 'rubyeventmachine'
 # 
 module EventMachine
 
-  VERSION = "0.5.3"
 
   # EventMachine::run initializes and runs an event loop.
   # This method only returns if user-callback code calls stop_event_loop.
@@ -187,7 +210,7 @@ module EventMachine
   # Ruby threads.
   def EventMachine::run_without_threads &block
     #EventMachine::run false, &block
-    EventMachine::run &block
+    EventMachine::run(&block)
   end
 
   # EventMachine#add_timer adds a one-shot timer to the event loop.
@@ -226,12 +249,15 @@ module EventMachine
   #  }
   #
   #
+  #--
+  # Changed 04Oct06: We now pass the interval as an integer number of milliseconds.
+  #
   def EventMachine::add_timer *args, &block
     interval = args.shift
     code = args.shift || block
     if code
       # check too many timers!
-      s = add_oneshot_timer interval
+      s = add_oneshot_timer((interval * 1000).to_i)
       @timers[s] = code
     end
   end
@@ -409,7 +435,7 @@ module EventMachine
   #  }
   #  
   #
-  def EventMachine::start_server server, port, handler=nil
+  def EventMachine::start_server server, port, handler=nil, &block
     klass = if (handler and handler.is_a?(Class))
       handler
     else
@@ -417,7 +443,19 @@ module EventMachine
     end
 
     s = start_tcp_server server, port
-    @acceptors[s] = klass
+    @acceptors[s] = [klass,block]
+  end
+
+
+  def EventMachine::start_unix_domain_server filename, handler=nil, &block
+    klass = if (handler and handler.is_a?(Class))
+      handler
+    else
+      Class.new( Connection ) {handler and include handler}
+    end
+
+    s = start_unix_server filename
+    @acceptors[s] = [klass,block]
   end
 
   # EventMachine#connect initiates a TCP connection to a remote
@@ -533,6 +571,29 @@ module EventMachine
   end
 
 
+    #--
+    # EXPERIMENTAL. DO NOT RELY ON THIS METHOD TO BE HERE IN THIS FORM, OR AT ALL.
+    # (03Nov06)
+    # Observe, the test for already-connected FAILS if we call a reconnect inside post_init,
+    # because we haven't set up the connection in @conns by that point.
+    # RESIST THE TEMPTATION to "fix" this problem by redefining the behavior of post_init.
+    #
+    # Changed 22Nov06: if called on an already-connected handler, just return the
+    # handler and do nothing more. Originally this condition raised an exception.
+    # We may want to change it yet again and call the block, if any.
+    #
+    def EventMachine::reconnect server, port, handler
+	raise "invalid handler" unless handler.respond_to?(:connection_completed)
+	#raise "still connected" if @conns.has_key?(handler.signature)
+	return handler if @conns.has_key?(handler.signature)
+	s = connect_server server, port
+	handler.signature = s
+	@conns[s] = handler
+	block_given? and yield handler
+	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
@@ -586,6 +647,25 @@ module EventMachine
   # 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
+
+    s = open_udp_socket address, port
+    c = klass.new s
+    @conns[s] = c
+    block_given? and yield c
+    c
+  end
+=begin
+  (Original, replaced 01Oct06)
   def self::open_datagram_socket address, port, handler=nil
     s = open_udp_socket address, port
     klass = Class.new( Connection ) {
@@ -596,6 +676,93 @@ module EventMachine
     block_given? and yield c
     c
   end
+=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
+
+
+  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
+
 
 
   private
@@ -613,16 +780,44 @@ module EventMachine
         raise ConnectionNotBound
       end
     when ConnectionAccepted
-      accep = @acceptors[conn_binding] or raise NoHandlerForAcceptedConnection
+      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
 
 
+  # Documentation stub
+  #--
+  # This is a provisional implementation of a stream-oriented file access object.
+  # We also experiment with wrapping up some better exception reporting.
+  class << self
+    def _open_file_for_writing filename, handler=nil
+      klass = if (handler and handler.is_a?(Class))
+        handler
+      else
+        Class.new( Connection ) {handler and include handler}
+      end
+
+      s = _write_file filename
+      c = klass.new s
+      @conns[s] = c
+      block_given? and yield c
+      c
+    end
+  end
+
 
 # EventMachine::Connection is a class that is instantiated
 # by EventMachine's processing loop whenever a new connection
@@ -650,6 +845,9 @@ module EventMachine
 #
 class Connection
 
+    # EXPERIMENTAL. Added the reconnect methods, which may go away.
+    attr_accessor :signature
+
   def initialize sig #:nodoc:
     @signature = sig
     post_init
@@ -770,7 +968,24 @@ class Connection
     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
 
+  # 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
@@ -800,8 +1015,58 @@ class Connection
   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
+
+  # Alias for #set_comm_inactivity_timeout.
+  def comm_inactivity_timeout= value
+      self.send :set_comm_inactivity_timeout, value
+  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
+
 end
 
 
 end # module 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.
+#
+
+require 'protocols/tcptest'
+require 'protocols/httpclient'
+require 'protocols/line_and_text'
+require 'protocols/header_and_content'
+

data/lib/eventmachine_version.rb

@@ -0,0 +1,42 @@
+# $Id: eventmachine_version.rb 221 2006-08-07 13:17:51Z blackhedd $
+#
+# Author:: blackhedd (gmail address: garbagecat10).
+# Date:: 8 Apr 2006
+# 
+# Copyright (C) 2006 by Francis Cianfrocca. All Rights Reserved.
+#
+# This program is made available under the terms of the GPL version 2.
+#
+# See EventMachine and EventMachine::Connection for documentation and
+# usage examples.
+#
+#----------------------------------------------------------------------------
+#
+# Copyright (C) 2006 by Francis Cianfrocca. All Rights Reserved.
+#
+# Gmail: garbagecat10
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of 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.
+#
+# 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.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+#
+#---------------------------------------------------------------------------
+#
+# 
+
+module EventMachine
+
+  VERSION = "0.7.0"
+
+end
+

data/lib/evma/callback.rb

@@ -0,0 +1,35 @@
+# $Id: callback.rb 88 2006-05-19 03:42:54Z blackhedd $
+#
+# Homepage::  http://rubyeventmachine.com
+# Copyright:: (C) 2006 by Francis Cianfrocca. All Rights Reserved.
+# Email:: gmail address: garbagecat10
+#
+# Available under the GNU Lesser General Public License.
+# See the file COPYING in the distribution for full licensing information.
+#-------------------------------------------------------------------
+# This file is part of Ruby/EventMachine.
+#
+# Ruby/EventMachine is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation; either version 2.1 of the License, or
+# (at your option) any later version.
+# 
+# Ruby/EventMachine 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.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with Ruby/EventMachine; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+#-------------------------------------------------------------------
+#
+
+
+module EventMachine
+
+def self.event_callback target, opcode, data
+  Evma::Container.callback target, opcode, data
+end
+
+end # module EventMachine

data/lib/evma/container.rb

@@ -0,0 +1,77 @@
+# $Id: container.rb 90 2006-05-19 04:58:15Z blackhedd $
+#
+# Homepage::  http://rubyeventmachine.com
+# Copyright:: (C) 2006 by Francis Cianfrocca. All Rights Reserved.
+# Email:: gmail address: garbagecat10
+#
+# Available under the GNU Lesser General Public License.
+# See the file COPYING in the distribution for full licensing information.
+#-------------------------------------------------------------------
+# This file is part of Ruby/EventMachine.
+#
+# Ruby/EventMachine is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation; either version 2.1 of the License, or
+# (at your option) any later version.
+# 
+# Ruby/EventMachine 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.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with Ruby/EventMachine; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+#-------------------------------------------------------------------
+#
+
+
+require 'singleton'
+
+module Evma
+
+class ContainerHasObject < Exception; end
+class UnsupportedCallback < Exception; end
+class UnknownTarget < Exception; end
+
+class Container
+  include Singleton
+
+  def initialize
+    @objects = {}
+  end
+
+  def self.store obj
+    instance.store obj
+  end
+
+  def self.callback target, opcode, data
+    instance.callback target, opcode, data
+  end
+
+  def store obj
+    sig = obj.signature
+    raise ContainerHasObject.new(sig) if @objects.has_key?(sig)
+    @objects[sig] = obj
+  end
+
+  def callback target, opcode, data
+    case opcode
+    when 101 # received data
+      obj = @objects[target] or raise UnknownTarget.new( target )
+      obj.receive_data data
+    when 102 # unbind
+      obj = @objects[target] or raise UnknownTarget.new( target )
+      obj.unbind
+      @objects.delete obj.signature
+    when 103 # accept
+      obj = @objects[target] or raise UnknownTarget.new( target )
+      obj.accept data
+    else
+      raise UnsupportedCallback.new( opcode.to_s )
+    end
+  end
+
+end # class Container
+end # module Evma
+

data/lib/evma/factory.rb

@@ -0,0 +1,80 @@
+# $Id: factory.rb 90 2006-05-19 04:58:15Z blackhedd $
+#
+# Homepage::  http://rubyeventmachine.com
+# Copyright:: (C) 2006 by Francis Cianfrocca. All Rights Reserved.
+# Email:: gmail address: garbagecat10
+#
+# Available under the GNU Lesser General Public License.
+# See the file COPYING in the distribution for full licensing information.
+#-------------------------------------------------------------------
+# This file is part of Ruby/EventMachine.
+#
+# Ruby/EventMachine is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation; either version 2.1 of the License, or
+# (at your option) any later version.
+# 
+# Ruby/EventMachine 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.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with Ruby/EventMachine; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+#-------------------------------------------------------------------
+#
+
+
+module Evma
+class ProtocolFactory < Protocol
+
+  #--
+  # default implementation raises an exception.
+  # we expect subclasses to override this.
+  # we can't do anything reasonable here because
+  def accept new_object
+    # don't bother calling Evma::Reactor.instance, since only Reactor can call accept
+    Evma::Container.store Evma::Protocol.new( new_object )
+    EventMachine.close_connection new_object, false
+  end
+
+
+end # class ProtocolFactory
+end # module Evma
+
+######################################
+
+module Evma
+class TcpSocket
+
+  def self.connect server, port, protocol_handler = Evma::Protocol
+    Evma::Reactor.instance # ensure initialization
+    sig = EventMachine.connect_server server, port
+    Evma::Container.store protocol_handler.new( sig )
+  end
+
+end
+end # module Evma
+
+######################################
+
+module Evma
+class TcpServerFactory < Evma::ProtocolFactory
+
+  def initialize server, port, protocol_handler = Evma::Protocol
+    Evma::Reactor.instance # ensure initialization
+    sig = EventMachine.start_tcp_server server, port
+    super sig
+    @protocol_handler = protocol_handler
+    Evma::Container.store self
+  end
+
+  def accept new_obj
+    # don't bother calling Evma::Reactor.instance, since only Reactor can call accept
+    Evma::Container.store @protocol_handler.new( new_obj )
+  end
+
+end
+end # module Evma
+