revactor 0.1.0

data/lib/revactor/actor.rb

@@ -0,0 +1,316 @@
+#--
+# Copyright (C)2007 Tony Arcieri
+# You can redistribute this under the terms of the Ruby license
+# See file LICENSE for details
+#++
+
+require File.dirname(__FILE__) + '/../revactor'
+require 'fiber'
+
+# Raised whenever any Actor-specific problems occur
+class ActorError < StandardError; end
+
+# Actors are lightweight concurrency primitives which communiucate via message
+# passing.  Each actor has a mailbox which it scans for matching messages.
+# An actor sleeps until it receives a message, at which time it scans messages
+# against its filter set and then executes appropriate callbacks.
+#
+# The Actor class is definined in the global scope in hopes of being generally
+# useful for Ruby 1.9 users while also attempting to be as compatible as
+# possible with the Omnibus and Rubinius Actor implementations.  In this way it 
+# should be possible to run programs written using Revactor to on top of other
+# Actor implementations.
+#
+class Actor < Fiber
+  include Enumerable
+  @@registered = {}
+
+  class << self
+    include Enumerable
+
+    # Create a new Actor with the given block and arguments
+    def new(*args, &block)
+      raise ArgumentError, "no block given" unless block
+      actor = super() do 
+        block.call(*args)
+        Actor.current.instance_eval { @_dead = true }
+      end
+
+      # For whatever reason #initialize is never called in subclasses of Fiber
+      actor.instance_eval do 
+        @_dead = false
+        @_mailbox = Mailbox.new
+        @_dictionary = {}
+      end
+
+      Scheduler << actor
+      actor
+    end
+    
+    alias_method :spawn, :new
+    
+    # This will be defined differently in the future, but now the two are the same
+    alias_method :start, :new
+    
+    # Obtain a handle to the current Actor
+    def current
+      actor = super
+      raise ActorError, "current fiber is not an actor" unless actor.is_a? Actor
+      
+      actor 
+    end
+    
+    # Wait for messages matching a given filter.  The filter object is yielded
+    # to be block passed to receive.  You can then invoke the when argument
+    # which takes a parameter and a block.  Messages are compared (using ===)
+    # against the parameter.  The Case gem includes several tools for matching
+    # messages using ===
+    #
+    # The first filter to match a message in the mailbox is executed.  If no
+    # filters match then the actor sleeps.
+    def receive(&filter)
+      unless current.is_a?(Actor)
+        raise ActorError, "receive must be called in the context of an Actor"
+      end
+
+      current.__send__(:_mailbox).receive(&filter)
+    end
+
+    # Look up an actor in the global dictionary
+    def [](key)
+      @@registered[key]
+    end
+
+    # Register this actor in the global dictionary
+    def []=(key, actor)
+      unless actor.is_a?(Actor)
+        raise ArgumentError, "only actors may be registered"
+      end
+
+      @@registered[key] = actor
+    end
+
+    # Delete an actor from the global dictionary
+    def delete(key, &block)
+      @@registered.delete(key, &block)
+    end
+
+    # Iterate over the actors in the global dictionary
+    def each(&block)
+      @@registered.each(&block)
+    end
+  end
+  
+  # Look up value in the actor's dictionary
+  def [](key)
+    @_dictionary[key]
+  end
+  
+  # Store a value in the actor's dictionary
+  def []=(key, value)
+    @_dictionary[key] = value
+  end
+  
+  # Delete a value from the actor's dictionary
+  def delete(key, &block)
+    @_dictionary.delete(key, &block)
+  end
+  
+  # Iterate over values in the actor's dictionary
+  def each(&block)
+    @_dictionary.each(&block)
+  end
+  
+  # Is the current actor dead?
+  def dead?; @_dead; end
+  
+  # Send a message to an actor
+  def <<(message)
+    # Erlang discards messages sent to dead actors, and if Erlang does it,
+    # it must be the right thing to do, right?  Hooray for the Erlang 
+    # cargo cult!  I think they do this because dealing with errors raised
+    # from dead actors complicates overall error handling too much to be worth it.
+    return message if dead?
+    
+    @_mailbox << message
+    Scheduler << self
+    message
+  end
+
+  alias_method :send, :<<
+  
+  #########
+  protected
+  #########
+  
+  attr_reader :_mailbox
+  
+  # The Actor Scheduler maintains a run queue of actors with outstanding
+  # messages who have not yet processed their mailbox.  If all actors have
+  # processed their mailboxes then the scheduler waits for any outstanding
+  # Rev events.  If there are no active Rev watchers then the scheduler exits.
+  class Scheduler
+    @@queue = []
+    @@running = false
+
+    class << self
+      # Schedule an Actor to be executed, and run the scheduler if it isn't
+      # currently running
+      def <<(actor)
+        @@queue << actor
+        run unless @@running
+      end
+      
+      # Run the scheduler
+      def run
+        return if @@running
+        @@running = true
+        default_loop = Rev::Loop.default
+        
+        until @@queue.empty? and default_loop.watchers.empty?
+          @@queue.each do |actor|
+            begin
+              actor.resume
+            rescue FiberError # Fiber may have died since being scheduled 
+            end
+          end
+          
+          @@queue.clear
+          
+          default_loop.run_once unless default_loop.watchers.empty?
+        end
+        
+        @@running = false
+      end
+    end
+  end
+
+  # Actor mailbox.  For purposes of efficiency the mailbox also handles 
+  # suspending and resuming an actor when no messages match its filter set.
+  class Mailbox
+    attr_accessor :timer
+    attr_accessor :timed_out
+    attr_accessor :timeout_action
+
+    def initialize
+      @timer = nil
+      @queue = []
+    end
+
+    # Add a message to the mailbox queue
+    def <<(message)
+      @queue << message
+    end
+
+    # Attempt to receive a message
+    def receive
+      raise ArgumentError, "no filter block given" unless block_given?
+
+      # Clear mailbox processing variables
+      action = matched_index = nil
+      processed_upto = 0
+      
+      # Clear timeout variables
+      @timed_out = false
+      @timeout_action = nil
+      
+      # Build the filter
+      filter = Filter.new(self)
+      yield filter
+      raise ArgumentError, "empty filter" if filter.empty?
+
+      # Process incoming messages
+      while action.nil?
+        @queue[processed_upto..@queue.size].each_with_index do |message, index|
+          unless (action = filter.match message)
+            # The filter did not match an action for the current message
+            # Keep track of which messages we've ran the filter across so it doesn't
+            # get run against messages it already failed to match
+            processed_upto += 1
+            next
+          end
+          
+          # We've found a matching action, so break out of the loop
+          matched_index = processed_upto + index
+          break
+        end
+
+        # If we've timed out, run the timeout action unless another has been found
+        action ||= @timeout_action if @timed_out
+
+        # If we didn't find a matching action, yield until we get another message
+        Actor.yield unless action
+      end
+
+      if @timer
+        @timer.detach if @timer.attached?
+        @timer = nil
+      end
+      
+      # If we encountered a timeout, call the action directly
+      return action.call if @timed_out
+      
+      # Otherwise we matched a message, so process it with the action      
+      return action.(@queue.delete_at matched_index)
+    end
+
+    # Timeout class, used to implement receive timeouts
+    class Timer < Rev::TimerWatcher
+      def initialize(timeout, actor)
+        @actor = actor
+        super(timeout)
+      end
+
+      def on_timer
+        @actor.instance_eval { @_mailbox.timed_out = true }
+        Scheduler << @actor
+      end
+    end
+ 
+    # Mailbox filterset.  Takes patterns or procs to match messages with
+    # and returns the associated proc when a pattern matches.
+    class Filter
+      def initialize(mailbox)
+        @mailbox = mailbox
+        @ruleset = []
+      end
+
+      # Provide a pattern to match against with === and a block to call
+      # when the pattern is matched.
+      def when(pattern, &action)
+        raise ArgumentError, "no block given" unless action
+        @ruleset << [pattern, action]
+      end
+
+      # Provide a timeout (in seconds, can be a Float) to wait for matching
+      # messages.  If the timeout elapses, the given block is called.
+      def after(timeout, &action)
+        raise ArgumentError, "timeout already specified" if @mailbox.timer
+        raise ArgumentError, "must be zero or positive" if timeout < 0
+        
+        # Don't explicitly require an action to be specified for a timeout
+        @mailbox.timeout_action = action || proc {}
+        
+        if timeout > 0
+          @mailbox.timer = Timer.new(timeout, Actor.current).attach(Rev::Loop.default)
+        else
+          # No need to actually set a timer if the timeout is zero, 
+          # just short-circuit waiting for one entirely...
+          @timed_out = true
+          Scheduler << self
+        end
+      end
+
+      # Match a message using the filter
+      def match(message)
+        _, action = @ruleset.find { |pattern, _| pattern === message }
+        action
+      end
+
+      # Is the filterset empty?
+      def empty?
+        @ruleset.empty?
+      end
+    end
+  end
+end

data/lib/revactor/behaviors/server.rb

@@ -0,0 +1,87 @@
+#--
+# Copyright (C)2007 Tony Arcieri
+# You can redistribute this under the terms of the Ruby license
+# See file LICENSE for details
+#++
+
+module Revactor
+  module Behavior
+    # The Server behavior provides a callback-driven class which eases the
+    # creation of standard synchronous "blocking" calls by abstracting away 
+    # inter-Actor communication and also providing baked-in state management.
+    #
+    # This behavior module provides the base set of callbacks necessary
+    # to implement the behavior.  It also provides descriptions for what
+    # certain callback methods should do.
+    #
+    # When used properly, the server behavior can implement transactional
+    # semantics, ensuring only successful calls mutate the previous state
+    # and erroneous/exception-raising ones do not.
+    #
+    # The design is modeled off Erlang/OTP's gen_server
+    module Server
+      # Initialize the server state.  Can return:
+      #
+      #   start(*args) 
+      #     -> [:ok, state]
+      #     -> [:ok, state, timeout]
+      #     -> [:stop, reason]
+      #
+      # The state variable allows you to provide a set of state whose mutation
+      # can be controlled a lot more closely than is possible with standard
+      # object oriented behavior.  The latest version of state is passed
+      # to all Revactor::Server callbacks and is only mutated upon a
+      # successful return (unless an exception was raised)
+      #
+      def start(*args)
+        return :ok
+      end
+
+      # Handle any calls made to a Reactor::Server object, which are captured
+      # via method_missing and dispatched here.  Calls provide synchronous
+      # behavior: the callee will block until this method completss and a
+      # reply is sent back to them.  Can return:
+      #
+      #   handle_call(message, from, state)
+      #     -> [:reply, reply, new_state]
+      #     -> [:reply, reply, new_state, timeout]
+      #     -> [:noreply, new_state]
+      #     -> [:noreply, new_state, timeout]
+      #     -> [:stop, reason, reply, new_state]
+      #
+      def handle_call(message, from, state)
+        return :reply, :ok, state
+      end
+
+      # Handle calls without return values
+      #
+      #   handle_cast(message, state)
+      #     -> [:noreply, new_state]
+      #     -> [:noreply, new_state, timeout]
+      #     -> [:stop, reason, new_state]
+      #
+      def handle_cast(message, state)
+        return :noreply, state
+      end
+
+      # Handle any spontaneous messages to the server which are not calls
+      # or casts made from Rev::Server.  Can return:
+      #
+      #   handle_info(info, state)
+      #     -> [:noreply, new_state]
+      #     -> [:noreply, new_state, timeout]
+      #     -> [:stop, reason, new_state]
+      #
+      def handle_info(info, state)
+        return :noreply, state
+      end
+
+      # Method called when the server is about to terminate, for example when 
+      # any of the handle_* routines above return :stop.  The return value of
+      # terminate is discarded.
+      #
+      def terminate(reason, state)
+      end
+    end
+  end
+end

data/lib/revactor/filters/line.rb

@@ -0,0 +1,53 @@
+#--
+# Copyright (C)2007 Tony Arcieri
+# You can redistribute this under the terms of the Ruby license
+# See file LICENSE for details
+#++
+
+module Revactor
+  module Filter
+    # A filter for line based protocols which are framed using LF or CRLF 
+    # encoding, such as IRC.  Both LF and CRLF are supported and no 
+    # validation is done on bare LFs for CRLF encoding.  The output
+    # is chomped and delivered without any newline.
+    class Line
+      MAX_LENGTH = 1048576 # Maximum length of a single line
+      
+      # Create a new Line filter.  Accepts the following options:
+      #
+      #   delimiter: A character to use as a delimiter.  Defaults to "\n"
+      #              Character sequences are not supported.
+      #
+      #   maxlength: Maximum length of a line
+      #
+      def initialize(options = {})
+        @input = ''
+        @delimiter = options[:delimiter] || "\n"
+        @size_limit = options[:maxlength] || MAX_LENGTH
+      end
+      
+      # Callback for processing incoming lines
+      def decode(data)
+        lines = data.split @delimiter, -1
+        
+        if @size_limit and @input.size + lines.first.size > @size_limit
+          raise 'input buffer full' 
+        end
+        
+        @input << lines.shift
+        return [] if lines.empty?
+        
+        lines.unshift @input
+        @input = lines.pop
+        
+        lines.map(&:chomp)
+      end
+      
+      # Encode lines using the current delimiter
+      def encode(*data)
+        data.reduce("") { |str, d| str << d << @delimiter }
+      end
+    end
+  end
+end
+  

data/lib/revactor/filters/packet.rb

@@ -0,0 +1,59 @@
+#--
+# Copyright (C)2007 Tony Arcieri
+# You can redistribute this under the terms of the Ruby license
+# See file LICENSE for details
+#++
+
+# Use buffering from Rev
+require 'rubygems'
+require 'rev'
+
+module Revactor
+  module Filter
+    # A filter for "packet" protocols which are framed using a fix-sized
+    # length prefix followed by a message body, such as DRb.  Either 16-bit
+    # or 32-bit prefixes are supported.
+    class Packet
+      def initialize(size = 2)
+        unless size == 2 or size == 4
+          raise ArgumentError, 'only 2 or 4 byte prefixes are supported' 
+        end
+        
+        @prefix_size = size
+        @data_size = 0
+        
+        @mode = :prefix
+        @buffer = Rev::Buffer.new
+      end
+
+      # Callback for processing incoming frames
+      def decode(data)
+        received = []
+        @buffer << data
+      
+        begin  
+          if @mode == :prefix
+            break if @buffer.size < @prefix_size
+            prefix = @buffer.read @prefix_size
+            @data_size = prefix.unpack(@prefix_size == 2 ? 'n' : 'N').first
+            @mode = :data
+          end
+        
+          break if @buffer.size < @data_size
+          received << @buffer.read(@data_size)
+          @mode = :prefix
+        end until @buffer.empty?
+        
+        received
+      end
+
+      # Send a packet with a specified size prefix
+      def encode(*data)
+        data.reduce('') do |s, d|
+          raise ArgumentError, 'packet too long for prefix length' if d.size >= 256 ** @prefix_size
+          s << [d.size].pack(@prefix_size == 2 ? 'n' : 'N') << d
+        end
+      end
+    end
+  end
+end

data/lib/revactor/mongrel.rb

@@ -0,0 +1,62 @@
+require File.dirname(__FILE__) + '/../revactor'
+require 'rubygems'
+require 'mongrel'
+
+class Revactor::TCP::Socket
+  # Monkeypatched readpartial routine inserted whenever Revactor's mongrel.rb
+  # is loaded.  The value passed to this method is ignored, so it is not
+  # fully compatible with Socket's readpartial method.
+  #
+  # Mongrel doesn't really care if we read more than Const::CHUNK_SIZE
+  # and readpartial doesn't really make sense in Revactor's API since
+  # read accomplishes the same functionality.  So, in this implementation
+  # readpartial just calls read and returns whatever is available.
+  def readpartial(value = nil)
+    read
+  end
+end
+
+module Mongrel
+  # Mongrel's HttpServer, monkeypatched to run on top of Revactor and using
+  # Actors for concurrency.
+  class HttpServer
+    def initialize(host, port, num_processors=950, throttle=0, timeout=60)
+      @socket = Revactor::TCP.listen(host, port)
+      @classifier = URIClassifier.new
+      @host = host
+      @port = port
+      @throttle = throttle
+      @num_processors = num_processors
+      @timeout = timeout
+    end
+
+    # Runs the thing.  It returns the Actor the listener is running in.
+    def run
+      @acceptor = Actor.new do
+        begin
+          while true
+            begin
+              client = @socket.accept
+              actor = Actor.new client, &method(:process_client)
+              actor[:started_on] = Time.now
+            rescue StopServer
+              break
+            rescue Errno::ECONNABORTED
+              # client closed the socket even before accept
+              client.close rescue nil
+            rescue Object => e
+              STDERR.puts "#{Time.now}: Unhandled listen loop exception #{e.inspect}."
+              STDERR.puts e.backtrace.join("\n")
+            end
+          end
+          graceful_shutdown
+        ensure
+          @socket.close
+          # STDERR.puts "#{Time.now}: Closed socket."
+        end
+      end
+
+      return @acceptor
+    end
+  end
+end