ione 1.0.0.pre0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d01e0e0185b664af4fe4770c988a2560388ab05b
+  data.tar.gz: ce1e35186cc20d8732d0cecb1698720d2f3fb73b
+SHA512:
+  metadata.gz: 2a147567529615c86aefe2e2e6cfb5e0e0c57d99efef0bfedd02b4b91dd7acc611d98c98dd694a8ce2c6d657431134b14b7125b1a17bac97598aa560dda8026a
+  data.tar.gz: 92bf693d6bba06dd05e6434484f50802a780819db5b3f1a23c5ed02a30bc183362e1fbe7aeda581adc1223e32084fba11a24a9e7a2decb547e9122e441bd0e2d

data/.yardopts

@@ -0,0 +1,4 @@
+--no-private
+--markup markdown
+lib/**/*.rb
+-- README

data/lib/ione.rb

@@ -0,0 +1,8 @@
+# encoding: utf-8
+
+module Ione
+end
+
+require 'ione/future'
+require 'ione/byte_buffer'
+require 'ione/io'

data/lib/ione/byte_buffer.rb

@@ -0,0 +1,279 @@
+# encoding: utf-8
+
+module Ione
+  # A byte buffer is a more efficient way of working with bytes than using
+  # a regular Ruby string. It also has convenient methods for reading integers
+  # shorts and single bytes that are faster than `String#unpack`.
+  #
+  # When you use a string as a buffer, by adding to the end and taking away
+  # from the beginning, Ruby will continue to grow the backing array of
+  # characters. This means that the longer you use the string the worse the
+  # performance will get and the more memory you waste.
+  #
+  # {ByteBuffer} solves the problem by using two strings: one is the read
+  # 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.
+  class ByteBuffer
+    def initialize(initial_bytes='')
+      @read_buffer = ''
+      @write_buffer = ''
+      @offset = 0
+      @length = 0
+      append(initial_bytes) unless initial_bytes.empty?
+    end
+
+    # Returns the number of bytes in the buffer.
+    #
+    # The value is cached so this is a cheap operation.
+    attr_reader :length
+    alias_method :size, :length
+    alias_method :bytesize, :length
+
+    # Returns true when the number of bytes in the buffer is zero.
+    #
+    # The length is cached so this is a cheap operation.
+    def empty?
+      length == 0
+    end
+
+    # Append the bytes from a string or another byte buffer to this buffer.
+    #
+    # @note
+    #   When the bytes are not in an ASCII compatible encoding they are copied
+    #   and retagged as `Encoding::BINARY` before they are appended to the
+    #   buffer – this is required to avoid Ruby retagging the whole buffer with
+    #   the encoding of the new bytes. If you can, make sure that the data you
+    #   append is ASCII compatible (i.e. responds true to `#ascii_only?`),
+    #   otherwise you will pay a small penalty for each append due to the extra
+    #   copy that has to be made.
+    #
+    # @param [String, Ione::ByteBuffer] bytes the bytes to append
+    # @return [Ione::ByteBuffer] itself
+    def append(bytes)
+      if bytes.is_a?(self.class)
+        bytes.append_to(self)
+      else
+        bytes = bytes.to_s
+        unless bytes.ascii_only?
+          bytes = bytes.dup.force_encoding(::Encoding::BINARY)
+        end
+        retag = @write_buffer.empty?
+        @write_buffer << bytes
+        @write_buffer.force_encoding(::Encoding::BINARY) if retag
+        @length += bytes.bytesize
+      end
+      self
+    end
+    alias_method :<<, :append
+
+    # Remove the first N bytes from the buffer.
+    #
+    # @param [Integer] n the number of bytes to remove from the buffer
+    # @return [Ione::ByteBuffer] itself
+    # @raise RangeError when there are not enough bytes in the buffer
+    def discard(n)
+      raise RangeError, "#{n} bytes to discard but only #{@length} available" if @length < n
+      @offset += n
+      @length -= n
+      self
+    end
+
+    # Remove and return the first N bytes from the buffer.
+    #
+    # @param [Integer] n the number of bytes to remove and return from the buffer
+    # @return [String] a string with the bytes, the string will be tagged
+    #   with `Encoding::BINARY`.
+    # @raise RangeError when there are not enough bytes in the buffer
+    def read(n)
+      raise RangeError, "#{n} bytes required but only #{@length} available" if @length < n
+      if @offset >= @read_buffer.bytesize
+        swap_buffers
+      end
+      if @offset + n > @read_buffer.bytesize
+        s = read(@read_buffer.bytesize - @offset)
+        s << read(n - s.bytesize)
+        s
+      else
+        s = @read_buffer[@offset, n]
+        @offset += n
+        @length -= n
+        s
+      end
+    end
+
+    # Remove and return the first four bytes from the buffer and decode them as an unsigned integer.
+    #
+    # @return [Integer] the big-endian integer interpretation of the four bytes
+    # @raise RangeError when there are not enough bytes in the buffer
+    def read_int
+      raise RangeError, "4 bytes required to read an int, but only #{@length} available" if @length < 4
+      if @offset >= @read_buffer.bytesize
+        swap_buffers
+      end
+      if @read_buffer.bytesize >= @offset + 4
+        i0 = @read_buffer.getbyte(@offset + 0)
+        i1 = @read_buffer.getbyte(@offset + 1)
+        i2 = @read_buffer.getbyte(@offset + 2)
+        i3 = @read_buffer.getbyte(@offset + 3)
+        @offset += 4
+        @length -= 4
+      else
+        i0 = read_byte
+        i1 = read_byte
+        i2 = read_byte
+        i3 = read_byte
+      end
+      (i0 << 24) | (i1 << 16) | (i2 << 8) | i3
+    end
+
+    # Remove and return the first two bytes from the buffer and decode them as an unsigned integer.
+    #
+    # @return [Integer] the big-endian integer interpretation of the two bytes
+    # @raise RangeError when there are not enough bytes in the buffer
+    def read_short
+      raise RangeError, "2 bytes required to read a short, but only #{@length} available" if @length < 2
+      if @offset >= @read_buffer.bytesize
+        swap_buffers
+      end
+      if @read_buffer.bytesize >= @offset + 2
+        i0 = @read_buffer.getbyte(@offset + 0)
+        i1 = @read_buffer.getbyte(@offset + 1)
+        @offset += 2
+        @length -= 2
+      else
+        i0 = read_byte
+        i1 = read_byte
+      end
+      (i0 << 8) | i1
+    end
+
+    # Remove and return the first byte from the buffer and decode it as a signed or unsigned integer.
+    #
+    # @param [Boolean] signed whether or not to interpret the byte as a signed number of not
+    # @return [Integer] the integer interpretation of the byte
+    # @raise RangeError when the buffer is empty
+    def read_byte(signed=false)
+      raise RangeError, "No bytes available to read byte" if empty?
+      if @offset >= @read_buffer.bytesize
+        swap_buffers
+      end
+      b = @read_buffer.getbyte(@offset)
+      b = (b & 0x7f) - (b & 0x80) if signed
+      @offset += 1
+      @length -= 1
+      b
+    end
+
+    # Overwrite a portion of the buffer with new bytes.
+    #
+    # The number of bytes that will be replaced depend on the size of the
+    # replacement string. If you pass a five byte string the five bytes
+    # starting at the location will be replaced.
+    #
+    # When you pass more bytes than the size of the buffer after the location
+    # only as many as needed to replace the remaining bytes of the buffer will
+    # actually be used.
+    #
+    # Make sure that you get your location right, if you have discarded bytes
+    # from the buffer all of the offsets will have changed.
+    #
+    # @example replacing bytes in the middle of a buffer
+    #   buffer = ByteBuffer.new("hello world!")
+    #   bufferupdate(6, "fnord")
+    #   buffer # => "hello fnord!"
+    #
+    # @example replacing bytes at the end of the buffer
+    #   buffer = ByteBuffer.new("my name is Jim")
+    #   buffer.update(11, "Sammy")
+    #   buffer # => "my name is Sam"
+    #
+    # @param [Integer] location the starting location where the new bytes
+    #   should be inserted
+    # @param [String] bytes the replacement bytes
+    # @return [Ione::ByteBuffer] itself
+    def update(location, bytes)
+      absolute_offset = @offset + location
+      bytes_length = bytes.bytesize
+      if absolute_offset >= @read_buffer.bytesize
+        @write_buffer[absolute_offset - @read_buffer.bytesize, bytes_length] = bytes
+      else
+        overflow = absolute_offset + bytes_length - @read_buffer.bytesize
+        read_buffer_portion = bytes_length - overflow
+        @read_buffer[absolute_offset, read_buffer_portion] = bytes[0, read_buffer_portion]
+        if overflow > 0
+          @write_buffer[0, overflow] = bytes[read_buffer_portion, bytes_length - 1]
+        end
+      end
+      self
+    end
+
+    # Return as much of the buffer as possible without having to concatenate
+    # or allocate any unnecessary strings.
+    #
+    # If the buffer is not empty this method will return something, but there
+    # are no guarantees as to how much it will return. It's primarily useful
+    # in situations where a loop wants to offer some bytes but can't be sure
+    # how many will be accepted — for example when writing to a socket.
+    #
+    # @example feeding bytes to a socket
+    #   while true
+    #     _, writables, _ = IO.select(nil, sockets)
+    #     if writables
+    #       writables.each do |io|
+    #         n = io.write_nonblock(buffer.cheap_peek)
+    #         buffer.discard(n)
+    #       end
+    #     end
+    #
+    # @return [String] some bytes from the start of the buffer
+    def cheap_peek
+      if @offset >= @read_buffer.bytesize
+        swap_buffers
+      end
+      @read_buffer[@offset, @read_buffer.bytesize - @offset]
+    end
+
+    def eql?(other)
+      self.to_str.eql?(other.to_str)
+    end
+    alias_method :==, :eql?
+
+    def hash
+      to_str.hash
+    end
+
+    def dup
+      self.class.new(to_str)
+    end
+
+    def to_str
+      (@read_buffer + @write_buffer)[@offset, @length]
+    end
+    alias_method :to_s, :to_str
+
+    def inspect
+      %(#<#{self.class.name}: #{to_str.inspect}>)
+    end
+
+    protected
+
+    def append_to(other)
+      other.raw_append(cheap_peek)
+      other.raw_append(@write_buffer) unless @write_buffer.empty?
+    end
+
+    def raw_append(bytes)
+      @write_buffer << bytes
+      @length += bytes.bytesize
+    end
+
+    private
+
+    def swap_buffers
+      @offset -= @read_buffer.bytesize
+      @read_buffer = @write_buffer
+      @write_buffer = ''
+    end
+  end
+end

data/lib/ione/future.rb

@@ -0,0 +1,509 @@
+# encoding: utf-8
+
+require 'thread'
+
+
+module Ione
+  FutureError = Class.new(StandardError)
+
+  # A promise of delivering a value some time in the future.
+  #
+  # 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}.
+  class Promise
+    attr_reader :future
+
+    def initialize
+      @future = CompletableFuture.new
+    end
+
+    # Fulfills the promise.
+    #
+    # This will resolve this promise's future, and trigger all listeners of that
+    # future. The value of the future will be the specified value, or nil if
+    # no value is specified.
+    #
+    # @param [Object] value the value of the future
+    def fulfill(value=nil)
+      @future.resolve(value)
+    end
+
+    # Fails the promise.
+    #
+    # This will fail this promise's future, and trigger all listeners of that
+    # future.
+    #
+    # @param [Error] error the error which prevented the promise to be fulfilled
+    def fail(error)
+      @future.fail(error)
+    end
+
+    # Observe a future and fulfill the promise with the future's value when the
+    # future resolves, or fail with the future's error when the future fails.
+    #
+    # @param [Ione::Future] future the future to observe
+    def observe(future)
+      future.on_value { |v| fulfill(v) }
+      future.on_failure { |e| fail(e) }
+    end
+
+    # Run the given block and fulfill this promise with its result. If the block
+    # raises an error, fail this promise with the error.
+    #
+    # All arguments given will be passed onto the block.
+    #
+    # @example
+    #   promise.try { 3 + 4 }
+    #   promise.future.value # => 7
+    #
+    # @example
+    #   promise.try do
+    #     do_something_that_will_raise_an_error
+    #   end
+    #   promise.future.value # => (raises error)
+    #
+    # @example
+    #   promise.try('foo', 'bar', &proc_taking_two_arguments)
+    #
+    # @yieldparam [Array] ctx the arguments passed to {#try}
+    def try(*ctx)
+      fulfill(yield(*ctx))
+    rescue => e
+      fail(e)
+    end
+  end
+
+  module FutureFactories
+    # Combines multiple futures into a new future which resolves when all
+    # constituent futures complete, or fails when one or more of them fails.
+    #
+    # The value of the combined future is an array of the values of the
+    # constituent futures.
+    #
+    # @param [Array<Ione::Future>] futures the futures to combine
+    # @return [Ione::Future<Array>] an array of the values of the constituent
+    #   futures
+    def all(*futures)
+      return resolved([]) if futures.empty?
+      CombinedFuture.new(futures)
+    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).
+    #
+    # @param [Array<Ione::Future>] futures the futures to monitor
+    # @return [Ione::Future] a future which represents the first completing future
+    def first(*futures)
+      return resolved if futures.empty?
+      FirstFuture.new(futures)
+    end
+
+    # Creates a new pre-resolved future.
+    #
+    # @param [Object, nil] value the value of the created future
+    # @return [Ione::Future] a resolved future
+    def resolved(value=nil)
+      ResolvedFuture.new(value)
+    end
+
+    # Creates a new pre-failed future.
+    #
+    # @param [Error] error the error of the created future
+    # @return [Ione::Future] a failed future
+    def failed(error)
+      FailedFuture.new(error)
+    end
+  end
+
+  module FutureCombinators
+    # Returns a new future representing a transformation of this future's value.
+    #
+    # @example
+    #   future2 = future1.map { |value| value * 2 }
+    #
+    # @param [Object] value the value of this future (when no block is given)
+    # @yieldparam [Object] value the value of this future
+    # @yieldreturn [Object] the transformed value
+    # @return [Ione::Future] a new future representing the transformed value
+    def map(value=nil, &block)
+      CompletableFuture.new.tap do |f|
+        on_failure { |e| f.fail(e) }
+        on_value { |v| run(f, value, block, v) }
+      end
+    end
+
+    # Returns a new future representing a transformation of this future's value,
+    # but where the transformation itself may be asynchronous.
+    #
+    # @example
+    #   future2 = future1.flat_map { |value| method_returning_a_future(value) }
+    #
+    # This method is useful when you want to chain asynchronous operations.
+    #
+    # @yieldparam [Object] value the value of this future
+    # @yieldreturn [Ione::Future] a future representing the transformed value
+    # @return [Ione::Future] a new future representing the transformed value
+    def flat_map(&block)
+      CompletableFuture.new.tap do |f|
+        on_failure { |e| f.fail(e) }
+        on_value { |v| chain(f, block, v) }
+      end
+    end
+
+    # Returns a new future which represents either the value of the original
+    # future, or the result of the given block, if the original future fails.
+    #
+    # This method is similar to{#map}, but is triggered by a failure. You can
+    # also think of it as a `rescue` block for asynchronous operations.
+    #
+    # If the block raises an error a failed future with that error will be
+    # returned (this can be used to transform an error into another error,
+    # instead of tranforming an error into a value).
+    #
+    # @example
+    #   future2 = future1.recover { |error| 'foo' }
+    #   future1.fail(error)
+    #   future2.value # => 'foo'
+    #
+    # @param [Object] value the value when no block is given
+    # @yieldparam [Object] error the error from the original future
+    # @yieldreturn [Object] the value of the new future
+    # @return [Ione::Future] a new future representing a value recovered from the error
+    def recover(value=nil, &block)
+      CompletableFuture.new.tap do |f|
+        on_failure { |e| run(f, value, block, e) }
+        on_value { |v| f.resolve(v) }
+      end
+    end
+
+    # Returns a new future which represents either the value of the original
+    # future, or the value of the future returned by the given block.
+    #
+    # This is like {#recover} but for cases when the handling of an error is
+    # itself asynchronous. In other words, {#fallback} is to {#recover} what
+    # {#flat_map} is to {#map}.
+    #
+    # If the block raises an error a failed future with that error will be
+    # returned (this can be used to transform an error into another error,
+    # instead of tranforming an error into a value).
+    #
+    # @example
+    #   result = http_get('/foo/bar').fallback do |error|
+    #     http_get('/baz')
+    #   end
+    #   result.value # either the response to /foo/bar, or if that failed
+    #                # the response to /baz
+    #
+    # @yieldparam [Object] error the error from the original future
+    # @yieldreturn [Object] the value of the new future
+    # @return [Ione::Future] a new future representing a value recovered from the
+    #   error
+    def fallback(&block)
+      CompletableFuture.new.tap do |f|
+        on_failure { |e| chain(f, block, e) }
+        on_value { |v| f.resolve(v) }
+      end
+    end
+
+    private
+
+    def run(f, value, producer, arg)
+      value = producer ? producer.call(arg) : value
+      f.resolve(value)
+    rescue => e
+      f.fail(e)
+    end
+
+    def chain(f, constructor, arg)
+      ff = constructor.call(arg)
+      ff.on_failure { |e| f.fail(e) }
+      ff.on_value { |v| f.resolve(v) }
+    rescue => e
+      f.fail(e)
+    end
+  end
+
+  module FutureCallbacks
+    # Registers a listener that will be called when this future completes,
+    # i.e. resolves or fails. The listener will be called with the future as
+    # solve argument
+    #
+    # @yieldparam [Ione::Future] future the future
+    def on_complete(&listener)
+      run_immediately = false
+      @lock.synchronize do
+        if @resolved || @failed
+          run_immediately = true
+        else
+          @complete_listeners << listener
+        end
+      end
+      if run_immediately
+        listener.call(self) rescue nil
+      end
+      nil
+    end
+
+    # Registers a listener that will be called when this future becomes
+    # resolved. The listener will be called with the value of the future as
+    # sole argument.
+    #
+    # @yieldparam [Object] value the value of the resolved future
+    def on_value(&listener)
+      run_immediately = false
+      @lock.synchronize do
+        if @resolved
+          run_immediately = true
+        elsif !@failed
+          @value_listeners << listener
+        end
+      end
+      if run_immediately
+        listener.call(value) rescue nil
+      end
+      nil
+    end
+
+    # Registers a listener that will be called when this future fails. The
+    # lisener will be called with the error that failed the future as sole
+    # argument.
+    #
+    # @yieldparam [Error] error the error that failed the future
+    def on_failure(&listener)
+      run_immediately = false
+      @lock.synchronize do
+        if @failed
+          run_immediately = true
+        elsif !@resolved
+          @failure_listeners << listener
+        end
+      end
+      if run_immediately
+        listener.call(@error) rescue nil
+      end
+      nil
+    end
+  end
+
+  # A future represents the value of a process that may not yet have completed.
+  #
+  # @see Ione::Promise
+  class Future
+    extend FutureFactories
+    include FutureCombinators
+    include FutureCallbacks
+
+    def initialize
+      @lock = Mutex.new
+      @resolved = false
+      @failed = false
+      @failure_listeners = []
+      @value_listeners = []
+      @complete_listeners = []
+    end
+
+    # Returns the value of this future, blocking until it is available if
+    # necessary.
+    #
+    # If the future fails this method will raise the error that failed the
+    # future.
+    #
+    # @return [Object] the value of this future
+    def value
+      semaphore = nil
+      @lock.synchronize do
+        raise @error if @failed
+        return @value if @resolved
+        semaphore = Queue.new
+        u = proc { semaphore << :unblock }
+        @value_listeners << u
+        @failure_listeners << u
+      end
+      while true
+        @lock.synchronize do
+          raise @error if @failed
+          return @value if @resolved
+        end
+        semaphore.pop
+      end
+    end
+
+    # Returns true if this future is resolved or failed
+    def completed?
+      resolved? || failed?
+    end
+
+    # Returns true if this future is resolved
+    def resolved?
+      @lock.synchronize { @resolved }
+    end
+
+    # Returns true if this future has failed
+    def failed?
+      @lock.synchronize { @failed }
+    end
+  end
+
+  # @private
+  class CompletableFuture < Future
+    def resolve(v=nil)
+      value_listeners = nil
+      complete_listeners = nil
+      @lock.synchronize do
+        raise FutureError, 'Future already completed' if @resolved || @failed
+        @resolved = true
+        @value = v
+        value_listeners = @value_listeners
+        complete_listeners = @complete_listeners
+        @value_listeners = nil
+        @failure_listeners = nil
+        @complete_listeners = nil
+      end
+      value_listeners.each do |listener|
+        listener.call(v) rescue nil
+      end
+      complete_listeners.each do |listener|
+        listener.call(self) rescue nil
+      end
+      nil
+    end
+
+    def fail(error)
+      failure_listeners = nil
+      complete_listeners = nil
+      @lock.synchronize do
+        raise FutureError, 'Future already completed' if @failed || @resolved
+        @failed = true
+        @error = error
+        failure_listeners = @failure_listeners
+        complete_listeners = @complete_listeners
+        @value_listeners = nil
+        @failure_listeners = nil
+        @complete_listeners = nil
+      end
+      failure_listeners.each do |listener|
+        listener.call(error) rescue nil
+      end
+      complete_listeners.each do |listener|
+        listener.call(self) rescue nil
+      end
+      nil
+    end
+  end
+
+  # @private
+  class CombinedFuture < CompletableFuture
+    def initialize(futures)
+      super()
+      values = Array.new(futures.size)
+      remaining = futures.size
+      futures.each_with_index do |f, i|
+        f.on_value do |v|
+          @lock.synchronize do
+            values[i] = v
+            remaining -= 1
+          end
+          if remaining == 0
+            resolve(values)
+          end
+        end
+        f.on_failure do |e|
+          unless failed?
+            fail(e)
+          end
+        end
+      end
+    end
+  end
+
+  # @private
+  class FirstFuture < CompletableFuture
+    def initialize(futures)
+      super()
+      futures.each do |f|
+        f.on_value do |value|
+          resolve(value) unless completed?
+        end
+        f.on_failure do |e|
+          fail(e) if futures.all?(&:failed?)
+        end
+      end
+    end
+  end
+
+  # @private
+  class ResolvedFuture < Future
+    def initialize(value=nil)
+      @resolved = true
+      @failed = false
+      @value = value
+      @error = nil
+    end
+
+    def value
+      @value
+    end
+
+    def completed?
+      true
+    end
+
+    def resolved?
+      true
+    end
+
+    def failed?
+      false
+    end
+
+    def on_complete(&listener)
+      listener.call(self) rescue nil
+    end
+
+    def on_value(&listener)
+      listener.call(value) rescue nil
+    end
+
+    def on_failure
+    end
+  end
+
+  # @private
+  class FailedFuture < Future
+    def initialize(error)
+      @resolved = false
+      @failed = true
+      @value = nil
+      @error = error
+    end
+
+    def value
+      raise @error
+    end
+
+    def completed?
+      true
+    end
+
+    def resolved?
+      false
+    end
+
+    def failed?
+      true
+    end
+
+    def on_complete(&listener)
+      listener.call(self) rescue nil
+    end
+
+    def on_value
+    end
+
+    def on_failure(&listener)
+      listener.call(@error) rescue nil
+    end
+  end
+end