ione 1.0.0.pre0

data/lib/ione/io.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+module Ione
+  CancelledError = Class.new(StandardError)
+  IoError = Class.new(StandardError)
+
+  module Io
+    ConnectionError = Class.new(IoError)
+    ConnectionClosedError = Class.new(ConnectionError)
+    ConnectionTimeoutError = Class.new(ConnectionError)
+  end
+end
+
+require 'ione/io/io_reactor'
+require 'ione/io/connection'

data/lib/ione/io/connection.rb

@@ -0,0 +1,215 @@
+# encoding: utf-8
+
+require 'socket'
+
+
+module Ione
+  module Io
+    # A wrapper around a socket. Handles connecting to the remote host, reading
+    # from and writing to the socket.
+    class Connection
+      attr_reader :host, :port, :connection_timeout
+
+      # @private
+      def initialize(host, port, connection_timeout, unblocker, clock, socket_impl=Socket)
+        @host = host
+        @port = port
+        @connection_timeout = connection_timeout
+        @unblocker = unblocker
+        @clock = clock
+        @socket_impl = socket_impl
+        @lock = Mutex.new
+        @connected = false
+        @write_buffer = ByteBuffer.new
+        @connected_promise = Promise.new
+      end
+
+      # @private
+      def connect
+        begin
+          unless @addrinfos
+            @connection_started_at = @clock.now
+            @addrinfos = @socket_impl.getaddrinfo(@host, @port, nil, Socket::SOCK_STREAM)
+          end
+          unless @io
+            _, port, _, ip, address_family, socket_type = @addrinfos.shift
+            @sockaddr = @socket_impl.sockaddr_in(port, ip)
+            @io = @socket_impl.new(address_family, socket_type, 0)
+          end
+          unless connected?
+            @io.connect_nonblock(@sockaddr)
+            @connected = true
+            @connected_promise.fulfill(self)
+          end
+        rescue Errno::EISCONN
+          @connected = true
+          @connected_promise.fulfill(self)
+        rescue Errno::EINPROGRESS, Errno::EALREADY
+          if @clock.now - @connection_started_at > @connection_timeout
+            close(ConnectionTimeoutError.new("Could not connect to #{@host}:#{@port} within #{@connection_timeout}s"))
+          end
+        rescue Errno::EINVAL, Errno::ECONNREFUSED => e
+          if @addrinfos.empty?
+            close(e)
+          else
+            @io = nil
+            retry
+          end
+        rescue SystemCallError => e
+          close(e)
+        rescue SocketError => e
+          close(e) || closed!(e)
+        end
+        @connected_promise.future
+      end
+
+      # Closes the connection
+      def close(cause=nil)
+        return false unless @io
+        begin
+          @io.close
+        rescue SystemCallError, IOError
+          # nothing to do, the socket was most likely already closed
+        end
+        closed!(cause)
+        true
+      end
+
+      # @private
+      def connecting?
+        !(closed? || connected?)
+      end
+
+      # Returns true if the connection is connected
+      def connected?
+        @connected
+      end
+
+      # Returns true if the connection is closed
+      def closed?
+        @io.nil?
+      end
+
+      # @private
+      def writable?
+        empty_buffer = @lock.synchronize do
+          @write_buffer.empty?
+        end
+        !(closed? || empty_buffer)
+      end
+
+      # Register to receive notifications when new data is read from the socket.
+      #
+      # You should only call this method in your protocol handler constructor.
+      #
+      # Only one callback can be registered, if you register multiple times only
+      # the last one will receive notifications. This is not meant as a general
+      # event system, it's just for protocol handlers to receive data from their
+      # connection. If you want multiple listeners you need to implement that
+      # yourself in your protocol handler.
+      #
+      # It is very important that you don't do any heavy lifting in the callback
+      # since it is called from the IO reactor thread, and as long as the
+      # callback is working the reactor can't handle any IO and no other
+      # callbacks can be called.
+      #
+      # Errors raised by the callback will be ignored.
+      #
+      # @yield [String] the new data
+      def on_data(&listener)
+        @data_listener = listener
+      end
+
+      # Register to receive a notification when the socket is closed, both for
+      # expected and unexpected reasons.
+      #
+      # You shoud only call this method in your protocol handler constructor.
+      #
+      # Only one callback can be registered, if you register multiple times only
+      # the last one will receive notifications. This is not meant as a general
+      # event system, it's just for protocol handlers to be notified of the
+      # connection closing. If you want multiple listeners you need to implement
+      # that yourself in your protocol handler.
+      #
+      # Errors raised by the callback will be ignored.
+      #
+      # @yield [error, nil] the error that caused the socket to close, or nil if
+      #   the socket closed with #close
+      def on_closed(&listener)
+        @closed_listener = listener
+      end
+
+      # Write bytes to the socket.
+      #
+      # You can either pass in bytes (as a string or as a `ByteBuffer`), or you
+      # can use the block form of this method to get access to the connection's
+      # internal buffer.
+      # 
+      # @yieldparam buffer [Ione::ByteBuffer] the connection's internal buffer
+      # @param bytes [String, Ione::ByteBuffer] the data to write to the socket
+      def write(bytes=nil)
+        @lock.synchronize do
+          if block_given?
+            yield @write_buffer
+          elsif bytes
+            @write_buffer.append(bytes)
+          end
+        end
+        @unblocker.unblock!
+      end
+
+      # @private
+      def flush
+        if writable?
+          @lock.synchronize do
+            bytes_written = @io.write_nonblock(@write_buffer.cheap_peek)
+            @write_buffer.discard(bytes_written)
+          end
+        end
+      rescue => e
+        close(e)
+      end
+
+      # @private
+      def read
+        new_data = @io.read_nonblock(2**16)
+        @data_listener.call(new_data) if @data_listener
+      rescue => e
+        close(e)
+      end
+
+      # @private
+      def to_io
+        @io
+      end
+
+      def to_s
+        state = 'inconsistent'
+        if connected?
+          state = 'connected'
+        elsif connecting?
+          state = 'connecting'
+        elsif closed?
+          state = 'closed'
+        end
+        %(#<#{self.class.name} #{state} #{@host}:#{@port}>)
+      end
+
+      private
+
+      def closed!(cause)
+        @io = nil
+        if cause && !cause.is_a?(IoError)
+          cause = ConnectionError.new(cause.message)
+        end
+        unless connected?
+          @connected_promise.fail(cause)
+        end
+        @connected = false
+        if @closed_listener
+          @closed_listener.call(cause)
+        end
+      end
+    end
+  end
+end

data/lib/ione/io/io_reactor.rb

@@ -0,0 +1,321 @@
+# encoding: utf-8
+
+module Ione
+  module Io
+    ReactorError = Class.new(IoError)
+
+    # An IO reactor takes care of all the IO for a client. It handles opening
+    # new connections, and making sure that connections that have data to send
+    # flush to the network, and connections that have data coming in read that
+    # data and delegate it to their protocol handlers.
+    #
+    # All IO is done in a single background thread, regardless of how many
+    # connections you open. There shouldn't be any problems handling hundreds of
+    # connections if needed. All operations are thread safe, but you should take
+    # great care when in your protocol handlers to make sure that they don't
+    # do too much work in their data handling callbacks, since those will be
+    # run in the reactor thread, and every cycle you use there is a cycle which
+    # can't be used to handle IO.
+    #
+    # The IO reactor is completely protocol agnostic, and it's up to you to
+    # create objects that can interpret the bytes received from remote hosts,
+    # and to send the correct commands back. The way this works is that when you
+    # open a connection you can provide a protocol handler factory as a block,
+    # (or you can simply wrap the returned connection). This factory can be used
+    # to create objects that wrap the raw connections and register to receive
+    # new data, and it can write data to connection. It can also register to be
+    # notified when the socket is closed, or it can itself close the socket.
+    #
+    # @example A protocol handler that processes whole lines
+    #   io_reactor.connect('example.com', 6543, 10) do |connection|
+    #     LineProtocolHandler.new(connection)
+    #   end
+    #
+    #   # ...
+    #
+    #   class LineProtocolHandler
+    #     def initialize(connection)
+    #       @connection = connection
+    #       # register a listener method for new data, this must be done in the
+    #       # in the constructor, and only one listener can be registered
+    #       @connection.on_data(&method(:process_data))
+    #       @buffer = ''
+    #     end
+    #
+    #     def process_data(new_data)
+    #       # in this fictional protocol we want to process whole lines, so we
+    #       # append new data to our buffer and then loop as long as there is
+    #       # a newline in the buffer, everything up until a newline is a
+    #       # complete line
+    #       @buffer << new_data
+    #       while newline_index = @buffer.index("\n")
+    #         line = @buffer.slice!(0, newline_index + 1)
+    #         line.chomp!
+    #         # Now do something interesting with the line, but remember that
+    #         # while you're in the data listener method you're executing in the
+    #         # IO reactor thread so you're blocking the reactor from doing
+    #         # other IO work. You should not do any heavy lifting here, but
+    #         # instead hand off the data to your application's other threads.
+    #         # One way of doing that is to create a Ione::Future in the method
+    #         # that sends the request, and then complete the future in this
+    #         # method. How you keep track of which future belongs to which
+    #         # reply is very protocol dependent so you'll have to figure that
+    #         # out yourself.
+    #       end
+    #     end
+    #
+    #     def send_request(command_string)
+    #       # This example primarily shows how to implement a data listener
+    #       # method, but this is how you write data to the connection. The
+    #       # method can be called anything, it doesn't have to be #send_request
+    #       @connection.write(command_string)
+    #       # The connection object itself is threadsafe, but to create any
+    #       # interesting protocol you probably need to set up some state for
+    #       # each request so that you know which request to complete when you
+    #       # get data back.
+    #     end
+    #   end
+    class IoReactor
+      # Initializes a new IO reactor.
+      #
+      # @param options [Hash] only used to inject behaviour during tests
+      def initialize(options={})
+        @clock = options[:clock] || Time
+        @unblocker = Unblocker.new
+        @io_loop = IoLoopBody.new(options)
+        @io_loop.add_socket(@unblocker)
+        @running = false
+        @stopped = false
+        @started_promise = Promise.new
+        @stopped_promise = Promise.new
+        @lock = Mutex.new
+      end
+
+      # Register to receive notifications when the reactor shuts down because
+      # on an irrecoverable error.
+      #
+      # The listener block will be called in the reactor thread. Any errors that
+      # it raises will be ignored.
+      #
+      # @yield [error] the error that cause the reactor to stop
+      def on_error(&listener)
+        @stopped_promise.future.on_failure(&listener)
+      end
+
+      # Returns true as long as the reactor is running. It will be true even
+      # after {#stop} has been called, but false when the future returned by
+      # {#stop} completes.
+      def running?
+        @running
+      end
+
+      # Starts the reactor. This will spawn a background thread that will manage
+      # all connections.
+      #
+      # This method is asynchronous and returns a future which completes when
+      # the reactor has started.
+      #
+      # @return [Ione::Future] a future that will resolve to the reactor itself
+      def start
+        @lock.synchronize do
+          raise ReactorError, 'Cannot start a stopped IO reactor' if @stopped
+          return @started_promise.future if @running
+          @running = true
+        end
+        Thread.start do
+          @started_promise.fulfill(self)
+          begin
+            @io_loop.tick until @stopped
+          ensure
+            @io_loop.close_sockets
+            @io_loop.cancel_timers
+            @running = false
+            if $!
+              @stopped_promise.fail($!)
+            else
+              @stopped_promise.fulfill(self)
+            end
+          end
+        end
+        @started_promise.future
+      end
+
+      # Stops the reactor.
+      #
+      # This method is asynchronous and returns a future which completes when
+      # the reactor has completely stopped, or fails with an error if the reactor
+      # stops or has already stopped because of a failure.
+      #
+      # @return [Ione::Future] a future that will resolve to the reactor itself
+      def stop
+        @stopped = true
+        @stopped_promise.future
+      end
+
+      # Opens a connection to the specified host and port.
+      #
+      # @param host [String] the host to connect to
+      # @param port [Integer] the port to connect to
+      # @param timeout [Numeric] the number of seconds to wait for a connection
+      #   before failing
+      # @return [Ione::Future] a future that will resolve to the connection when
+      #   when it has finished connecting.
+      def connect(host, port, timeout)
+        connection = Connection.new(host, port, timeout, @unblocker, @clock)
+        f = connection.connect
+        @io_loop.add_socket(connection)
+        @unblocker.unblock!
+        f
+      end
+
+      # Returns a future that completes after the specified number of seconds.
+      #
+      # @param timeout [Float] the number of seconds to wait until the returned
+      #   future is completed
+      # @return [Ione::Future] a future that completes when the timer expires
+      def schedule_timer(timeout)
+        @io_loop.schedule_timer(timeout)
+      end
+
+      def to_s
+        @io_loop.to_s
+      end
+    end
+
+    # @private
+    class Unblocker
+      def initialize
+        @out, @in = IO.pipe
+        @lock = Mutex.new
+      end
+
+      def connected?
+        true
+      end
+
+      def connecting?
+        false
+      end
+
+      def writable?
+        false
+      end
+
+      def closed?
+        @in.nil?
+      end
+
+      def unblock!
+        @lock.synchronize do
+          @in.write(PING_BYTE)
+        end
+      end
+
+      def read
+        @out.read_nonblock(2**16)
+      end
+
+      def close
+        @in.close
+        @out.close
+        @in = nil
+        @out = nil
+      end
+
+      def to_io
+        @out
+      end
+
+      def to_s
+        %(#<#{self.class.name}>)
+      end
+
+      private
+
+      PING_BYTE = "\0".freeze
+    end
+
+    # @private
+    class IoLoopBody
+      def initialize(options={})
+        @selector = options[:selector] || IO
+        @clock = options[:clock] || Time
+        @lock = Mutex.new
+        @sockets = []
+        @timers = []
+      end
+
+      def add_socket(socket)
+        @lock.synchronize do
+          sockets = @sockets.reject { |s| s.closed? }
+          sockets << socket
+          @sockets = sockets
+        end
+      end
+
+      def schedule_timer(timeout, promise=Promise.new)
+        @lock.synchronize do
+          timers = @timers.reject { |pair| pair[1].nil? }
+          timers << [@clock.now + timeout, promise]
+          @timers = timers
+        end
+        promise.future
+      end
+
+      def close_sockets
+        @sockets.each do |s|
+          begin
+            s.close unless s.closed?
+          rescue
+            # the socket had most likely already closed due to an error
+          end
+        end
+      end
+
+      def cancel_timers
+        @timers.each do |pair|
+          if pair[1]
+            pair[1].fail(CancelledError.new)
+            pair[1] = nil
+          end
+        end
+      end
+
+      def tick(timeout=1)
+        check_sockets!(timeout)
+        check_timers!
+      end
+
+      def to_s
+        %(#<#{IoReactor.name} @connections=[#{@sockets.map(&:to_s).join(', ')}]>)
+      end
+
+      private
+
+      def check_sockets!(timeout)
+        readables, writables, connecting = [], [], []
+        sockets = @sockets
+        sockets.each do |s|
+          next if s.closed?
+          readables << s if s.connected?
+          writables << s if s.connecting? || s.writable?
+          connecting << s if s.connecting?
+        end
+        r, w, _ = @selector.select(readables, writables, nil, timeout)
+        connecting.each(&:connect)
+        r && r.each(&:read)
+        w && w.each(&:flush)
+      end
+
+      def check_timers!
+        timers = @timers
+        timers.each do |pair|
+          if pair[1] && pair[0] <= @clock.now
+            pair[1].fulfill
+            pair[1] = nil
+          end
+        end
+      end
+    end
+  end
+end