promise 0.1.1 → 0.2.0

data/README

@@ -1,26 +1,27 @@
 # Promising Future
-A glimpse of a promising future in which ruby supports delayed execution
+A glimpse of a promising future in which Ruby supports lazy evaluation.
 
 ## Overview
+[Promises and futures][] both transparently defer the execution of a block.
+Promises evaluate the given block if and when its result is first needed.
+Futures evaluate the given block optimistically in another thread.
 
     require 'promise'
-    require 'future'    # you can just require future if using both
-
+    require 'future'    # you can just require 'future' if using both
+    
     x = promise { 1 + 2 }
-    y = future  { sleep 10; 5 + 5 }
-
-    puts x      # => 3
-    # ... do work for 5 seconds
-    puts y      # => 10, after blocking 5 seconds
-
-Promises and futures both transparantly delay the execution of a block.
-Futures run the evaluation of the block optimistically in another thread.
+    y = future  { sleep 10 && 6 * 7 }
+    
+    puts x      #=> 3
+    sleep 5     # ... do work for 5 seconds ...
+    puts y      #=> 42, after blocking 5 seconds
 
-Note that this is pretty useless in irb, which will evaluate everything
-as part of its read-eval-print loop.
+Note that this is pretty useless in Ruby's interactive shell `irb`, as it
+will eagerly evaluate everything as part of its read-eval-print loop,
+forcing promises and futures to yield their results.
 
-Yardocs are available at <http://promise.rubyforge.org/>.  Tested under MRI 
-1.8 and JRuby.
+The library has been tested with Ruby 1.8.7, 1.9.1 and JRuby 1.5.0.
+YARD documentation is available at <http://promise.rubyforge.org/>
 
 ## Classes
 
@@ -28,17 +29,18 @@ Yardocs are available at <http://promise.rubyforge.org/>.  Tested under MRI
  * {Future}
 
 ## Installation
+The library is distributed via [RubyGems](http://rubygems.org/):
 
-Promising future is distributed via gemcutter under the name 'promise'.
-
-    gem install promise
+    $ gem install promise
 
 ## Source
 The source is available at <http://github.com/bhuga/promising-future>
 
 ## Author
-Ben Lavender (http://github.com/bhuga)
+[Ben Lavender](http://github.com/bhuga)
 
 ## Unlicense
 Promising Future is free and unencumbered public domain software. For more
 information, see <http://unlicense.org/> or the accompanying UNLICENSE file.
+
+[Promises and futures]: http://en.wikipedia.org/wiki/Futures_and_promises

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/lib/future.rb

@@ -6,13 +6,15 @@ require 'promise'
 #     x = future { sleep 5; 1 + 2 }
 #     # do stuff...
 #     y = x * 2     # => 6.  blocks unless 5 seconds has passed.
-# 
+#
 class Future < defined?(BasicObject) ? BasicObject : Object
 
-  instance_methods.each { |m| undef_method m unless m =~ /__|object_id/ } unless defined?(BasicObject)
-  
+  instance_methods.each { |m| undef_method m unless m =~ /__/ } unless defined?(BasicObject)
+
   ##
-  # @param [Proc] block
+  # Create a new future
+  #
+  # @yield [] The block to evaluate optimistically
   # @return [Future]
   def initialize(block)
     @promise = promise &block
@@ -23,15 +25,26 @@ class Future < defined?(BasicObject) ? BasicObject : Object
 
   ##
   # The value of the future's evaluation.  Blocks until result available.
+  #
   # @return [Any]
-  def force
+  def __force__
     @thread.join
     @promise
   end
+  alias_method :force, :__force__
+
+  ##
+  # Does this promise support the given method?
+  #
+  # @param  [Symbol]
+  # @return [true, false]
+  def respond_to?(method)
+    (method == :force) || (method == :__force__) || (__force__.respond_to?(method))
+  end
 
   # @private
   def method_missing(method, *args, &block)
-    @promise.send(method, *args, &block) 
+    @promise.send(method, *args, &block)
   end
 
 
@@ -40,9 +53,13 @@ end
 
 module Kernel
 
-  # Create a new future 
-  # @example
+  # Create a new future
+  #
+  # @example Evaluate an operation in another thread
   #     x = future { 3 + 3 }
+  # @return       [Future]
+  # @yield        [] A block to be optimistically evaluated in another thread
+  # @yieldreturn  [Any] The return value of the block will be the evaluated value of the future. 
   def future(&block)
     Future.new(block)
   end

data/lib/promise.rb

@@ -11,43 +11,73 @@
 #     x = promise { y = y + 5 }
 #     x + 5     # => 15
 #     x + 5     # => 15
-class Promise < defined?(BasicObject) ? BasicObject : Object
+class Promise < defined?(BasicObject) ? BasicObject : ::Object
 
-  instance_methods.each { |m| undef_method m unless m =~ /__|object_id/ } unless defined?(BasicObject)
+  instance_methods.each { |m| undef_method m unless m.to_s =~ /__/ }
 
-  # Returns a new promise
+  NOT_SET = ::Object.new.freeze
+
+  ##
+  # Create a new promise
+  #
+  # @example Lazily evaluate a database call
+  #     result = promise { @db.query("SELECT * FROM TABLE") }
   # @param [Proc] block
   # @return [Promise]
+  # @see Kernel#promise
   def initialize(block)
     if block.arity > 0
       raise ArgumentError, "Cannot store a promise that requires an argument"
     end
     @block = block
     @mutex = ::Mutex.new
+    @result = NOT_SET
+    @error  = NOT_SET
   end
 
+  ##
   # Force the evaluation of this promise immediately
+  #
   # @return [Any]
-  def force
-    @mutex.synchronize do 
-      unless @result
-        @result = @block.call
+  def __force__
+    @mutex.synchronize do
+      if @result == NOT_SET && @error == NOT_SET
+        begin
+          @result = @block.call
+        rescue ::Exception => e
+          @error = e
+        end
       end
-    end
-    @result
+    end if @result == NOT_SET && @error == NOT_SET
+    # BasicObject won't send raise to Kernel
+    @error.equal?(NOT_SET) ? @result : (::Kernel.raise @error)
+  end
+  alias_method :force, :__force__
+
+  ##
+  # Does this promise support the given method?
+  #
+  # @param  [Symbol]
+  # @return [true, false]
+  def respond_to?(method)
+    (method == :force) || (method == :__force__) || (__force__.respond_to?(method))
   end
 
   def method_missing(method, *args, &block)
-    force unless @result
+    __force__
     @result.send(method, *args, &block)
   end
 end
 
 module Kernel
-  
+
   # Create a new promise
-  # @example
+  #
+  # @example Lazily evaluate an arithmetic operation
   #     x = promise { 3 + 3 }
+  # @return       [Promise]
+  # @yield        [] A block to be lazily evaluated
+  # @yieldreturn  [Any] The return value of the block will be the lazily evaluated value of the promise. 
   def promise(&block)
     Promise.new(block)
   end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 1
-  version: 0.1.1
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Ben Lavender
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-06-04 00:00:00 +02:00
+date: 2010-06-22 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -26,9 +26,9 @@ dependencies:
       - !ruby/object:Gem::Version 
         segments: 
         - 1
-        - 2
-        - 9
-        version: 1.2.9
+        - 3
+        - 0
+        version: 1.3.0
   type: :development
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
@@ -41,11 +41,11 @@ dependencies:
         segments: 
         - 0
         - 5
-        - 2
-        version: 0.5.2
+        - 6
+        version: 0.5.6
   type: :development
   version_requirements: *id002
-description: "    A glimpse into a promising future, in which ruby supports delayed execution.\n    Provides 'promise' and 'future' functions.\n"
+description: "    A glimpse of a promising future in which Ruby supports delayed execution.\n    Provides global 'promise' and 'future' methods.\n"
 email: blavender@gmail.com
 executables: []