eventmachine-le 1.1.0.beta.1

data/lib/em/messages.rb

@@ -0,0 +1,66 @@
+#--
+#
+# 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/em/pool.rb

@@ -0,0 +1,151 @@
+module EventMachine
+  # = EventMachine::Pool
+  #
+  # A simple async resource pool based on a resource and work queue. Resources
+  # are enqueued and work waits for resources to become available.
+  #
+  # Example:
+  #
+  #    EM.run do
+  #      pool  = EM::Pool.new
+  #      spawn = lambda { pool.add EM::HttpRequest.new('http://example.org') }
+  #      10.times { spawn[] }
+  #      done, scheduled = 0, 0
+  #    
+  #      check = lambda do
+  #        done += 1
+  #        if done >= scheduled
+  #          EM.stop
+  #        end
+  #      end
+  #    
+  #      pool.on_error { |conn| spawn[] }
+  #    
+  #      100.times do
+  #        pool.perform do |conn|
+  #          req = conn.get :path => '/', :keepalive => true
+  #    
+  #          req.callback do
+  #            p [:success, conn.object_id, i, req.response.size]
+  #            check[]
+  #          end
+  #    
+  #          req.errback { check[] }
+  #    
+  #          req
+  #        end
+  #      end
+  #    end
+  #
+  # Resources are expected to be controlled by an object responding to a
+  # deferrable/completion style API with callback and errback blocks.
+  #
+  class Pool
+
+    def initialize
+      @resources = EM::Queue.new
+      @removed = []
+      @contents = []
+      @on_error = nil
+    end
+
+    def add resource
+      @contents << resource
+      requeue resource
+    end
+
+    def remove resource
+      @contents.delete resource
+      @removed << resource
+    end
+
+    # Returns a list for introspection purposes only. You should *NEVER* call
+    # modification or work oriented methods on objects in this list. A good
+    # example use case is periodic statistics collection against a set of
+    # connection resources.
+    #
+    # For example: 
+    #     pool.contents.inject(0) { |sum, connection| connection.num_bytes }
+    def contents
+      @contents.dup
+    end
+
+    # Define a default catch-all for when the deferrables returned by work
+    # blocks enter a failed state. By default all that happens is that the
+    # resource is returned to the pool. If on_error is defined, this block is
+    # responsible for re-adding the resource to the pool if it is still usable.
+    # In other words, it is generally assumed that on_error blocks explicitly
+    # handle the rest of the lifetime of the resource.
+    def on_error *a, &b
+      @on_error = EM::Callback(*a, &b)
+    end
+
+    # Perform a given #call-able object or block. The callable object will be
+    # called with a resource from the pool as soon as one is available, and is
+    # expected to return a deferrable.
+    # 
+    # The deferrable will have callback and errback added such that when the
+    # deferrable enters a finished state, the object is returned to the pool.
+    #
+    # If on_error is defined, then objects are not automatically returned to the
+    # pool.
+    def perform(*a, &b)
+      work = EM::Callback(*a, &b)
+
+      @resources.pop do |resource|
+        if removed? resource
+          @removed.delete resource
+          reschedule work
+        else
+          process work, resource
+        end
+      end
+    end
+    alias reschedule perform
+
+    # A peek at the number of enqueued jobs waiting for resources
+    def num_waiting
+      @resources.num_waiting
+    end
+
+    # Removed will show resources in a partial pruned state. Resources in the
+    # removed list may not appear in the contents list if they are currently in
+    # use.
+    def removed? resource
+      @removed.include? resource
+    end
+
+    protected
+    def requeue resource
+      @resources.push resource
+    end
+
+    def failure resource
+      if @on_error
+        @contents.delete resource
+        @on_error.call resource
+        # Prevent users from calling a leak.
+        @removed.delete resource
+      else
+        requeue resource
+      end
+    end
+
+    def completion deferrable, resource
+      deferrable.callback { requeue resource }
+      deferrable.errback  { failure resource }
+    end
+
+    def process work, resource
+      deferrable = work.call resource
+      if deferrable.kind_of?(EM::Deferrable)
+        completion deferrable, resource
+      else
+        raise ArgumentError, "deferrable expected from work"
+      end
+    rescue Exception
+      failure resource
+      raise
+    end
+  end
+end

data/lib/em/process_watch.rb

@@ -0,0 +1,45 @@
+module EventMachine
+
+  # This is subclassed from EventMachine::Connection for use with the process monitoring API. Read the
+  # documentation on the instance methods of this class, and for a full explanation see EventMachine.watch_process.
+  class ProcessWatch < Connection
+    # @private
+    Cfork = 'fork'.freeze
+    # @private
+    Cexit = 'exit'.freeze
+
+    # @private
+    def receive_data(data)
+      case data
+      when Cfork
+        process_forked
+      when Cexit
+        process_exited
+      end
+    end
+
+    # Returns the pid that EventMachine::watch_process was originally called with.
+    def pid
+      @pid
+    end
+
+    # Should be redefined with the user's custom callback that will be fired when the prcess is forked.
+    #
+    # There is currently not an easy way to get the pid of the forked child.
+    def process_forked
+    end
+
+    # Should be redefined with the user's custom callback that will be fired when the process exits.
+    #
+    # stop_watching is called automatically after this callback
+    def process_exited
+    end
+
+    # Discontinue monitoring of the process.
+    # This will be called automatically when a process dies. User code may call it as well.
+    def stop_watching
+      EventMachine::unwatch_pid(@signature)
+    end
+  end
+
+end

data/lib/em/processes.rb

@@ -0,0 +1,123 @@
+#--
+#
+# Author:: Francis Cianfrocca (gmail: blackhedd)
+# Homepage::  http://rubyeventmachine.com
+# Date:: 13 Dec 07
+# 
+# See EventMachine and EventMachine::Connection for documentation and
+# usage examples.
+#
+#----------------------------------------------------------------------------
+#
+# Copyright (C) 2006-08 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.
+#
+#---------------------------------------------------------------------------
+#
+# 
+
+
+module EventMachine
+
+  # EM::DeferrableChildProcess is a sugaring of a common use-case
+  # involving EM::popen.
+  # Call the #open method on EM::DeferrableChildProcess, passing
+  # a command-string. #open immediately returns an EM::Deferrable
+  # object. It also schedules the forking of a child process, which
+  # will execute the command passed to #open.
+  # When the forked child terminates, the Deferrable will be signalled
+  # and execute its callbacks, passing the data that the child process
+  # wrote to stdout.
+  #
+  class DeferrableChildProcess < EventMachine::Connection
+    include EventMachine::Deferrable
+
+    # @private
+    def initialize
+      super
+      @data = []
+    end
+
+    # Sugars a common use-case involving forked child processes.
+    # #open takes a String argument containing an shell command
+    # string (including arguments if desired). #open immediately
+    # returns an EventMachine::Deferrable object, without blocking.
+    #
+    # It also invokes EventMachine#popen to run the passed-in
+    # command in a forked child process.
+    #
+    # When the forked child terminates, the Deferrable that
+    # #open calls its callbacks, passing the data returned
+    # from the child process.
+    #
+    def self.open cmd
+      EventMachine.popen( cmd, DeferrableChildProcess )
+    end
+
+    # @private
+    def receive_data data
+      @data << data
+    end
+
+    # @private
+    def unbind
+      succeed( @data.join )
+    end
+  end
+
+  # @private
+  class SystemCmd < EventMachine::Connection
+    def initialize cb
+      @cb = cb
+      @output = []
+    end
+    def receive_data data
+      @output << data
+    end
+    def unbind
+      @cb.call @output.join(''), get_status if @cb
+    end
+  end
+
+  # EM::system is a simple wrapper for EM::popen. It is similar to Kernel::system, but requires a
+  # single string argument for the command and performs no shell expansion.
+  #
+  # The block or proc passed to EM::system is called with two arguments: the output generated by the command,
+  # and a Process::Status that contains information about the command's execution.
+  #
+  #  EM.run{
+  #    EM.system('ls'){ |output,status| puts output if status.exitstatus == 0 }
+  #  }
+  #
+  # You can also supply an additional proc to send some data to the process:
+  #
+  #  EM.run{
+  #    EM.system('sh', proc{ |process|
+  #      process.send_data("echo hello\n")
+  #      process.send_data("exit\n")
+  #    }, proc{ |out,status|
+  #      puts(out)
+  #    })
+  #  }
+  #
+  # Like EventMachine.popen, EventMachine.system currently does not work on windows.
+  # It returns the pid of the spawned process.
+  def EventMachine::system cmd, *args, &cb
+    cb ||= args.pop if args.last.is_a? Proc
+    init = args.pop if args.last.is_a? Proc
+
+    # merge remaining arguments into the command
+    cmd = ([cmd] + args.map{|a|a.to_s.dump}).join(' ')
+
+    EM.get_subprocess_pid(EM.popen(cmd, SystemCmd, cb) do |c|
+      init[c] if init
+    end.signature)
+  end
+end

data/lib/em/protocols.rb

@@ -0,0 +1,37 @@
+module EventMachine
+  # This module contains various protocol implementations, including:
+  # - HttpClient and HttpClient2
+  # - Stomp
+  # - Memcache
+  # - SmtpClient and SmtpServer
+  # - SASLauth and SASLauthclient
+  # - LineProtocol, LineAndTextProtocol and LineText2
+  # - HeaderAndContentProtocol
+  # - Postgres3
+  # - ObjectProtocol
+  #
+  # The protocol implementations live in separate files in the protocols/ subdirectory,
+  # but are auto-loaded when they are first referenced in your application.
+  #
+  # EventMachine::Protocols is also aliased to EM::P for easier usage.
+  #
+  module Protocols
+    # TODO : various autotools are completely useless with the lack of naming
+    # convention, we need to correct that!
+    autoload :TcpConnectTester, 'em/protocols/tcptest'
+    autoload :HttpClient, 'em/protocols/httpclient'
+    autoload :HttpClient2, 'em/protocols/httpclient2'
+    autoload :LineAndTextProtocol, 'em/protocols/line_and_text'
+    autoload :HeaderAndContentProtocol, 'em/protocols/header_and_content'
+    autoload :LineText2, 'em/protocols/linetext2'
+    autoload :Stomp, 'em/protocols/stomp'
+    autoload :SmtpClient, 'em/protocols/smtpclient'
+    autoload :SmtpServer, 'em/protocols/smtpserver'
+    autoload :SASLauth, 'em/protocols/saslauth'
+    autoload :Memcache, 'em/protocols/memcache'
+    autoload :Postgres3, 'em/protocols/postgres3'
+    autoload :ObjectProtocol, 'em/protocols/object_protocol'
+    autoload :Socks4, 'em/protocols/socks4'
+    autoload :LineProtocol, 'em/protocols/line_protocol'
+  end
+end

data/lib/em/protocols/header_and_content.rb

@@ -0,0 +1,138 @@
+#--
+#
+# Author:: Francis Cianfrocca (gmail: blackhedd)
+# Homepage::  http://rubyeventmachine.com
+# Date:: 15 Nov 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.
+#
+#---------------------------------------------------------------------------
+#
+#
+
+module EventMachine
+  module Protocols
+
+    # === Usage
+    #
+    #  class RequestHandler < EM::P::HeaderAndContentProtocol
+    #    def receive_request headers, content
+    #      p [:request, headers, content]
+    #    end
+    #  end
+    #
+    #  EM.run{
+    #    EM.start_server 'localhost', 80, RequestHandler
+    #  }
+    #
+    #--
+    # Originally, this subclassed LineAndTextProtocol, which in
+    # turn relies on BufferedTokenizer, which doesn't gracefully
+    # handle the transitions between lines and binary text.
+    # Changed 13Sep08 by FCianfrocca.
+    class HeaderAndContentProtocol < Connection
+      include LineText2
+
+      ContentLengthPattern = /Content-length:\s*(\d+)/i
+
+      def initialize *args
+        super
+        init_for_request
+      end
+
+      def receive_line line
+        case @hc_mode
+        when :discard_blanks
+          unless line == ""
+            @hc_mode = :headers
+            receive_line line
+          end
+        when :headers
+          if line == ""
+            raise "unrecognized state" unless @hc_headers.length > 0
+            if respond_to?(:receive_headers)
+              receive_headers @hc_headers
+            end
+            # @hc_content_length will be nil, not 0, if there was no content-length header.
+            if @hc_content_length.to_i > 0
+              set_binary_mode @hc_content_length
+            else
+              dispatch_request
+            end
+          else
+            @hc_headers << line
+            if ContentLengthPattern =~ line
+              # There are some attacks that rely on sending multiple content-length
+              # headers. This is a crude protection, but needs to become tunable.
+              raise "extraneous content-length header" if @hc_content_length
+              @hc_content_length = $1.to_i
+            end
+            if @hc_headers.length == 1 and respond_to?(:receive_first_header_line)
+              receive_first_header_line line
+            end
+          end
+        else
+          raise "internal error, unsupported mode"
+        end
+      end
+
+      def receive_binary_data text
+        @hc_content = text
+        dispatch_request
+      end
+
+      def dispatch_request
+        if respond_to?(:receive_request)
+          receive_request @hc_headers, @hc_content
+        end
+        init_for_request
+      end
+      private :dispatch_request
+
+      def init_for_request
+        @hc_mode = :discard_blanks
+        @hc_headers = []
+        # originally was @hc_headers ||= []; @hc_headers.clear to get a performance
+        # boost, but it's counterproductive because a subclassed handler will have to
+        # call dup to use the header array we pass in receive_headers.
+
+        @hc_content_length = nil
+        @hc_content = ""
+      end
+      private :init_for_request
+
+      # Basically a convenience method. We might create a subclass that does this
+      # automatically. But it's such a performance killer.
+      def headers_2_hash hdrs
+        self.class.headers_2_hash hdrs
+      end
+
+      class << self
+        def headers_2_hash hdrs
+          hash = {}
+          hdrs.each {|h|
+            if /\A([^\s:]+)\s*:\s*/ =~ h
+              tail = $'.dup
+              hash[ $1.downcase.gsub(/-/,"_").intern ] = tail
+            end
+          }
+          hash
+        end
+      end
+
+    end
+  end
+end