oldmoe-reactor 0.2.0

data/README

@@ -0,0 +1,42 @@
+Reactor
+
+A reactor library with the very original name of "Reactor". 
+
+What is a reactor any way?
+
+A reactor library is one that provides an asynchronus event handling mechanism. Ruby already has a couple of those. The most prominent are EventMachine and Rev. Many high performing Ruby applications like Thin and Evented Mongrel are utilizing EventMachine for event handling. Both Rev and EventMachine build atop native reactor implementations written in C or C++. While this ensures high performance it makes some integration aspects with Ruby a bit quirky. Sometimes even at a noticable performance cost.
+
+This is why I thought of building Reactor. A much simpler reactor library in pure Ruby that attempts to use as much of the Ruby built in classes and standard libraries as possible. It only provides a minimal API that does not attempt to be so smart. It differs from EventMachine and Rev in the following aspects.
+
+1 - Pure Ruby, no C or C++ code involved
+2 - Very small (~100 lines of code)
+3 - Uses the vanilla Ruby socket and server implementations
+4 - Decent (high) performance on Ruby 1.9.1
+5 - Ruby threading friendly (naturally)
+6 - You can have multiple reactors running (like Rev and unlike EventMachine)
+
+Usage is simple, here's a simple Echo server that uses Reactor
+
+require 'reactor'
+require 'socket'
+
+reactor = Reactor::Base.new
+server = TCPServer.new("0.0.0.0",8080)
+
+reactor.attach(:read, server) do |server|
+  conn = server.accept
+  conn.write(conn.gets)
+  conn.close
+end
+
+reactor.run # blocking call, will run for ever (no signal handling currently)
+
+The server is a normal Ruby TCPServer. It attaches itself to the reactor and asks to be notified if there is data to be read on the wire. A block is provided that will handle those notifications. Alternatively, the server can implement a notify_readable method that will be fired instead.
+
+Any IO object can be attached to the reactor but it doesn't make much sense to attach actual files since they will block upon reading or writing anyway. Sockets and pipes will work in a non-blocking manner though.
+
+Reactor is using Ruby's IO.select behind the scenes. This limits its ability to scale in comparison to something like EventMachine or Rev which are able to utilize Epoll and Kqueue which scale much better. This is not a major concern though. Most servers listen to a few fds most of the time, which is a bit faster when using select. Besides one can hope that Ruby will be able to use Epoll and Kqueue some day which will translate to direct benefit to Reactor.
+
+Todo
+
+The timers code needs to be reimplemented as a red black tree or a skip list to avoid the current O(n) cost. It works just fine at its current form for a few timers though (tens or even hundreds)

data/lib/reactor.rb

@@ -0,0 +1,226 @@
+$:.unshift File.expand_path(File.dirname(__FILE__))
+
+require 'util'
+require 'timer'
+
+module Reactor
+  # A small, fast, pure Ruby reactor library
+  #
+  # Has the following features:
+  #
+  #  - Pure Ruby, no compilation involved
+  #  - Attach/detach IO objects for readability and writability notifications
+  #  - Add blocks of code that get executed after some time
+  #  - Multiple reactors can co-exist (each in a separate thread of course)
+  #
+  # Lacks the following features: 
+  #
+  #  - No Epoll or Kqueue support since it relies on Ruby's IO.select 
+  #      (Yaki Schloba's Ktools can help here)
+  #  - While you can have several reactors in several threads you cannot manipulate
+  #    a single reactor from multiple threads.
+  # 
+  # Rationale
+  #
+  #  - Reactor libraries are re-implementing every bit of Ruby, 
+  #    I would like to see that effort go to Ruby and its standard library 
+  #  - I needed better integration with some Ruby built in classes.
+  #  - Some people consider using EventMachine with Ruby as cheating!
+  #
+  # Example TCP server (an echo server)
+  #
+  # require 'reactor'
+  # require 'socket'
+  #
+  # reactor = Reactor::Base.new
+  # server = TCPServer.new("0.0.0.0",8080)
+  #
+  # reactor.attach(:read, server) do |server|
+  #   connection = server.accept
+  #   connection.write(connection.read)
+  #   connection.close
+  # end   
+  #
+  # reactor.run # blocking call, will run for ever (no signal handling currently)  
+  # 
+  # You can see a working example by running "ruby reactor.rb"
+  class Base
+    # Initializes a new reactor object
+    def initialize
+      @selectables = {:read => {:dirty=> false, :ios => {}, :callbacks => {}, :io_list => []}, 
+                       :write=> {:dirty=> false, :ios => {}, :callbacks => {}, :io_list => []}}
+      @next_procs, @timers, @running = [], [], false
+    end
+    
+    # Starts the reactor loop
+    #
+    # If a block is given it is run and the reactor itself is sent as a parameter
+    # The block will be run while the reactor is in the running state but before
+    # the actual loop.
+    # 
+    # Each run of the loop will fire all expired time objects and will wait a few
+    # melliseconds for notifications on the list of IO objects, if any occurs
+    # the corresponding callbacks are fired and the loop resumes, otherwise it resumes
+    # directly
+    def run
+      @running = true
+      yield self if block_given?
+      loop do
+        break unless @running
+        run_once
+      end
+    end
+    
+    # A single select run, it will fire all expired timers and the callbacks on IO objects
+    # but it will return immediately after that. This is useful if you need to create your
+    # own loop to interleave the IO event notifications with other operations
+    def run_once
+      update_list(@selectables[:read])
+      update_list(@selectables[:write])            
+      if res = IO.select(@selectables[:read][:io_list], @selectables[:write][:io_list], nil, 0.005)
+        fire_ios(:read, res[0])
+        fire_ios(:write, res[1])
+      end 
+      fire_procs
+      fire_timers
+    end
+    
+    # Stops the reactor loop
+    # It does not detach any of the attached IO objects, the reactor can be started again
+    # and it will keep notifying on the same set of attached IO objects
+    # 
+    # Stop does not stop the reactor immediately, rather it is stopped at the next cycle,
+    # the current cycle continues to completion
+    def stop
+      @running = false
+    end
+    
+    # Attach an IO object to the reactor.
+    #
+    # mode can be either :read or :write
+    #
+    # A block must be provided and it will be used as the callback to handle the event,
+    # once the event fires the block will be called with the IO object and the reactor
+    # passed as block parameters.
+    #
+    # A third argument (which defaults to true) tells the method what to do if the IO
+    # object is already attached. If it is set to true (default) then the reactor will
+    # append the new call back till the original caller detaches it. If set to false
+    # then the reactor will just override the old callback with the new one
+
+    def attach(mode, io, wait_if_attached = true, &callback)
+      selectables = @selectables[mode] || raise("mode is not :read or :write")
+      raise "you must supply a callback block" if callback.nil?
+      if wait_if_attached && selectables[:ios][io.object_id]
+        selectables[:callbacks][io.object_id] << callback
+      else
+        selectables[:ios][io.object_id] = io 
+        selectables[:callbacks][io.object_id] = [callback]
+        selectables[:dirty] = true
+      end
+    end
+    
+    # Detach an IO object from the reactor
+    #
+    # mode can be either :read or :write
+    def detach(mode, io, force=false)
+      selectables = @selectables[mode] || raise("mode is not :read or :write")
+      if !force && selectables[:callbacks][io.object_id].length > 0
+        selectables[:callbacks][io.object_id].shift
+      else
+        selectables[:ios].delete(io.object_id)
+        selectables[:callbacks].delete(io.object_id)
+        selectables[:dirty] = true
+      end
+    end
+      
+    # Detach all IO objects of a certain mode from the reactor
+    #
+    # mode can be either :read or :write
+    def detach_all(mode)
+      raise("mode is not :read or :write") unless [:read, :write].include? mode
+      @selectables[mode] = {:ios => {}, :callbacks => {}, :io_list => []}
+    end
+    
+    # Ask the reactor if an IO object is attached in some mode
+    #
+    # mode can be either :read or :write
+    def attached?(mode, io)
+      @selectables[mode][:ios].include? io
+    end
+
+    # Add a block of code that will fire after some time
+    def add_timer(time, periodical=false, &block)
+      timer = Timer.new(@timers, time, periodical, &block)
+    end
+
+    # Add a block of code that will fire periodically after some time passes
+    def add_periodical_timer(time, &block)
+      add_timer(time, true, &block)
+    end
+    
+    # Register a block to be called at the next reactor tick
+    def next_tick &block
+      @next_procs << block
+    end
+    
+    # Is the reactor running?
+    def running?
+      @running
+    end
+    
+    protected
+    
+    def update_list(selectables)
+      selectables[:io_list], selectables[:dirty] = selectables[:ios].values, false if selectables[:dirty]
+    end
+    
+    def fire_procs
+      length = @next_procs.length
+      length.times { @next_procs.shift.call }
+    end
+    
+    def fire_timers
+      return if @timers.length == 0
+      t = (Time.now.to_f * 1000).to_i
+      while @timers.length > 0 && @timers.first.time_of_fire <= t
+        @timers.shift.fire
+      end
+    end
+    
+    def fire_ios(mode, ios)
+      ios.each {|io|@selectables[mode][:callbacks][io.object_id][0].call(io, self)}
+    end
+  end
+end 
+
+if __FILE__ == $0
+  trap('INT') do 
+    puts "why did you have to press CTRL+C? why? why?"
+    puts "off to the darkness.. again!"
+    exit    
+  end
+  require 'socket'
+  port = (ARGV[0] || 3333).to_i
+  puts ">> Reactor library version 1.0 ()"
+  puts ">> This is an interactive test"
+  puts ">> The console will echo everything you type"
+  puts ">> At the same time it will *secretly* listen"
+  puts ">> to connections on port #{port} and send"
+  puts ">> all that you wrote to whoever asks for it"
+  puts ">> Have fun.."  
+  buffer = ""
+  reactor = Reactor::Base.new
+  server = TCPServer.new("0.0.0.0", port)
+  reactor.attach(:read, server) do |server|
+    conn = server.accept
+    conn.write("HTTP/1.1 200 OK\r\nContent-Length:#{buffer.length}\r\nContent-Type:text/plain\r\n\r\n#{buffer}")
+    conn.close
+  end
+  reactor.attach(:read, STDIN) do
+    data = gets
+    puts data
+    buffer << data
+  end
+  reactor.run
+end

data/lib/timer.rb

@@ -0,0 +1,40 @@
+module Reactor
+  # Timer objects created by Reactor::Base#add_to_timer are instances
+  # of this class. You can call cancel on them to stop them from executing
+  class Timer
+    include Comparable
+  
+    attr_reader :time_of_fire, :periodical
+    
+    def initialize(timers, time, periodical, &block)
+      @timers = timers
+      @time = time * 1000
+      @periodical = periodical
+      @block = block
+      @active = true
+      add_to_timers
+    end
+    
+    def fire
+      return unless @active
+      @block.call
+      add_to_timers if @periodical
+    end
+    
+    # Cancels the timer
+    # It will be lazily removed from the timer's list later
+    def cancel
+      @active = false
+    end
+
+    def add_to_timers
+      @time_of_fire = (Time.now.to_f * 1000).to_i + @time
+      @timers.insert_sorted(self)      
+    end
+
+    def <=>(other)
+      self.time_of_fire <=> other.time_of_fire
+    end
+    
+  end
+end

data/lib/util.rb

@@ -0,0 +1,36 @@
+class Array
+  def insert_sorted(value)
+    #move across all values
+    if self.length == 0
+      self << value
+    elsif self.first >= value
+      self.unshift value
+    elsif self.last <= value
+      self << value
+    else
+      #find the first value that is bigger than value
+      start, finish = 0, self.length - 1
+      loop do
+        median = ((start + finish)/2).to_i
+        if self[median] > value
+          if self[median-1] < value
+            self.insert(median, value)
+            break
+          end
+          finish = median - 1
+        elsif self[median] < value
+          if self[median+1] > value
+            self.insert(median + 1, value)
+            break
+          end
+          start = median + 1
+        else
+          self.insert(median, value)
+          break
+        end
+      end
+    end
+  end
+end
+
+

data/reactor.gemspec

@@ -0,0 +1,22 @@
+Gem::Specification.new do |s|
+  s.name     = "reactor"
+  s.version  = "0.2.0"
+  s.date     = "2009-07-04"
+  s.summary  = "A pure Ruby reactor library"
+  s.email    = "oldmoe@gmail.com"
+  s.homepage = "http://github.com/oldmoe/reactor"
+  s.description = "A simple, fast reactor library in pure Ruby"
+  s.has_rdoc = true
+  s.authors  = ["Muhammad A. Ali"]
+  s.platform = Gem::Platform::RUBY
+  s.files    = [ 
+		"reactor.gemspec", 
+		"README",
+		"lib/reactor.rb",
+		"lib/util.rb",
+		"lib/timer.rb"
+	]
+  s.rdoc_options = ["--main", "README"]
+  s.extra_rdoc_files = ["README"]
+end
+

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification 
+name: oldmoe-reactor
+version: !ruby/object:Gem::Version 
+  version: 0.2.0
+platform: ruby
+authors: 
+- Muhammad A. Ali
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-07-04 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: A simple, fast reactor library in pure Ruby
+email: oldmoe@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- reactor.gemspec
+- README
+- lib/reactor.rb
+- lib/util.rb
+- lib/timer.rb
+has_rdoc: true
+homepage: http://github.com/oldmoe/reactor
+post_install_message: 
+rdoc_options: 
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A pure Ruby reactor library
+test_files: []
+