ione 1.2.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7b16fd5d35a6cd0dd75c20ea9a3febd681f5a37b
-  data.tar.gz: 5aff84c71ae8a849858789063b528ed59b45c87c
+  metadata.gz: e616ec4a5f533a25efb171aa4e6ede4b1ca5de6f
+  data.tar.gz: 433284b5a259cb2db15f8ac95882d13d1e63507a
 SHA512:
-  metadata.gz: b6e57d6dc85d7b329353e8d7ff2cb8ba606ff2431377fb7f1e7ca1badf6e0b1ccc7e3971d03cf28387798b307c85cbb32de4c0dbc2851664e096447b190b7215
-  data.tar.gz: c6825f4358471a8c344f39f3473dc6c11d8f3367886d25953de255c84ebf53f214098f3deeb46471a323ef1a5b628c72e271a910d6930db5d146bba885ba29e6
+  metadata.gz: f80b6f25ac0192d10eac99cc8e2dd15b373944bb89e3125f378ff17df4a7a07caf0f35955e5772b322911560a8dff3cc42704c4c25dc67c952cd8c15269e5c8b
+  data.tar.gz: 885562d9eb7bb0cd1e6499a0b975fb2d82dee2298918fef4887ca66b5b9d4959c4bdacdd8c2aa2deb2a8e0f44187017dcc44dd9b801a5432bf0888caa720cac9

data/README.md

@@ -27,7 +27,7 @@ Networking usually means pushing lots of bytes around and in Ruby it's easy to m
 The [examples](https://github.com/iconara/ione/tree/master/examples) directory has some examples of what you can do with Ione, for example:
 
 * [redis_client](https://github.com/iconara/ione/tree/master/examples/redis_client) is a more or less full featured Redis client that uses most of Ione's features.
-* [http_client](https://github.com/iconara/ione/tree/master/examples/http_client) is a simplistic HTTP client that uses Ione and [http_parser.rb](http://rubygems.org/gems/http_parser.rb) to make HTTP GET request.
+* [http_client](https://github.com/iconara/ione/tree/master/examples/http_client) is a simplistic HTTP client that uses Ione and [http_parser.rb](http://rubygems.org/gems/http_parser.rb) to make HTTP GET request. It also shows how to make TLS connections.
 * [cql-rb](https://github.com/iconara/cql-rb) is a high performance Cassandra driver and where Ione was originally developed.
 * [cassandra-driver](https://github.com/datastax/ruby-driver) is the successor to cql-rb.
 * [ione-rpc](https://github.com/iconara/ione-rpc) is a RPC framework built on Ione. It makes it reasonably easy to build networked applications without having to reinvent the wheel.

data/lib/ione/byte_buffer.rb

@@ -14,6 +14,8 @@ module Ione
   # buffer and one is the write buffer. Writes go to the write buffer only,
   # and reads read from the read buffer until it is empty, then a new write
   # buffer is created and the old write buffer becomes the new read buffer.
+  #
+  # @since v1.0.0
   class ByteBuffer
     def initialize(initial_bytes=nil)
       @read_buffer = ''

data/lib/ione/future.rb

@@ -11,6 +11,7 @@ module Ione
   # A promise is the write end of a Promise/Future pair. It can be fulfilled
   # with a value or failed with an error. The value can be read through the
   # future returned by {#future}.
+  # @since v1.0.0
   class Promise
     attr_reader :future
 
@@ -104,7 +105,7 @@ module Ione
   #
   # @example Creating a future for a blocking operation
   #   def find_my_ip
-  #     promise = Promse.new
+  #     promise = Promise.new
   #     Thread.start do
   #       begin
   #         data = JSON.load(open('http://jsonip.org/').read)
@@ -178,7 +179,13 @@ module Ione
   # @see Ione::Future::FutureCallbacks
   # @see Ione::Future::FutureCombinators
   # @see Ione::Future::FutureFactories
+  # @since v1.0.0
   class Future
+    PENDING_STATE = 0
+    RESOLVED_STATE = 1
+    FAILED_STATE = 2
+
+    # @since v1.0.0
     module Factories
       # Combines multiple futures into a new future which resolves when all
       # constituent futures complete, or fails when one or more of them fails.
@@ -207,6 +214,33 @@ module Ione
         end
       end
 
+      # Combines multiple futures into a new future which resolves when all
+      # constituent futures complete, or fails when one or more of them fails.
+      #
+      # The resulting future has no value.
+      #
+      # @example
+      #   future = Future.after(delete_thing(1), delete_thing(2))
+      #   future.value # => nil
+      #
+      # @param [Array<Ione::Future>] futures the futures to combine (this argument
+      #   can be a splatted array or a regular array passed as sole argument)
+      # @return [Ione::Future] with a nil value once all futures have succeeded
+      # @since v1.3.0
+      def after(*futures)
+        if futures.size == 1 && (fs = futures.first).is_a?(Enumerable)
+          *futures = *fs
+        end
+        if futures.count == 0
+          ResolvedFuture::NIL
+        elsif futures.count == 1
+          futures.first.map(nil)
+        else
+          CombinedNilFuture.new(futures)
+        end
+      end
+
+
       # Returns a future which will be resolved with the value of the first
       # (resolved) of the specified futures. If all of the futures fail, the
       # returned future will also fail (with the error of the last failed future).
@@ -249,6 +283,7 @@ module Ione
       # @yieldreturn [Ione::Future] a future
       # @return [Ione::Future] a future that will resolve to an array of the values
       #   of the futures returned by the block
+      # @since v1.2.0
       def traverse(values, &block)
         all(values.map(&block))
       rescue => e
@@ -286,7 +321,8 @@ module Ione
       #
       # @param [Array<Ione::Future>] futures an array of futures whose values
       #   should be reduced
-      # @param [Object] initial_value the initial value of the accumulator
+      # @param [Object] initial_value the initial value of the accumulator. When
+      #   nil (the default) the value of the first future will be used instead. 
       # @param [Hash] options
       # @option options [Boolean] :ordered (true) whether or not to respect the
       #   order of the input when reducing – when true the block will be called
@@ -302,6 +338,7 @@ module Ione
       # @return [Ione::Future] a future that will resolve to the value returned
       #   from the last invocation of the block, or nil when the list of futures
       #   is empty.
+      # @since v1.2.0
       def reduce(futures, initial_value=nil, options=nil, &reducer)
         if options && options[:ordered] == false
           UnorderedReducingFuture.new(futures, initial_value, reducer)
@@ -328,6 +365,7 @@ module Ione
       end
     end
 
+    # @since v1.0.0
     module Combinators
       # Returns a new future representing a transformation of this future's value.
       #
@@ -411,6 +449,7 @@ module Ione
       # @yieldreturn [Object, Ione::Future] the transformed value, or a future
       #   that will resolve to the transformed value.
       # @return [Ione::Future] a new future representing the transformed value
+      # @since v1.2.0
       def then(&block)
         f = CompletableFuture.new
         on_complete do |v, e|
@@ -519,6 +558,7 @@ module Ione
       end
     end
 
+    # @since v1.0.0
     module Callbacks
       # Registers a listener that will be called when this future becomes
       # resolved. The listener will be called with the value of the future as
@@ -549,9 +589,10 @@ module Ione
     include Combinators
     include Callbacks
 
+    # @private
     def initialize
       @lock = Mutex.new
-      @state = :pending
+      @state = PENDING_STATE
       @listeners = []
     end
 
@@ -595,12 +636,12 @@ module Ione
     # @see Callbacks#on_failure
     def on_complete(&listener)
       run_immediately = false
-      if @state != :pending
+      if @state != PENDING_STATE
         run_immediately = true
       else
         @lock.lock
         begin
-          if @state == :pending
+          if @state == PENDING_STATE
             @listeners << listener
           else
             run_immediately = true
@@ -634,13 +675,13 @@ module Ione
     # @see Callbacks#on_failure
     # @see Callbacks#on_complete
     def value
-      raise @error if @state == :failed
-      return @value if @state == :resolved
+      raise @error if @state == FAILED_STATE
+      return @value if @state == RESOLVED_STATE
       semaphore = nil
       @lock.lock
       begin
-        raise @error if @state == :failed
-        return @value if @state == :resolved
+        raise @error if @state == FAILED_STATE
+        return @value if @state == RESOLVED_STATE
         semaphore = Queue.new
         u = proc { semaphore << :unblock }
         @listeners << u
@@ -650,8 +691,8 @@ module Ione
       while true
         @lock.lock
         begin
-          raise @error if @state == :failed
-          return @value if @state == :resolved
+          raise @error if @state == FAILED_STATE
+          return @value if @state == RESOLVED_STATE
         ensure
           @lock.unlock
         end
@@ -662,10 +703,10 @@ module Ione
 
     # Returns true if this future is resolved or failed
     def completed?
-      return true unless @state == :pending
+      return true unless @state == PENDING_STATE
       @lock.lock
       begin
-        @state != :pending
+        @state != PENDING_STATE
       ensure
         @lock.unlock
       end
@@ -673,10 +714,10 @@ module Ione
 
     # Returns true if this future is resolved
     def resolved?
-      return @state == :resolved unless @state == :pending
+      return @state == RESOLVED_STATE unless @state == PENDING_STATE
       @lock.lock
       begin
-        @state == :resolved
+        @state == RESOLVED_STATE
       ensure
         @lock.unlock
       end
@@ -684,10 +725,10 @@ module Ione
 
     # Returns true if this future has failed
     def failed?
-      return @state == :failed unless @state == :pending
+      return @state == FAILED_STATE unless @state == PENDING_STATE
       @lock.lock
       begin
-        @state == :failed
+        @state == FAILED_STATE
       ensure
         @lock.unlock
       end
@@ -731,9 +772,9 @@ module Ione
       listeners = nil
       @lock.lock
       begin
-        raise FutureError, 'Future already completed' unless @state == :pending
+        raise FutureError, 'Future already completed' unless @state == PENDING_STATE
         @value = v
-        @state = :resolved
+        @state = RESOLVED_STATE
         listeners = @listeners
         @listeners = nil
       ensure
@@ -749,9 +790,9 @@ module Ione
       listeners = nil
       @lock.lock
       begin
-        raise FutureError, 'Future already completed' unless @state == :pending
+        raise FutureError, 'Future already completed' unless @state == PENDING_STATE
         @error = error
-        @state = :failed
+        @state = FAILED_STATE
         listeners = @listeners
         @listeners = nil
       ensure
@@ -793,14 +834,37 @@ module Ione
     end
   end
 
+  # @private
+  class CombinedNilFuture < CompletableFuture
+    def initialize(futures)
+      super()
+      @futures = futures
+      await_next(nil, nil)
+    end
+
+    def await_next(v, e)
+      if e
+        @futures = nil
+        fail(e)
+      elsif @futures.empty?
+        @futures = nil
+        resolve
+      else
+        @futures.pop.on_complete(&method(:await_next))
+      end
+    end
+  end
+
   # @private
   class ReducingFuture < CompletableFuture
+    NO_INITIAL_VALUE = Object.new
+
     def initialize(futures, initial_value, reducer)
       super()
       @futures = Array(futures)
       @remaining = @futures.size
       @initial_value = initial_value
-      @accumulator = initial_value
+      @accumulator = initial_value.nil? ? NO_INITIAL_VALUE : initial_value
       @reducer = reducer
     end
 
@@ -810,10 +874,10 @@ module Ione
       unless failed?
         @lock.lock
         begin
-          if @accumulator
-            @accumulator = @reducer.call(@accumulator, value)
-          else
+          if @accumulator.equal?(NO_INITIAL_VALUE)
             @accumulator = value
+          else
+            @accumulator = @reducer.call(@accumulator, value)
           end
           @remaining -= 1
         rescue => e
@@ -905,7 +969,7 @@ module Ione
   # @private
   class ResolvedFuture < Future
     def initialize(value=nil)
-      @state = :resolved
+      @state = RESOLVED_STATE
       @value = value
       @error = nil
     end
@@ -943,7 +1007,7 @@ module Ione
   # @private
   class FailedFuture < Future
     def initialize(error)
-      @state = :failed
+      @state = FAILED_STATE
       @value = nil
       @error = error
     end

data/lib/ione/io/acceptor.rb

@@ -3,11 +3,19 @@
 
 module Ione
   module Io
+    # An acceptor wraps a server socket and accepts client connections.
+    # @since v1.1.0
     class Acceptor
+      # @private
       ServerSocket = RUBY_ENGINE == 'jruby' ? ::ServerSocket : Socket
 
+      BINDING_STATE = 0
+      CONNECTED_STATE = 1
+      CLOSED_STATE = 2
+
       attr_reader :backlog
 
+      # @private
       def initialize(host, port, backlog, unblocker, reactor, socket_impl=nil)
         @host = host
         @port = port
@@ -17,15 +25,19 @@ module Ione
         @socket_impl = socket_impl || ServerSocket
         @accept_listeners = []
         @lock = Mutex.new
-        @state = :binding
+        @state = BINDING_STATE
       end
 
+      # Register a listener to be notified when client connections are accepted
+      #
+      # @yieldparam [Ione::Io::ServerConnection] the connection to the client
       def on_accept(&listener)
         @lock.synchronize do
           @accept_listeners << listener
         end
       end
 
+      # @private
       def bind
         addrinfos = @socket_impl.getaddrinfo(@host, @port, nil, Socket::SOCK_STREAM)
         begin
@@ -39,17 +51,18 @@ module Ione
             retry
           end
         end
-        @state = :connected
+        @state = CONNECTED_STATE
         Future.resolved(self)
       rescue => e
         close
         Future.failed(e)
       end
 
+      # Stop accepting connections
       def close
         @lock.synchronize do
-          return false if @state == :closed
-          @state = :closed
+          return false if @state == CLOSED_STATE
+          @state = CLOSED_STATE
         end
         if @io
           begin
@@ -63,26 +76,32 @@ module Ione
         true
       end
 
+      # @private
       def to_io
         @io
       end
 
+      # Returns true if the acceptor has stopped accepting connections
       def closed?
-        @state == :closed
+        @state == CLOSED_STATE
       end
 
+      # Returns true if the acceptor is accepting connections
       def connected?
-        @state != :closed
+        @state != CLOSED_STATE
       end
 
+      # @private
       def connecting?
         false
       end
 
+      # @private
       def writable?
         false
       end
 
+      # @private
       def read
         client_socket, host, port = accept
         connection = ServerConnection.new(client_socket, host, port, @unblocker)
@@ -91,10 +110,12 @@ module Ione
       end
 
       if RUBY_ENGINE == 'jruby'
+        # @private
         def bind_socket(socket, addr, backlog)
           socket.bind(addr, backlog)
         end
       else
+        # @private
         def bind_socket(socket, addr, backlog)
           socket.bind(addr)
           socket.listen(backlog)

data/lib/ione/io/base_connection.rb

@@ -2,14 +2,21 @@
 
 module Ione
   module Io
+    # @since v1.0.0
     class BaseConnection
+      CONNECTING_STATE = 0
+      CONNECTED_STATE = 1
+      DRAINING_STATE = 2
+      CLOSED_STATE = 3
+
       attr_reader :host, :port
 
+      # @private
       def initialize(host, port, unblocker)
         @host = host
         @port = port
         @unblocker = unblocker
-        @state = :connecting
+        @state = CONNECTING_STATE
         @writable = false
         @lock = Mutex.new
         @write_buffer = ByteBuffer.new
@@ -21,8 +28,8 @@ module Ione
       # @return [true, false] returns false if the connection was already closed
       def close(cause=nil)
         @lock.synchronize do
-          return false if @state == :closed
-          @state = :closed
+          return false if @state == CLOSED_STATE
+          @state = CLOSED_STATE
           @writable = false
         end
         if @io
@@ -50,30 +57,31 @@ module Ione
       #
       # @return [Ione::Future] a future that resolves to the connection when it
       #   has closed
+      # @since v1.1.0
       def drain
-        @state = :draining
+        @state = DRAINING_STATE
         close unless @writable
         @closed_promise.future
       end
 
       # @private
       def connecting?
-        @state == :connecting
+        @state == CONNECTING_STATE
       end
 
       # Returns true if the connection is connected
       def connected?
-        @state == :connected
+        @state == CONNECTED_STATE
       end
 
       # Returns true if the connection is closed
       def closed?
-        @state == :closed
+        @state == CLOSED_STATE
       end
 
       # @private
       def writable?
-        @writable && @state != :closed
+        @writable && @state != CLOSED_STATE
       end
 
       # Register to receive notifications when new data is read from the socket.
@@ -119,7 +127,7 @@ module Ione
       # @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)
-        if @state == :connected || @state == :connecting
+        if @state == CONNECTED_STATE || @state == CONNECTING_STATE
           @lock.lock
           begin
             if block_given?
@@ -137,7 +145,7 @@ module Ione
 
       # @private
       def flush
-        if @state == :connected || @state == :draining
+        if @state == CONNECTED_STATE || @state == DRAINING_STATE
           @lock.lock
           begin
             if @writable
@@ -145,7 +153,7 @@ module Ione
               @write_buffer.discard(bytes_written)
             end
             @writable = !@write_buffer.empty?
-            if @state == :draining && !@writable
+            if @state == DRAINING_STATE && !@writable
               close
             end
           ensure
@@ -158,7 +166,7 @@ module Ione
 
       # @private
       def read
-        new_data = @io.read_nonblock(2**16)
+        new_data = @io.read_nonblock(65536)
         @data_listener.call(new_data) if @data_listener
       rescue => e
         close(e)
@@ -170,7 +178,11 @@ module Ione
       end
 
       def to_s
-        %(#<#{self.class.name} #{@state} #{@host}:#{@port}>)
+        state_constant_name = self.class.constants.find do |name|
+          name.to_s.end_with?('_STATE') && self.class.const_get(name) == @state
+        end
+        state = state_constant_name.to_s.rpartition('_').first
+        %(#<#{self.class.name} #{state} #{@host}:#{@port}>)
       end
     end
   end