cool.io 0.9.0

data/lib/cool.io/iowatcher.rb

@@ -0,0 +1,17 @@
+#--
+# Copyright (C)2007-10 Tony Arcieri
+# You can redistribute this under the terms of the Ruby license
+# See file LICENSE for details
+#++
+
+module Coolio
+  class IOWatcher 
+    # The actual implementation of this class resides in the C extension
+    # Here we metaprogram proper event_callbacks for the callback methods
+    # These can take a block and store it to be called when the event
+    # is actually fired.
+
+    extend Meta
+    event_callback :on_readable, :on_writable
+  end
+end

data/lib/cool.io/listener.rb

@@ -0,0 +1,93 @@
+#--
+# Copyright (C)2007-10 Tony Arcieri
+# You can redistribute this under the terms of the Ruby license
+# See file LICENSE for details
+#++
+
+require 'socket'
+
+module Coolio
+  # Listeners wait for incoming connections.  When a listener receives a
+  # connection it fires the on_connection event with the newly accepted
+  # socket as a parameter.
+  class Listener < IOWatcher
+    def initialize(listen_socket)
+      @listen_socket = listen_socket
+      super(@listen_socket)
+    end
+
+    # Returns an integer representing the underlying numeric file descriptor
+    def fileno
+      @listen_socket.fileno
+    end
+
+    # Close the listener
+    def close
+      detach if attached?
+      @listen_socket.close
+    end
+
+    # Called whenever the server receives a new connection
+    def on_connection(socket); end
+    event_callback :on_connection
+
+    #########
+    protected
+    #########
+
+    # Coolio callback for handling new connections
+    def on_readable
+      begin
+        on_connection @listen_socket.accept_nonblock
+      rescue Errno::EAGAIN, Errno::ECONNABORTED
+        # EAGAIN can be triggered here if the socket is shared between
+        # multiple processes and a thundering herd is woken up to accept
+        # one connection, only one process will get the connection and
+        # the others will be awoken.
+        # ECONNABORTED is documented in accept() manpages but modern TCP
+        # stacks with syncookies and/or accept()-filtering for DoS
+        # protection do not see it.  In any case this error is harmless
+        # and we should instead spend our time with clients that follow
+        # through on connection attempts.
+      end
+    end
+  end
+
+  class TCPListener < Listener
+    DEFAULT_BACKLOG = 1024
+    
+    # Create a new Coolio::TCPListener on the specified address and port.
+    # Accepts the following options:
+    #
+    #  :backlog - Max size of the pending connection queue (default 1024)
+    #  :reverse_lookup - Retain BasicSocket's reverse DNS functionality (default false)
+    #
+    # If the specified address is an TCPServer object, it will ignore
+    # the port and :backlog option and create a new Coolio::TCPListener out
+    # of the existing TCPServer object.
+    def initialize(addr, port = nil, options = {})
+      BasicSocket.do_not_reverse_lookup = true unless options[:reverse_lookup]
+      options[:backlog] ||= DEFAULT_BACKLOG
+      
+      listen_socket = if ::TCPServer === addr
+        addr
+      else
+        raise ArgumentError, "port must be an integer" if nil == port
+        ::TCPServer.new(addr, port)
+      end
+      listen_socket.instance_eval { listen(options[:backlog]) }
+      super(listen_socket)
+    end
+  end
+
+  class UNIXListener < Listener
+    # Create a new Coolio::UNIXListener
+    #
+    # Accepts the same arguments as UNIXServer.new
+    # Optionally, it can also take anyn existing UNIXServer object
+    # and create a Coolio::UNIXListener out of it.
+    def initialize(*args)
+      super(::UNIXServer === args.first ? args.first : ::UNIXServer.new(*args))
+    end
+  end
+end

data/lib/cool.io/loop.rb

@@ -0,0 +1,130 @@
+#--
+# Copyright (C)2007-10 Tony Arcieri
+# You can redistribute this under the terms of the Ruby license
+# See file LICENSE for details
+#++
+
+require 'thread'
+
+# Monkeypatch Thread to include a method for obtaining the default Coolio::Loop
+class Thread
+  def _coolio_loop
+    @_coolio_loop ||= Coolio::Loop.new
+  end
+end
+
+module Coolio
+  class Loop
+    # In Ruby 1.9 we want a Coolio::Loop per thread, but Ruby 1.8 is unithreaded
+    if RUBY_VERSION >= "1.9.0"
+      # Retrieve the default event loop for the current thread
+      def self.default
+        Thread.current._coolio_loop
+      end
+    else
+      # Retrieve the default event loop
+      def self.default
+        @@_coolio_loop ||= Coolio::Loop.new
+      end
+    end
+
+    # Create a new Coolio::Loop
+    #
+    # Options:
+    #
+    # :skip_environment (boolean)
+    #   Ignore the $LIBEV_FLAGS environment variable
+    #
+    # :fork_check (boolean)      
+    #   Enable autodetection of forks
+    #
+    # :backend
+    #   Choose the default backend, one (or many in an array) of:
+    #     :select (most platforms)
+    #     :poll   (most platforms except Windows)
+    #     :epoll  (Linux)
+    #     :kqueue (BSD/Mac OS X)
+    #     :port   (Solaris 10)
+    #
+    def initialize(options = {})
+      @watchers = {}
+      @active_watchers = 0
+      
+      flags = 0
+
+      options.each do |option, value|
+        case option
+        when :skip_environment
+          flags |= EVFLAG_NOEV if value
+        when :fork_check
+          flags |= EVFLAG_FORKCHECK if value
+        when :backend
+          value = [value] unless value.is_a? Array
+          value.each do |backend|
+            case backend
+            when :select then flags |= EVBACKEND_SELECT
+            when :poll   then flags |= EVBACKEND_POLL
+            when :epoll  then flags |= EVBACKEND_EPOLL
+            when :kqueue then flags |= EVBACKEND_KQUEUE
+            when :port   then flags |= EVBACKEND_PORT
+            else raise ArgumentError, "no such backend: #{backend}"
+            end
+          end
+        else raise ArgumentError, "no such option: #{option}"
+        end
+      end
+
+      @loop = ev_loop_new(flags)
+    end
+    
+    # Attach a watcher to the loop
+    def attach(watcher)
+      watcher.attach self
+    end
+
+    # Run the event loop and dispatch events back to Ruby.  If there
+    # are no watchers associated with the event loop it will return
+    # immediately.  Otherwise, run will continue blocking and making
+    # event callbacks to watchers until all watchers associated with
+    # the loop have been disabled or detached.  The loop may be 
+    # explicitly stopped by calling the stop method on the loop object.
+    def run
+      raise RuntimeError, "no watchers for this loop" if @watchers.empty?
+
+      @running = true
+      while @running and not @active_watchers.zero?
+        run_once
+      end
+      @running = false
+    end
+
+    # Stop the event loop if it's running
+    def stop
+      raise RuntimeError, "loop not running" unless @running
+      @running = false
+    end
+    
+    # Does the loop have any active watchers?
+    def has_active_watchers?
+      @active_watchers > 0
+    end
+    
+    # All watchers attached to the current loop
+    def watchers
+      @watchers.keys
+    end
+    
+    #######
+    private
+    #######
+    
+    EVFLAG_NOENV     = 0x1000000  # do NOT consult environment
+    EVFLAG_FORKCHECK = 0x2000000  # check for a fork in each iteration
+
+    EVBACKEND_SELECT = 0x00000001 # supported about anywhere 
+    EVBACKEND_POLL   = 0x00000002 # !win 
+    EVBACKEND_EPOLL  = 0x00000004 # linux 
+    EVBACKEND_KQUEUE = 0x00000008 # bsd 
+    EVBACKEND_PORT   = 0x00000020 # solaris 10
+  end
+end

data/lib/cool.io/meta.rb

@@ -0,0 +1,49 @@
+#--
+# Copyright (C)2007-10 Tony Arcieri
+# You can redistribute this under the terms of the Ruby license
+# See file LICENSE for details
+#++
+
+module Coolio
+  module Meta
+    # Use an alternate watcher with the attach/detach/enable/disable methods
+    # if it is presently assigned.  This is useful if you are waiting for
+    # an event to occur before the current watcher can be used in earnest,
+    # such as making an outgoing TCP connection.
+    def watcher_delegate(proxy_var)
+      %w{attach detach enable disable}.each do |method|
+        module_eval <<-EOD
+          def #{method}(*args)
+            if #{proxy_var}
+              #{proxy_var}.#{method}(*args)
+              return self
+            end
+
+            super
+          end
+        EOD
+      end
+    end
+
+    # Define callbacks whose behavior can be changed on-the-fly per instance.
+    # This is done by giving a block to the callback method, which is captured
+    # as a proc and stored for later.  If the method is called without a block,
+    # the stored block is executed if present, otherwise it's a noop.
+    def event_callback(*methods)
+      methods.each do |method|
+        module_eval <<-EOD
+          def #{method}(*args, &block)
+            if block
+              @#{method}_callback = block
+              return
+            end
+            
+            if @#{method}_callback
+              instance_exec(*args, &@#{method}_callback) 
+            end
+          end
+        EOD
+      end
+    end
+  end
+end

data/lib/cool.io/server.rb

@@ -0,0 +1,74 @@
+#--
+# Copyright (C)2007-10 Tony Arcieri
+# You can redistribute this under the terms of the Ruby license
+# See file LICENSE for details
+#++
+
+module Coolio
+  class Server < Listener
+    # Servers listen for incoming connections and create new connection objects
+    # whenever incoming connections are received.  The default class for new
+    # connections is a Socket, but any subclass of IOWatcher is acceptable.
+    def initialize(listen_socket, klass = Socket, *args, &block)
+      # Ensure the provided class responds to attach
+      unless klass.allocate.is_a? IO
+        raise ArgumentError, "can't convert #{klass} to Coolio::IO"
+      end
+
+      # Verify the arity of the provided arguments
+      arity = klass.instance_method(:initialize).arity
+      expected = arity >= 0 ? arity : -(arity + 1)
+
+      if (arity >= 0 and args.size + 1 != expected) or (arity < 0 and args.size + 1 < expected)
+        raise ArgumentError, "wrong number of arguments for #{klass}#initialize (#{args.size+1} for #{expected})" 
+      end
+     
+      @klass, @args, @block = klass, args, block
+      super(listen_socket)
+    end
+
+    # Returns an integer representing the underlying numeric file descriptor
+    def fileno
+      @listen_socket.fileno
+    end
+
+    #########
+    protected
+    #########
+    
+    def on_connection(socket)
+      connection = @klass.new(socket, *@args).attach(evloop)
+      connection.__send__(:on_connect)
+      @block.call(connection) if @block
+    end
+  end
+
+  # TCP server class.  Listens on the specified host and port and creates
+  # new connection objects of the given class. This is the most common server class.
+  # Note that the new connection objects will be bound by default to the same event loop that the server is attached to.
+  # Optionally, it can also take any existing core TCPServer object as
+  # +host+ and create a Coolio::TCPServer out of it.
+  class TCPServer < Server
+    def initialize(host, port = nil, klass = TCPSocket, *args, &block)
+      listen_socket = if ::TCPServer === host
+        host
+      else
+        raise ArgumentError, "port must be an integer" if nil == port
+        ::TCPServer.new(host, port)
+      end
+      listen_socket.instance_eval { listen(1024) } # Change listen backlog to 1024
+      super(listen_socket, klass, *args, &block)
+    end
+  end
+
+  # UNIX server class.  Listens on the specified UNIX domain socket and
+  # creates new connection objects of the given class.
+  # Optionally, it can also take any existing core UNIXServer object as
+  # +path+ and create a Coolio::UNIXServer out of it.
+  class UNIXServer < Server
+    def initialize(path, klass = UNIXSocket, *args, &block)
+      s = ::UNIXServer === path ? path : ::UNIXServer.new(path)
+      super(s, klass, *args, &block)
+    end
+  end
+end

data/lib/cool.io/socket.rb

@@ -0,0 +1,224 @@
+#--
+# Copyright (C)2007 Tony Arcieri
+# You can redistribute this under the terms of the Ruby license
+# See file LICENSE for details
+#++
+
+require 'socket'
+require 'resolv'
+
+module Coolio
+  class Socket < IO    
+    def self.connect(socket, *args)
+
+      new(socket, *args).instance_eval do
+        @_connector = Connector.new(self, socket)
+        self
+      end
+    end
+    
+    watcher_delegate :@_connector
+
+    def attach(evloop)
+      raise RuntimeError, "connection failed" if @_failed
+      
+      if @_connector
+        @_connector.attach(evloop)
+        return self
+      end
+      
+      super
+    end
+
+    # Called upon completion of a socket connection
+    def on_connect; end
+    event_callback :on_connect
+    
+    # Called if a socket connection failed to complete
+    def on_connect_failed; end
+    event_callback :on_connect_failed
+    
+    # Called if a hostname failed to resolve when connecting
+    # Defaults to  calling on_connect_failed
+    def on_resolve_failed
+       on_connect_failed
+    end
+    
+    #########
+    protected
+    #########
+    
+    class Connector < IOWatcher
+      def initialize(coolio_socket, ruby_socket)
+        @coolio_socket, @ruby_socket = coolio_socket, ruby_socket
+        super(ruby_socket, :w)
+      end
+      
+      def on_writable
+        evl = evloop
+        detach
+
+        if connect_successful?
+          @coolio_socket.instance_eval { @_connector = nil }
+          @coolio_socket.attach(evl)
+          @ruby_socket.setsockopt(::Socket::IPPROTO_TCP, ::Socket::TCP_NODELAY, [1].pack("l"))
+          @ruby_socket.setsockopt(::Socket::SOL_SOCKET, ::Socket::SO_KEEPALIVE, true)
+
+          @coolio_socket.__send__(:on_connect)
+        else
+          @coolio_socket.instance_eval { @_failed = true }
+          @coolio_socket.__send__(:on_connect_failed)
+        end
+      end      
+
+      #######
+      private
+      #######
+
+      def connect_successful?
+        @ruby_socket.getsockopt(::Socket::SOL_SOCKET, ::Socket::SO_ERROR).unpack('i').first == 0
+      rescue IOError
+        false
+      end
+    end
+  end
+  
+  class TCPSocket < Socket
+    attr_reader :remote_host, :remote_addr, :remote_port, :address_family
+    watcher_delegate :@_resolver
+    
+    # Similar to .new, but used in cases where the resulting object is in a
+    # "half-open" state.  This is primarily used for when asynchronous
+    # DNS resolution is taking place.  We don't actually have a handle to
+    # the socket we want to use to create the watcher yet, since we don't
+    # know the IP address to connect to.
+    def self.precreate(*args, &block)
+      obj = allocate
+      obj.__send__(:preinitialize, *args, &block)
+      obj
+    end
+    
+    # Perform a non-blocking connect to the given host and port
+    # see examples/echo_client.rb
+    # addr is a string, can be an IP address or a hostname.
+    def self.connect(addr, port, *args)
+      family = nil
+
+      if (Resolv::IPv4.create(addr) rescue nil)
+        family = ::Socket::AF_INET
+      elsif(Resolv::IPv6.create(addr) rescue nil)
+        family = ::Socket::AF_INET6
+      end
+ 
+      if family
+        return super(TCPConnectSocket.new(family, addr, port), *args) # this creates a 'real' write buffer so we're ok there with regards to already having a write buffer from the get go
+      end
+
+      if host = Coolio::DNSResolver.hosts(addr)
+        return connect(host, port, *args) # calls this same function
+      end
+
+      precreate(addr, port, *args)
+    end
+    
+    # Called by precreate during asyncronous DNS resolution
+    def preinitialize(addr, port, *args)
+      @_write_buffer = ::IO::Buffer.new # allow for writing BEFORE the DNS has resolved
+      @remote_host, @remote_addr, @remote_port = addr, addr, port
+      @_resolver = TCPConnectResolver.new(self, addr, port, *args)
+    end
+    
+    private :preinitialize
+    
+    def initialize(socket)
+      unless socket.is_a?(::TCPSocket) or socket.is_a?(TCPConnectSocket)
+        raise TypeError, "socket must be a TCPSocket"
+      end
+      
+      super
+      
+      @address_family, @remote_port, @remote_host, @remote_addr = socket.peeraddr  
+    end
+    
+    def peeraddr
+      [@address_family, @remote_port, @remote_host, @remote_addr]
+    end
+    
+    #########
+    protected
+    #########
+
+    class TCPConnectSocket < ::Socket
+      def initialize(family, addr, port, host = addr)
+        @host,  addr, @port = host, addr, port
+        @address_family = nil
+
+        @socket = super(family, ::Socket::SOCK_STREAM, 0)
+        begin
+          @socket.connect_nonblock(::Socket.sockaddr_in(port, addr))
+        rescue Errno::EINPROGRESS
+        end
+      end
+
+      def peeraddr
+        [
+          @address_family == ::Socket::AF_INET ? 'AF_INET' : 'AF_INET6',
+          @port,
+          @host,
+          @addr
+        ]
+      end
+    end
+
+    class TCPConnectResolver < Coolio::DNSResolver
+      def initialize(socket, host, port, *args)
+        @sock, @host, @port, @args = socket, host, port, args
+        super(host)
+      end
+
+      def on_success(addr)
+        host, port, args = @host, @port, @args
+
+        @sock.instance_eval do
+          # DNSResolver only supports IPv4 so we can safely assume IPv4 address
+          begin
+            socket = TCPConnectSocket.new(::Socket::AF_INET, addr, port, host)
+          rescue Errno::ENETUNREACH
+            on_connect_failed
+            return
+          end
+
+          initialize(socket, *args)
+          @_connector = Socket::Connector.new(self, socket)
+          @_resolver = nil
+        end
+        @sock.attach(evloop)
+      end
+
+      def on_failure
+        @sock.__send__(:on_resolve_failed)
+        @sock.instance_eval do 
+          @_resolver = nil 
+          @_failed = true
+        end
+        return
+      end
+    end
+  end
+  
+  class UNIXSocket < Socket
+    attr_reader :path, :address_family
+    
+    # Connect to the given UNIX domain socket
+    def self.connect(path, *args)
+      new(::UNIXSocket.new(path), *args)
+    end
+    
+    def initialize(socket)
+      raise ArgumentError, "socket must be a UNIXSocket" unless socket.is_a? ::UNIXSocket
+      
+      super
+      @address_family, @path = socket.peeraddr
+    end
+  end
+end