arachni-reactor 0.1.0.beta1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    N2QwMGQ1ZmU1MGEwYTViZDgzOWZiYmFlMzZhZjA4OTZkNjY4YmIyNA==
+  data.tar.gz: !binary |-
+    MGMyYjhhMTc1MTU1NTAyMjNlNWY3N2VjNzlhNGZjZjM5OWU3M2Y1ZA==
+SHA512:
+  metadata.gz: !binary |-
+    MGJlY2Q1Njk4OTVkODI3ODZmNTUwZGM0MTBiMDBiZjY0ZTVkNDQ4ZTgyOTEy
+    YWFiOWNjYzgwZTA5Y2FiMzljOTc5NmY5MWM3M2JkM2U5Nzg5ZDJhMjJlMzRm
+    NDMwYzI2NzkwOGI0ZTQ1YjhlMjA0NDYzZjAxMTlkZTUyNDUwOWY=
+  data.tar.gz: !binary |-
+    ZGQ2ZmE0Y2UwNWRhY2ZmMGY0ZTFjNTgzYTM5M2IyMDdiNzE5YmRiOTllOTQ5
+    Nzk4MzkwNjJkY2VjMDY2OWQ4NWM5MTFhNDE3MmVjNWRhYjljMzI2YTk0ZmFl
+    OWM0ZDAzY2Q1YzhmNWU3NWZiZmVhODZiYzc0YWQyMjNiZjFkOGY=

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# ChangeLog
+
+## Version 0.1.0 (_Under development_)
+
+ - Initial release.

data/LICENSE.md

@@ -0,0 +1,29 @@
+# License
+
+    Copyright (C) 2014, Tasos Laskos <tasos.laskos@gmail.com>
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without modification,
+    are permitted provided that the following conditions are met:
+
+        * Redistributions of source code must retain the above copyright notice,
+          this list of conditions and the following disclaimer.
+
+        * Redistributions in binary form must reproduce the above copyright notice,
+          this list of conditions and the following disclaimer in the documentation
+          and/or other materials provided with the distribution.
+
+        * Neither the name of the copyright holder nor the names of its contributors
+          may be used to endorse or promote products derived from this software
+          without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+    ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+    ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,79 @@
+# Arachni::Reactor
+
+<table>
+    <tr>
+        <th>Version</th>
+        <td>0.1.0.beta1</td>
+    </tr>
+    <tr>
+        <th>Github page</th>
+        <td><a href="http://github.com/Arachni/arachni-reactor">http://github.com/Arachni/arachni-reactor</a></td>
+     <tr/>
+    <tr>
+        <th>Code Documentation</th>
+        <td><a href="http://rubydoc.info/github/Arachni/arachni-reactor/">http://rubydoc.info/github/Arachni/arachni-reactor/</a></td>
+    </tr>
+    <tr>
+       <th>Author</th>
+       <td><a href="http://twitter.com/Zap0tek">Tasos Laskos</a></td>
+    </tr>
+    <tr>
+        <th>Twitter</th>
+        <td><a href="http://twitter.com/ArachniScanner">@ArachniScanner</a></td>
+    </tr>
+    <tr>
+        <th>Copyright</th>
+        <td>2014</td>
+    </tr>
+    <tr>
+        <th>License</th>
+        <td><a href="file.LICENSE.html">3-clause BSD</a></td>
+    </tr>
+</table>
+
+## Synopsis
+
+`Arachni::Reactor` is a simple, lightweight, pure-Ruby implementation of the
+[Reactor](http://en.wikipedia.org/wiki/Reactor_pattern) pattern, mainly focused
+on network connections -- and less so on generic tasks.
+
+## Features
+
+ - Extremely lightweight.
+ - Very simple design.
+ - Support for TCP/IP and UNIX-domain sockets.
+ - TLS encryption.
+ - Pure-Ruby.
+ - Multi-platform.
+
+## Supported platforms
+
+ - Rubies:
+    - MRI >= 1.9
+    - Rubinius
+    - JRuby (Without OpenSSL support)
+ - Operating Systems:
+    - Linux
+    - OSX
+    - Windows
+
+## Examples
+
+For examples please see the `examples/` directory.
+
+## Installation
+
+## Running the Specs
+
+    rake spec
+
+## Bug reports/Feature requests
+
+Please send your feedback using GitHub's issue system at
+[http://github.com/arachni/arachni-reactor/issues](http://github.com/arachni/arachni-reactor/issues).
+
+
+## License
+
+Arachni::Reactor is provided under the 3-clause BSD license.
+See the [LICENSE](https://github.com/Arachni/arachni-reactor/blob/master/LICENSE.md) file for more information.

data/Rakefile

@@ -0,0 +1,53 @@
+=begin
+
+    This file is part of the Arachni::Reactor project and may be subject to
+    redistribution and commercial restrictions. Please see the Arachni::Reactor
+    web site for more information on licensing and terms of use.
+
+=end
+
+require 'rubygems'
+require File.expand_path( File.dirname( __FILE__ ) ) + '/lib/arachni/reactor/version'
+
+begin
+    require 'rspec'
+    require 'rspec/core/rake_task'
+
+    RSpec::Core::RakeTask.new
+rescue
+end
+
+task default: [ :build, :spec ]
+
+desc 'Generate docs'
+task :docs do
+    outdir = '../arachni-reactor-docs'
+    sh "rm -rf #{outdir}"
+    sh "mkdir -p #{outdir}"
+
+    sh "yardoc -o #{outdir}"
+
+    sh 'rm -rf .yardoc'
+end
+
+desc 'Clean up'
+task :clean do
+    sh 'rm *.gem || true'
+end
+
+desc 'Build the gem.'
+task build: [ :clean ] do
+    sh "gem build arachni-reactor.gemspec"
+end
+
+desc 'Build and install the gem.'
+task install: [ :build ] do
+    sh "gem install arachni-reactor-#{Arachni::Reactor::VERSION}.gem"
+end
+
+desc 'Push a new version to Rubygems'
+task publish: [ :build ] do
+    sh "git tag -a v#{Arachni::Reactor::VERSION} -m 'Version #{Arachni::Reactor::VERSION}'"
+    sh "gem push arachni-reactor-#{Arachni::Reactor::VERSION}.gem"
+end
+task release: [ :publish ]

data/lib/arachni/reactor.rb

@@ -0,0 +1,679 @@
+=begin
+
+    This file is part of the Arachni::Reactor project and may be subject to
+    redistribution and commercial restrictions. Please see the Arachni::Reactor
+    web site for more information on licensing and terms of use.
+
+=end
+
+require 'socket'
+require 'openssl'
+
+module Arachni
+
+# Reactor scheduler and and resource factory.
+#
+# You're probably interested in:
+#
+#   * Getting access to a shared and {.global globally accessible Reactor} --
+#       that's probably what you want.
+#       * Rest of the class methods can be used to manage it.
+#   * Creating resources like:
+#       * Cross-thread, non-blocking {#create_queue Queues}.
+#       * Asynchronous, concurrent {#create_iterator Iterators}.
+#       * Network connections to:
+#           * {#connect Connect} to a server.
+#           * {#listen Listen} for clients.
+#       * Tasks to be scheduled:
+#           * {#schedule As soon as possible}.
+#           * {#on_tick On every loop iteration}.
+#           * {#delay After a configured delay}.
+#           * {#at_interval Every few seconds}.
+#           * {#on_shutdown During shutdown}.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+class Reactor
+
+    # {Reactor} error namespace.
+    #
+    # All {Reactor} errors inherit from and live under it.
+    #
+    # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+    class Error < StandardError
+
+        # Raised when trying to perform an operation that requires the Reactor
+        # to be running when it is not.
+        #
+        # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+        class NotRunning < Error
+        end
+
+        # Raised when trying to run an already running loop.
+        #
+        # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+        class AlreadyRunning < Error
+        end
+
+        # Raised when trying to use UNIX-domain sockets on a host OS that
+        # does not support them.
+        #
+        # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+        class UNIXSocketsNotSupported < Error
+        end
+
+    end
+
+    %w(connection tasks queue iterator global).each do |f|
+        require_relative "reactor/#{f}"
+    end
+
+    # @return     [Integer,nil]
+    #   Amount of time to wait for a connection.
+    attr_accessor :max_tick_interval
+
+    # @return     [Array<Connection>]
+    #   {#attach Attached} connections.
+    attr_reader   :connections
+
+    # @return     [Integer]
+    #   Amount of ticks.
+    attr_reader   :ticks
+
+    DEFAULT_OPTIONS = {
+        select_timeout:    0.02,
+        max_tick_interval: 0.02
+    }
+
+    class <<self
+
+        # @return   [Reactor]
+        #   Lazy-loaded, globally accessible Reactor.
+        def global
+            @reactor ||= Global.instance
+        end
+
+        # Stops the {.global global Reactor} instance and destroys it. The next
+        # call to {.global} will return a new instance.
+        def stop
+            return if !@reactor
+
+            global.stop rescue Error::NotRunning
+
+            # Admittedly not the cleanest solution, but that's the only way to
+            # force a Singleton to re-initialize -- and we want the Singleton to
+            # cleanly implement the pattern in a Thread-safe way.
+            global.class.instance_variable_set(:@singleton__instance__, nil)
+
+            @reactor = nil
+        end
+
+        def supports_unix_sockets?
+            return false if jruby?
+
+            !!UNIXSocket
+        rescue NameError
+            false
+        end
+
+        def jruby?
+            RUBY_PLATFORM == 'java'
+        end
+    end
+
+    # @param    [Hash]  options
+    # @option   options  [Integer,nil]   :max_tick_interval    (0.02)
+    #   How long to wait for each tick when no connections are available for
+    #   processing.
+    # @option   options  [Integer]   :select_timeout    (0.02)
+    #   How long to wait for connection activity before continuing to the next
+    #   tick.
+    def initialize( options = {} )
+        options = DEFAULT_OPTIONS.merge( options )
+
+        @max_tick_interval = options[:max_tick_interval]
+        @select_timeout    = options[:select_timeout]
+
+        # Socket => Connection
+        @connections = {}
+        @stop        = false
+        @ticks       = 0
+        @thread      = nil
+        @tasks       = Tasks.new
+
+        @shutdown_tasks = Tasks.new
+        @done_signal    = ::Queue.new
+    end
+
+    # @return   [Reactor::Iterator]
+    #   New {Reactor::Iterator} with `self` as the scheduler.
+    # @param    [#to_a] list
+    #   List to iterate.
+    # @param    [Integer]   concurrency
+    #   Parallel workers to spawn.
+    def create_iterator( list, concurrency = 1 )
+        Reactor::Iterator.new( self, list, concurrency )
+    end
+
+    # @return   [Reactor::Queue]
+    #   New {Reactor::Queue} with `self` as the scheduler.
+    def create_queue
+        Reactor::Queue.new self
+    end
+
+    # @note {Connection::Error Connection errors} will be passed to the `handler`'s
+    #   {Connection::Callbacks#on_close} method as a `reason` argument.
+    #
+    # Connects to a peer.
+    #
+    # @overload  connect( host, port, handler = Connection, *handler_options )
+    #   @param    [String]    host
+    #   @param    [Integer]   port
+    #   @param    [Connection]   handler
+    #       Connection handler, should be a subclass of {Connection}.
+    #   @param    [Hash]   handler_options
+    #       Options to pass to the `#initialize` method of the `handler`.
+    #
+    # @overload  connect( unix_socket, handler = Connection, *handler_options )
+    #   @param    [String]    unix_socket
+    #       Path to the UNIX socket to connect.
+    #   @param    [Connection]   handler
+    #       Connection handler, should be a subclass of {Connection}.
+    #   @param    [Hash]   handler_options
+    #       Options to pass to the `#initialize` method of the `handler`.
+    #
+    # @return   [Connection]
+    #   Connected instance of `handler`.
+    #
+    # @raise    (see #fail_if_not_running)
+    # @raise    (see #fail_if_non_unix)
+    def connect( *args, &block )
+        fail_if_not_running
+
+        options = determine_connection_options( *args )
+
+        connection = options[:handler].new( *options[:handler_options] )
+        connection.reactor = self
+        block.call connection if block_given?
+
+        begin
+            Connection::Error.translate do
+                socket = options[:unix_socket] ?
+                    connect_unix( options[:unix_socket] ) :
+                    connect_tcp( options[:host], options[:port] )
+
+                connection.configure socket, :client
+                attach connection
+            end
+        rescue Connection::Error => e
+            connection.close e
+        end
+
+        connection
+    end
+
+    # @note {Connection::Error Connection errors} will be passed to the `handler`'s
+    #   {Connection::Callbacks#on_close} method as a `reason` argument.
+    #
+    # Listens for incoming connections.
+    #
+    # @overload  listen( host, port, handler = Connection, *handler_options )
+    #   @param    [String]    host
+    #   @param    [Integer]   port
+    #   @param    [Connection]   handler
+    #       Connection handler, should be a subclass of {Connection}.
+    #   @param    [Hash]   handler_options
+    #       Options to pass to the `#initialize` method of the `handler`.
+    #
+    #   @raise    [Connection::Error::HostNotFound]
+    #       If the `host` is invalid.
+    #   @raise    [Connection::Error::Permission]
+    #       If the `port` could not be opened due to a permission error.
+    #
+    # @overload  listen( unix_socket, handler = Connection, *handler_options )
+    #   @param    [String]    unix_socket
+    #       Path to the UNIX socket to create.
+    #   @param    [Connection]   handler
+    #       Connection handler, should be a subclass of {Connection}.
+    #   @param    [Hash]   handler_options
+    #       Options to pass to the `#initialize` method of the `handler`.
+    #
+    #   @raise    [Connection::Error::Permission]
+    #       If the `unix_socket` file could not be created due to a permission error.
+    #
+    # @return   [Connection]
+    #   Listening instance of `handler`.
+    #
+    # @raise    (see #fail_if_not_running)
+    # @raise    (see #fail_if_non_unix)
+    def listen( *args, &block )
+        fail_if_not_running
+
+        options = determine_connection_options( *args )
+
+        server_handler = proc do
+            c = options[:handler].new( *options[:handler_options] )
+            c.reactor = self
+            block.call c if block_given?
+            c
+        end
+
+        server = server_handler.call
+
+        begin
+            Connection::Error.translate do
+                socket = options[:unix_socket] ?
+                    listen_unix( options[:unix_socket] ) :
+                    listen_tcp( options[:host], options[:port] )
+
+                server.configure socket, :server, server_handler
+                attach server
+            end
+        rescue Connection::Error => e
+            server.close e
+        end
+
+        server
+    end
+
+    # @return   [Bool]
+    #   `true` if the {Reactor} is {#run running}, `false` otherwise.
+    def running?
+        !!thread
+    end
+
+    # Stops the {Reactor} {#run loop} {#schedule as soon as possible}.
+    #
+    # @raise    (see #fail_if_not_running)
+    def stop
+        schedule { @stop = true }
+    end
+
+    # Starts the {Reactor} loop and blocks the current {#thread} until {#stop}
+    # is called.
+    #
+    # @param    [Block] block
+    #   Block to call right before initializing the loop.
+    #
+    # @raise    (see #fail_if_running)
+    def run( &block )
+        fail_if_running
+
+        @done_signal.clear
+
+        @thread = Thread.current
+
+        block.call if block_given?
+
+        loop do
+            @tasks.call
+            break if @stop
+
+            process_connections
+            break if @stop
+
+            @ticks += 1
+        end
+
+        @tasks.clear
+        close_connections
+
+        @shutdown_tasks.call
+
+        @ticks  = 0
+        @thread = nil
+
+        @done_signal << nil
+    end
+
+    # {#run Runs} the Reactor in a thread and blocks until it is {#running?}.
+    #
+    # @param    (see #run)
+    #
+    # @return   [Thread]
+    #   {Reactor#thread}
+    #
+    # @raise    (see #fail_if_running)
+    def run_in_thread( &block )
+        fail_if_running
+
+        Thread.new do
+            run(&block)
+        end
+
+        sleep 0.1 while !running?
+
+        thread
+    end
+
+    # Waits for the Reactor to stop {#running?}.
+    #
+    # @raise    (see #fail_if_not_running)
+    def wait
+        fail_if_not_running
+
+        @done_signal.pop
+        true
+    end
+
+    # Starts the {#run Reactor loop}, blocks the current {#thread} while the
+    # given `block` executes and then {#stop}s it.
+    #
+    # @param    [Block] block
+    #   Block to call.
+    #
+    # @raise    (see #fail_if_running)
+    def run_block( &block )
+        fail ArgumentError, 'Missing block.' if !block_given?
+        fail_if_running
+
+        run do
+            block.call
+            next_tick { stop }
+        end
+    end
+
+    # @param    [Block] block
+    #   Schedules a {Tasks::Persistent task} to be run at each tick.
+    #
+    # @raise    (see #fail_if_not_running)
+    def on_tick( &block )
+        fail_if_not_running
+        @tasks << Tasks::Persistent.new( &block )
+        nil
+    end
+
+    # @param    [Block] block
+    #   Schedules a task to be run as soon as possible, either immediately if
+    #   the caller is {#in_same_thread? in the same thread}, or at the
+    #   {#next_tick} otherwise.
+    #
+    # @raise    (see #fail_if_not_running)
+    def schedule( &block )
+        fail_if_not_running
+
+        if running? && in_same_thread?
+            block.call
+        else
+            next_tick(&block)
+        end
+
+        nil
+    end
+
+    # @param    [Block] block
+    #   Schedules a {Tasks::OneOff task} to be run at {#stop shutdown}.
+    #
+    # @raise    (see #fail_if_not_running)
+    def on_shutdown( &block )
+        fail_if_not_running
+        @shutdown_tasks << Tasks::OneOff.new( &block )
+        nil
+    end
+
+    # @param    [Block] block
+    #   Schedules a {Tasks::OneOff task} to be run at the next tick.
+    #
+    # @raise    (see #fail_if_not_running)
+    def next_tick( &block )
+        fail_if_not_running
+        @tasks << Tasks::OneOff.new( &block )
+        nil
+    end
+
+    # @note Time accuracy cannot be guaranteed.
+    #
+    # @param    [Float] interval
+    #   Time in seconds.
+    # @param    [Block] block
+    #   Schedules a {Tasks::Periodic task} to be run at every `interval` seconds.
+    #
+    # @raise    (see #fail_if_not_running)
+    def at_interval( interval, &block )
+        fail_if_not_running
+        @tasks << Tasks::Periodic.new( interval, &block )
+        nil
+    end
+
+    # @note Time accuracy cannot be guaranteed.
+    #
+    # @param    [Float] time
+    #   Time in seconds.
+    # @param    [Block] block
+    #   Schedules a {Tasks::Delayed task} to be run in `time` seconds.
+    #
+    # @raise    (see #fail_if_not_running)
+    def delay( time, &block )
+        fail_if_not_running
+        @tasks << Tasks::Delayed.new( time, &block )
+        nil
+    end
+
+    # @return   [Thread, nil]
+    #   Thread of the {#run loop}, `nil` if not running.
+    def thread
+        @thread
+    end
+
+    # @return   [Bool]
+    #   `true` if the caller is in the same {#thread} as the {#run reactor loop},
+    #   `false` otherwise.
+    #
+    # @raise    (see #fail_if_not_running)
+    def in_same_thread?
+        fail_if_not_running
+        Thread.current == thread
+    end
+
+    # @note Will call {Connection::Callbacks#on_attach}.
+    #
+    # {Connection#attach Attaches} a connection to the {Reactor} loop.
+    #
+    # @param    [Connection]    connection
+    #
+    # @raise    (see #fail_if_not_running)
+    def attach( connection )
+        return if attached? connection
+
+        schedule do
+            connection.reactor = self
+            @connections[connection.socket] = connection
+            connection.on_attach
+        end
+    end
+
+    # @note Will call {Connection::Callbacks#on_detach}.
+    #
+    # {Connection#detach Detaches} a connection from the {Reactor} loop.
+    #
+    # @param    [Connection]    connection
+    #
+    # @raise    (see #fail_if_not_running)
+    def detach( connection )
+        return if !attached?( connection )
+
+        schedule do
+            connection.on_detach
+            @connections.delete connection.socket
+            connection.reactor = nil
+        end
+    end
+
+    # @return   [Bool]
+    #   `true` if the connection is attached, `false` otherwise.
+    def attached?( connection )
+        @connections.include? connection.socket
+    end
+
+    private
+
+    # @raise    [Error::NotRunning]
+    #   If the Reactor is not {#running?}.
+    def fail_if_not_running
+        fail Error::NotRunning, 'Reactor is not running.' if !running?
+    end
+
+    # @raise    [Error::NotRunning]
+    #   If the Reactor is already {#running?}.
+    def fail_if_running
+        fail Error::AlreadyRunning, 'Reactor is already running.' if running?
+    end
+
+    # @raise    [Error::UNIXSocketsNotSupported]
+    #   If trying to use UNIX-domain sockets on a host OS that does not
+    #   support them.
+    def fail_if_non_unix
+        return if self.class.supports_unix_sockets?
+
+        fail Error::UNIXSocketsNotSupported,
+             'The host OS does not support UNIX-domain sockets.'
+    end
+
+    def process_connections
+        if @connections.empty?
+            sleep @max_tick_interval
+            return
+        end
+
+        # Get connections with available events - :read, :write, :error.
+        selected = select_connections
+
+        # Close connections that have errors.
+        [selected.delete(:error)].flatten.compact.each(&:close)
+
+        # Call the corresponding event on the connections.
+        selected.each { |event, connections| connections.each(&"_#{event}".to_sym) }
+    end
+
+    def determine_connection_options( *args )
+        options = {}
+        host = port = unix_socket = nil
+
+        if args[1].is_a? Integer
+            options[:host], options[:port], options[:handler], *handler_options = *args
+        else
+            options[:unix_socket], options[:handler], *handler_options = *args
+        end
+
+        if !options[:unix_socket].is_a?( String ) &&
+            (!options[:host].is_a?( String ) || !options[:port].is_a?( Integer ))
+            fail ArgumentError,
+                 'Either a UNIX socket path or a host and port combination are required.'
+        end
+
+        options[:handler]       ||= Connection
+        options[:handler_options] = handler_options
+        options
+    end
+
+    # @return   [UNIXSocket]
+    #   Connected socket.
+    def connect_unix( unix_socket )
+        fail_if_non_unix
+
+        UNIXSocket.new( unix_socket )
+    end
+
+    # @return   [Socket]
+    #   Connected socket.
+    def connect_tcp( host, port )
+        socket = Socket.new(
+            Socket::Constants::AF_INET,
+            Socket::Constants::SOCK_STREAM,
+            Socket::Constants::IPPROTO_IP
+        )
+        socket.do_not_reverse_lookup = true
+
+        # JRuby throws java.nio.channels.NotYetConnectedException even after
+        # it returns the socket from Kernel.select, so wait for it to connect
+        # before moving on.
+        if self.class.jruby?
+            socket.connect( Socket.sockaddr_in( port, host ) )
+        else
+            begin
+                socket.connect_nonblock( Socket.sockaddr_in( port, host ) )
+            rescue IO::WaitReadable, IO::WaitWritable, Errno::EINPROGRESS
+            end
+        end
+
+        socket
+    end
+
+    # @return   [TCPServer]
+    #   Listening server socket.
+    def listen_tcp( host, port )
+        server = TCPServer.new( host, port )
+        server.do_not_reverse_lookup = true
+        server
+    end
+
+    # @return   [UNIXServer]
+    #   Listening server socket.
+    def listen_unix( unix_socket )
+        UNIXServer.new( unix_socket )
+    end
+
+    # Closes all client connections, both ingress and egress.
+    def close_connections
+        @connections.values.each(&:close)
+    end
+
+    # @return   [Hash]
+    #
+    #   Connections grouped by their available events:
+    #
+    #   * `:read` -- Ready for reading (i.e. with data in their incoming buffer).
+    #   * `:write` -- Ready for writing (i.e. with data in their
+    #       {Connection#has_outgoing_data? outgoing buffer).
+    #   * `:error`
+    def select_connections
+        grouped_sockets =
+            begin
+                Connection::Error.translate do
+                    select(
+                        read_sockets,
+                        write_sockets,
+                        read_sockets, # Read sockets are actually all sockets.
+                        @select_timeout
+                    )
+                end
+            rescue Connection::Error
+            end
+
+        return {} if !grouped_sockets
+
+        {
+            # Since these will be processed in order, it's better have the write
+            # ones first to flush the buffers ASAP.
+            write: connections_from_sockets( grouped_sockets[1] ),
+            read:  connections_from_sockets( grouped_sockets[0] ),
+            error: connections_from_sockets( grouped_sockets[2] )
+        }
+    end
+
+    # @return   [Array<Socket>]
+    #   Sockets of all connections, we want to be ready to read at any time.
+    def read_sockets
+        @connections.keys
+    end
+
+    # @return   [Array<Socket>]
+    #   Sockets of connections with
+    #   {Connection#has_outgoing_data? outgoing data}.
+    def write_sockets
+        @connections.map do |socket, connection|
+            next if !connection.has_outgoing_data?
+            socket
+        end.compact
+    end
+
+    def connections_from_sockets( sockets )
+        sockets.map { |s| connection_from_socket( s ) }
+    end
+
+    def connection_from_socket( socket )
+        @connections[socket]
+    end
+
+end
+
+end