revactor 0.1.0

data/lib/revactor/server.rb

@@ -0,0 +1,153 @@
+#--
+# 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'
+
+module Revactor
+  # Revactor::Server wraps an Actor's receive loop and issues callbacks to
+  # a class which implements Revactor::Behaviors::Server.  It eases the
+  # creation of standard synchronous "blocking" calls by abstracting away 
+  # inter-Actor communication and also providing baked-in state management.
+  #
+  # When used properly, Revactor::Server 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
+  class Server
+    # How long to wait for a response to a call before timing out
+    # This value also borrowed from Erlang.  More cargo culting!
+    DEFAULT_CALL_TIMEOUT = 5
+    
+    # Create a new server.  Accepts the following options:
+    #
+    #   register: Register the Actor in the Actor registry under
+    #             the given term
+    #
+    # Any options passed after the options hash are passed to the
+    # start method of the given object.
+    #
+    def initialize(obj, options = {}, *args)
+      @obj = obj
+      @timeout = nil
+      @state = obj.start(*args)
+      @actor = Actor.new(&method(:start).to_proc)
+      
+      Actor[options[:register]] = @actor if options[:register]
+    end
+    
+    # Call the server with the given message
+    def call(message, options = {})
+      options[:timeout] ||= DEFAULT_CALL_TIMEOUT
+      
+      @actor << T[:call, Actor.current, message]
+      Actor.receive do |filter|
+        filter.when(Case[:call_reply, @actor, Object]) { |_, _, reply| reply }
+        filter.when(Case[:call_error, @actor, Object]) { |_, _, ex| raise ex }
+        filter.after(options[:timeout]) { raise 'timeout' }
+      end
+    end
+    
+    # Send a cast to the server
+    def cast(message)
+      @actor << T[:cast, message]
+      message
+    end
+    
+    #########
+    protected
+    #########
+    
+    # Start the server
+    def start
+      @running = true
+      while @running do
+        Actor.receive do |filter|
+          filter.when(Object) { |message| handle_message(message) }
+          filter.after(@timeout) { stop(:timeout) } if @timeout
+        end
+      end
+    end
+    
+    # Dispatch the incoming message to the appropriate handler
+    def handle_message(message)
+      case message.first
+      when :call then handle_call(message)
+      when :cast then handle_cast(message)
+      else handle_info(message)
+      end
+    end
+    
+    # Wrapper for calling the provided object's handle_call method
+    def handle_call(message)
+      _, from, body = message
+      
+      begin
+        result = @obj.handle_call(body, from, @state)
+        case result.first
+        when :reply
+          _, reply, @state, @timeout = result
+          from << T[:call_reply, Actor.current, reply]
+        when :noreply
+          _, @state, @timeout = result
+        when :stop
+          _, reason, @state = result
+          stop(reason)
+        end
+      rescue Exception => ex
+        log_exception(ex)
+        from << T[:call_error, Actor.current, ex]
+      end
+    end
+    
+    # Wrapper for calling the provided object's handle_cast method
+    def handle_cast(message)
+      _, body = message
+    
+      begin
+        result = @obj.handle_cast(body, @state)
+        case result.first
+        when :noreply
+          _, @state, @timeout = result
+        when :stop
+          _, reason, @state = result
+          stop(reason)
+        end
+      rescue Exception => e
+        log_exception(e)
+      end
+    end
+    
+    # Wrapper for calling the provided object's handle_info method
+    def handle_info(message)
+      begin
+        result = @obj.handle_info(message, @state)
+        case result.first
+        when :noreply
+          _, @state, @timeout = result
+        when :stop
+          _, reason, @state = result
+          stop(reason)
+        end
+      rescue Exception => e
+        log_exception(e)
+      end
+    end
+    
+    # Stop the server
+    def stop(reason)
+      @running = false
+      @obj.terminate(reason, @state)
+    end
+    
+    # Log an exception
+    def log_exception(exception)
+      # FIXME this should really go to a logger, not STDERR
+      STDERR.puts "Rev::Server exception: #{exception}"
+      STDERR.puts exception.backtrace
+    end
+  end
+end

data/lib/revactor/tcp.rb

@@ -0,0 +1,397 @@
+#--
+# 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'
+
+module Revactor
+  # The TCP module holds all Revactor functionality related to the
+  # Transmission Control Protocol, including drop-in replacements
+  # for Ruby TCP Sockets which can operate concurrently using Actors.
+  module TCP
+    # Number of seconds to wait for a connection
+    CONNECT_TIMEOUT = 10
+
+    # Raised when a connection to a remote server fails
+    class ConnectError < StandardError; end
+    
+    # Raised when hostname resolution for a remote server fails
+    class ResolveError < ConnectError; end
+    
+    # Connect to the specified host and port.  Host may be a domain name
+    # or IP address.  Accepts the following options:
+    #
+    #   :active - Controls how data is read from the socket.  See the
+    #             documentation for Revactor::TCP::Socket#active=
+    #
+    def self.connect(host, port, options = {})
+      socket = Socket.connect host, port, options
+      socket.attach Rev::Loop.default
+
+      Actor.receive do |filter|
+        filter.when(Case[Object, socket]) do |message|
+          case message[0]
+          when :tcp_connected
+            return socket
+          when :tcp_connect_failed
+            raise ConnectError, "connection refused"
+          when :tcp_resolve_failed
+            raise ResolveError, "couldn't resolve #{host}"
+          else raise "unexpected message for #{socket.inspect}: #{message.first}"
+          end              
+        end
+
+        filter.after(CONNECT_TIMEOUT) do
+          raise ConnectError, "connection timed out"
+        end
+      end
+    end
+
+    # Listen on the specified address and port.  Accepts the following options:
+    #
+    #   :active - Default active setting for new connections.  See the
+    #             documentation Rev::TCP::Socket#active= for more info
+    #
+    #   :controller - The controlling actor, default Actor.current
+    #
+    def self.listen(addr, port, options = {})
+      Listener.new(addr, port, options).attach(Rev::Loop.default).disable
+    end
+
+    # TCP socket class, returned by Revactor::TCP.connect and 
+    # Revactor::TCP::Listener#accept
+    class Socket < Rev::TCPSocket
+      attr_reader :active
+      attr_reader :controller
+
+      class << self
+        # Connect to the specified host and port.  Host may be a domain name
+        # or IP address.  Accepts the following options:
+        #
+        #   :active - Controls how data is read from the socket.  See the
+        #             documentation for #active=
+        #
+        #   :controller - The controlling actor, default Actor.current
+        #
+        #   :filter - An symbol/class or array of symbols/classes which implement 
+        #             #encode and #decode methods to transform data sent and 
+        #             received data respectively via Revactor::TCP::Socket.
+        #
+        def connect(host, port, options = {})
+          options[:active]     ||= false
+          options[:controller] ||= Actor.current
+        
+          super(host, port, options).instance_eval {
+            @active, @controller = options[:active], options[:controller]
+            @filterset = initialize_filter(*options[:filter])
+            self
+          }
+        end
+      end
+      
+      def initialize(socket, options = {})        
+        super(socket)
+        
+        @active ||= options[:active] || false
+        @controller ||= options[:controller] || Actor.current
+        @filterset ||= initialize_filter(*options[:filter])
+        
+        @receiver = @controller
+        @read_buffer = Rev::Buffer.new
+      end
+      
+      # Enable or disable active mode data reception.  State can be any
+      # of the following:
+      #
+      #   true - All received data is sent to the controlling actor
+      #   false - Receiving data is disabled
+      #   :once - A single message will be sent to the controlling actor
+      #           then active mode will be disabled
+      def active=(state)
+        unless @receiver == @controller
+          raise "cannot change active state during a synchronous call" 
+        end
+        
+        unless [true, false, :once].include? state
+          raise ArgumentError, "must be true, false, or :once" 
+        end
+        
+        if [true, :once].include?(state)
+          unless @read_buffer.empty?
+            @receiver << [:tcp, self, @read_buffer.read]
+            return if state == :once
+          end
+          
+          enable unless enabled?
+        end
+        
+        @active = state
+      end
+      
+      # Set the controlling actor
+      def controller=(controller)
+        raise ArgumentError, "controller must be an actor" unless controller.is_a? Actor
+        
+        @receiver = controller if @receiver == @controller
+        @controller = controller
+      end
+      
+      # Read data from the socket synchronously.  If a length is specified
+      # then the call blocks until the given length has been read.  Otherwise
+      # the call blocks until it receives any data.
+      def read(length = nil)
+        # Only one synchronous call allowed at a time
+        raise "already being called synchronously" unless @receiver == @controller
+        
+        unless @read_buffer.empty? or (length and @read_buffer.size < length)
+          return @read_buffer.read(length) 
+        end
+        
+        active = @active
+        @active = :once
+        @receiver = Actor.current
+        enable unless enabled?
+        
+        loop do
+          Actor.receive do |filter|
+            filter.when(Case[:tcp, self, Object]) do |_, _, data|
+              if length.nil?
+                @receiver = @controller
+                @active = active
+                enable if @active
+                
+                return data
+              end
+              
+              @read_buffer << data
+              
+              if @read_buffer.size >= length
+                @receiver = @controller
+                @active = active
+                enable if @active
+                
+                return @read_buffer.read(length)
+              end
+            end
+            
+            filter.when(Case[:tcp_closed, self]) do
+              unless @receiver == @controller
+                @receiver = @controller
+                @receiver << T[:tcp_closed, self]
+              end
+              
+              raise EOFError, "connection closed"
+            end
+          end
+        end
+      end
+      
+      # Write data to the socket.  The call blocks until all data has been written.
+      def write(data)
+        # Only one synchronous call allowed at a time
+        raise "already being called synchronously" unless @receiver == @controller
+        
+        active = @active
+        @active = false
+        @receiver = Actor.current
+        disable if @active
+        
+        super(encode(data))
+        
+        Actor.receive do |filter|
+          filter.when(Case[:tcp_write_complete, self]) do
+            @receiver = @controller
+            @active = active
+            enable if @active
+            
+            return data.size
+          end
+          
+          filter.when(Case[:tcp_closed, self]) do
+            @receiver = @controller
+            @active = active
+            enable if @active
+            
+            raise EOFError, "connection closed"
+          end
+        end
+      end
+      
+      alias_method :<<, :write
+      
+      #########
+      protected
+      #########
+      
+      #
+      # Filter setup
+      #
+      
+      # Initialize filter change
+      def initialize_filter(*filterset)
+        return filterset if filterset.empty?
+        
+        filterset.map do |filter|
+          case filter
+          when Array
+            name = filter.shift
+            case name
+            when Class
+              name.new(*filter)
+            when Symbol
+              symbol_to_filter(name).new(*filter)
+            else raise ArgumentError, "unrecognized filter type: #{name.class}"
+            end
+          when Class
+            filter.new
+          when Symbol
+            symbol_to_filter(filter).new
+          end
+        end
+      end
+      
+      # Lookup filters referenced as symbols
+      def symbol_to_filter(filter)
+        case filter
+        when :line then Revactor::Filters::Line
+        when :packet then Revactor::Filters::Packet
+        else raise ArgumentError, "unrecognized filter type: #{filter}"
+        end
+      end
+      
+      # Decode data through the filter chain
+      def decode(data)
+        @filterset.reduce([data]) do |a, filter|
+          a.reduce([]) do |a2, d|
+            a2 + filter.decode(d)
+          end
+        end
+      end
+      
+      # Encode data through the filter chain
+      def encode(message)
+        @filterset.reverse.reduce(message) { |m, filter| filter.encode(*m) }
+      end
+      
+      #
+      # Rev::TCPSocket callback
+      #
+      
+      def on_connect
+        @receiver << T[:tcp_connected, self]
+      end
+
+      def on_connect_failed
+        @receiver << T[:tcp_connect_failed, self]
+      end
+
+      def on_resolve_failed
+        @receiver << T[:tcp_resolve_failed, self]
+      end
+
+      def on_close
+        @receiver << T[:tcp_closed, self]
+      end
+
+      def on_read(data)
+        # Run incoming message through the filter chain
+        message = decode(data)
+        
+        if message.is_a?(Array) and not message.empty?
+          message.each { |msg| @receiver << T[:tcp, self, msg] }
+        elsif message
+          @receiver << T[:tcp, self, message]
+        else return
+        end
+          
+        if @active == :once
+          @active = false
+          disable
+        end
+      end
+
+      def on_write_complete
+        @receiver << T[:tcp_write_complete, self]
+      end
+    end
+
+    # TCP Listener returned from Revactor::TCP.listen
+    class Listener < Rev::TCPListener
+      attr_reader :active
+      attr_reader :controller
+   
+      # Listen on the specified address and port.  Accepts the following options:
+      #
+      #   :active - Default active setting for new connections.  See the 
+      #             documentation Rev::TCP::Socket#active= for more info
+      #
+      #   :controller - The controlling actor, default Actor.current
+      #   
+      def initialize(host, port, options = {})
+        super(host, port)
+        opts = {
+          active:     false,
+          controller: Actor.current
+        }.merge(options)
+        
+        @active, @controller = opts[:active], opts[:controller]
+        @filterset = options[:filter]
+        
+        @accepting = false
+      end
+      
+      # Change the default active setting for newly accepted connections
+      def active=(state)
+        unless [true, false, :once].include? state
+          raise ArgumentError, "must be true, false, or :once" 
+        end
+      
+        @active = state
+      end
+      
+      # Change the default controller for newly accepted connections
+      def controller=(controller)
+        raise ArgumentError, "controller must be an actor" unless controller.is_a? Actor
+        @controller = controller
+      end
+      
+      # Accept an incoming connection
+      def accept
+        raise "another actor is already accepting" if @accepting
+        
+        @accepting = true
+        @receiver = Actor.current
+        enable
+        
+        Actor.receive do |filter|
+          filter.when(Case[:tcp_connection, self, Object]) do |_, _, sock|
+            @accepting = false            
+            return sock
+          end
+        end
+      end
+      
+      #########
+      protected
+      #########
+      
+      #
+      # Rev::TCPListener callbacks
+      #
+      
+      def on_connection(socket)
+        sock = Socket.new(socket, 
+          :controller => @controller, 
+          :active => @active,
+          :filter => @filterset
+        )
+        sock.attach(evloop)
+        
+        @receiver << T[:tcp_connection, self, sock]
+        disable
+      end
+    end
+  end
+end

data/lib/revactor.rb

@@ -0,0 +1,29 @@
+#--
+# Copyright (C)2007 Tony Arcieri
+# You can redistribute this under the terms of the Ruby license
+# See file LICENSE for details
+#++
+
+require 'rubygems'
+require 'rev'
+require 'case'
+
+# This is mostly in hopes of a bright future with Rubinius
+# The recommended container for all datagrams sent between
+# Actors is a Tuple, defined below, and with a 'T' shortcut:
+unless defined? Tuple
+  # A Tuple class.  Will (eventually) be a subset of Array
+  # with fixed size and faster performance, at least that's
+  # the hope with Rubinius...
+  class Tuple < Array; end
+end
+
+# Shortcut Tuple as T
+T = Tuple unless defined? T
+
+require File.dirname(__FILE__) + '/revactor/actor'
+require File.dirname(__FILE__) + '/revactor/server'
+require File.dirname(__FILE__) + '/revactor/tcp'
+require File.dirname(__FILE__) + '/revactor/behaviors/server'
+require File.dirname(__FILE__) + '/revactor/filters/line'
+require File.dirname(__FILE__) + '/revactor/filters/packet'

data/revactor.gemspec

@@ -0,0 +1,28 @@
+require 'rubygems'
+
+GEMSPEC = Gem::Specification.new do |s|
+  s.name = "revactor"
+  s.version = "0.1.0"
+  s.authors = "Tony Arcieri"
+  s.email = "tony@medioh.com"
+  s.date = "2008-1-15"
+  s.summary = "Revactor is an Actor implementation for writing high performance concurrent programs"
+  s.platform = Gem::Platform::RUBY
+  s.required_ruby_version = '>= 1.9.0'
+
+  # Gem contents
+  s.files = Dir.glob("{lib,examples,tools,spec}/**/*") + ['Rakefile', 'revactor.gemspec']
+
+  # Dependencies
+  s.add_dependency("rev", ">= 0.1.3")
+  s.add_dependency("case", ">= 0.3")
+
+  # RubyForge info
+  s.homepage = "http://revactor.org"
+  s.rubyforge_project = "revactor"
+
+  # RDoc settings
+  s.has_rdoc = true
+  s.rdoc_options = %w(--title Revactor --main README --line-numbers)
+  s.extra_rdoc_files = ["LICENSE", "README", "CHANGES"]
+end