futuristic 0.4.3

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NTJmNzk2OThkYzJiMzQ0ZDZmYjJjMGYyODE4ZTVjNWQ1NWNkYjhjOQ==
+  data.tar.gz: !binary |-
+    N2IzMTc1NGEzYzI0NzQ0NmY5ZTNkMjlkZjM3YzIzZTM2OTgyNjRmMg==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    ODQ1NjZhODc4MzZiOTQ3ZTQwOWMyNTQ2ZjQ5YjUxYzE0NjVjZmNlY2UzZDk4
+    ZTgwZGFiOGQ4NjBhMGM3ZDg2ZjIzNmMwZTUxNmU5Mjc5ZjVlMTdjN2YzYzE3
+    MDJjNzY5NWU3NWU2ZGQ1NjRhYjkzOTcyMDIzOWZkNzlmMzA3ZmU=
+  data.tar.gz: !binary |-
+    NWUxNzYxYjQ5YzExMDAyOTk1NDE1MGFkZDcyMjVlYjdjMzRjNDNlMGMyODU1
+    NTk2NGQ1YjI3OTQ5MTQ5NmYxMGY3OTJmNTZkYTkzZDY0NjI3ZTk0Nzg2ODgz
+    NDMzYmRhYzNiNTcyZmM3MzIwNjY0ZDQ0NWYyMzNhOTUyNjE0ODI=

data/README.md

@@ -0,0 +1,96 @@
+#Futures and Promises
+This is a rubymotion implementation of the Futures and Promise pattern, on top of Grand Central [Dispatch](https://github.com/MacRuby/MacRuby/wiki/Dispatch-Module).
+
+##What are Future and Promises?
+
+> In computer science, future, promise, and delay refer to constructs used for 
+> synchronizing in some concurrent programming languages. They describe an object 
+> that acts as a proxy for a result that is initially unknown, usually because the 
+> computation of its value is yet incomplete<[source Wikipedia](http://en.wikipedia.org/wiki/Futures_and_promises)>.
+
+
+##Futures and Promises
+are objects holding a value which may become available at some point. This value is usually the result of some other computation. Since this computation may fail with an exception, the Future/Promise may also hold an exception in case the computation throws one.
+
+#Usage:
+in your Gem file
+
+```ruby
+gem 'futuristic', :git => 'git://github.com/seanlilmateus/futuristic.git'
+
+```
+###how to use Promises
+```ruby
+def fibonacci(n)
+  return n if n < 2
+  fib1 = Dispatch::Promise.new { fibonacci(n-1) }
+  fib2 = Dispatch::Promise.new { fibonacci(n-2) }
+  fib1 + fib2
+end
+
+p fibonacci(10) # => 55
+```
+
+###how to use Futures
+
+```ruby
+# computation is started
+future_data = Dispatch::Future.new do
+	bundle	= NSBundle.mainBundle
+	plist_path = bundle.pathForResource("map", ofType: "plist")
+	@map_data = load_plist(File.read(plist_path))
+end
+
+# you can do something else
+@table = create_table_named("Future Maps")
+
+puts "Hello World"
+
+@table.data = future_data.value # if the computation is done, results with be immediatelly returned, if not done yet it will wait.
+```
+
+###Futures using callback
+```ruby
+# computation is started
+future_data = Dispatch::Future.new do
+	bundle	= NSBundle.mainBundle
+	plist_path = bundle.pathForResource("map", ofType: "plist")
+	@map_data = load_plist(File.read(plist_path))
+end
+
+# you can do something else
+@table = create_table_named("Future Maps")
+
+future_data.when_done do |value|
+	# when the computation is done, table data will be setted on the Future Queue
+	# the call back is not executed on the MainQueue/Dispatch::Queue.main
+	@table.data = future_data.value
+end
+```
+
+###Module Futuristic
+```ruby
+class Request
+  include Dispatch::Futuristic
+  def long_taking_computation
+  	sleep 10
+  	42
+  end
+end
+
+request = Request.new
+computation = request.future.long_taking_computation
+
+#you can do something else while the computation is been executed on a background queue
+puts "Drink some Kölsch"
+
+# now you need the result, if it's already finished
+# you will ge the result, otherwise it will wait untill the computation finish
+p computation.value  # =>  42
+```
+
+#Todo
+- Parallel Enumerable 
+- Actor models
+- documentation and examples
+

data/futuristic.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'futuristic/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'futuristic'
+  gem.version       = Futuristic::VERSION
+  gem.date          = '2013-03-21'
+  gem.summary       = %q{Rubymotion Promise and Futures}
+  gem.description   = %q{Rubymotion Promise and Futures helper on top of Grand Central Dispatch}
+  gem.authors       = ["Mateus Armando"]
+  gem.email         = 'seanlilmateus@yahoo.de'
+  gem.files         = ["lib/futuristic.rb"]
+  gem.homepage      = 'http://github.com/seanlilmateus/futuristic'
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+end

data/lib/futuristic.rb

@@ -0,0 +1,9 @@
+unless defined?(Motion::Project::Config)
+  raise "This file must be required within a RubyMotion project Rakefile."
+end
+
+Motion::Project::App.setup do |app|
+  Dir.glob(File.join(File.dirname(__FILE__), 'futuristic/**/*.rb')).each do |file|
+    app.files.unshift(file)
+  end
+end

data/lib/futuristic/dispatch/future.rb

@@ -0,0 +1,56 @@
+# Future
+# actually future acts just like a Promise,
+# the only difference is that they are not lazy
+module Dispatch
+  class Future < Promise
+    # Create s new Future
+    #
+    # Example:
+    #   >> future = Dispatch::Future.new { long_taking_task; 10 }
+    #   => future.value # 10
+    # Arguments
+    #    block, last
+    def self.new(&block)
+      # MacRuby and Rubymotion BasicObject#initialize doesn't like blocks, so we have to do this
+      # new :: a -> Eval (Future a)
+      unless block_given?
+        ::Kernel.raise(::ArgumentError, "You cannot initalize a Dispatch::Future without a block")
+      end
+      self.alloc.initialization(block)
+    end
+
+
+    def when_done(&call_back)
+      @group.notify(@promise_queue) { call_back.call __value__ }
+      self
+    end
+
+
+    def initialization(block)
+      super(block)
+      __force__
+      self
+    end
+
+    #
+    # Future#description
+    # => <Future: 0x400d382a0 run> 
+    #
+    def description
+      state = done? ? :dead : :run
+      NSString.stringWithString(super.gsub(/>/, " #{state}>"))
+    end
+    alias_method :to_s, :description
+    alias_method :inspect, :description
+
+
+    def done?
+      !!@value
+    end
+
+
+    def value
+      __value__
+    end
+  end
+end

data/lib/futuristic/dispatch/promise.rb

@@ -0,0 +1,73 @@
+module Dispatch
+  class Promise < BasicObject
+    # new :: Promise a -> Eval a
+    # MacRuby and Rubymotion BasicObject#initialize doesn't like blocks, so we have to do this
+    def self.new(&block)
+      unless block_given?
+        ::Kernel.raise(::ArgumentError, "You cannot initalize a Dispatch::Promise without a block")
+      end
+      self.alloc.initialization(block)
+    end
+
+
+    # setup Grand Central Dispatch concurrent Queue and Group
+    def initialization(block)
+      init
+      @computation = block
+      # Groups are just simple layers on top of semaphores.
+      @group = ::Dispatch::Group.new
+      # Each thread gets its own FIFO queue upon which we will dispatch
+      # the delayed computation passed in the &block variable.
+      @promise_queue = ::Dispatch::Queue.concurrent("org.macruby.#{self.class}-0x#{hash.to_s(16)}") #
+      self
+    end
+
+
+    def inspect
+      __value__.inspect
+    end
+
+
+    private
+    # Asynchronously dispatch the future to the thread-local queue.
+    def __force__
+      @running = true # should only be initiliazed once
+      @promise_queue.async(@group) do
+        begin
+          @value = @computation.call
+        rescue ::Exception => e
+          @exception = e
+        end
+      end
+    end
+
+
+    # Wait fo the computation to finish. If it has already finished, then
+    # just return the value in question.
+    def __value__
+      __force__ unless @running
+      @group.wait
+      ::Kernel.raise(@exception) if @exception
+      @value
+    end
+
+
+    # like method_missing for objc
+    # without this 'promise = Dispatch::Promise.new { NSData.dataWithContentsOfFile(file_name) }' will not work
+    # NSString.alloc.initWithData(promise, encoding:NSUTF8StringEncoding)
+    # since promise will not respond to NSData#bytes and return a NSInvalidArgumentException
+    def method_missing(meth, *args, &block)
+      __value__.send(meth, *args, &block)
+    end
+
+
+    def respond_to_missing?(method_name, include_private = false)
+      __value__.respond_to?(method_name, include_private) || super
+    end
+
+
+    def forwardingTargetForSelector(sel)
+      __value__ if __value__.respond_to?(sel)
+    end
+  end
+end

data/lib/futuristic/futuristic.rb

@@ -0,0 +1,19 @@
+# Futuristic
+module Futuristic
+  def future
+    proxy = Class.new(BasicObject) do
+      def initialize(obj)
+        @object = obj
+      end
+      
+      def method_missing(meth, *args, &blk)
+        Dispatch::Future.new { @object.send(meth, *args, &blk) }
+      end
+      
+      def respond_to_missing?(meth, include_private = false)
+        @object.respond_to?(meth) || super
+      end
+    end
+    proxy.new(self)
+  end
+end

data/lib/futuristic/version.rb

@@ -0,0 +1,3 @@
+module Futuristic
+  VERSION = "0.4.3"
+end

data/spec/future_spec.rb

@@ -0,0 +1,25 @@
+describe Dispatch::Future do
+
+  before { @method = Kernel.method(:future) }
+  
+  it "should inherit from BasicObject if available, and not otherwise" do
+    Dispatch::Future.ancestors.should.include BasicObject
+  end
+  
+  # behaves_like "A Promise"
+  
+  def range_of(range)
+     lambda { |obj| range.include?(obj) }
+  end
+    
+  it "should work in the background" do
+    start = Time.now
+    x = future { sleep 3; 5 }
+    middle = Time.now
+    y = x.value + 5
+    y.should == 10
+    finish = Time.now
+    (middle - start).should.be range_of(0.0..1.0)
+    (finish - start).should.be range_of(3.0..3.9)    
+  end
+end

data/spec/promise_spec.rb

@@ -0,0 +1,25 @@
+describe Dispatch::Promise do
+  before do
+    @method = Kernel.method(:promise)
+  end
+
+  it "should inherit from BasicObject if available, and not otherwise" do
+    Dispatch::Promise.ancestors.should.include BasicObject
+  end
+
+  behaves_like "A Promise"
+
+  it "should delay execution" do
+    value = 5
+    x = @method.call { value = 10 ; value }
+    value.should == 5
+    y = x + 5
+    y.should == 15
+    value.should == 10
+  end
+
+  it "should delay execution of invalid code" do
+    lambda { 1 / 0 }.should.raise(ZeroDivisionError).message.should.match(/divided by 0/)
+    lambda { x = [ 1, @method.call { x / 0 }]}.should.not.raise(ZeroDivisionError)
+  end
+end

data/spec/shared_spec.rb

@@ -0,0 +1,109 @@
+shared "A Promise" do
+  it "should be createable" do
+    lambda { x = @method.call { 3 + 5 } }.should.not.raise(Exception)
+  end
+
+  it "should accept a block requiring arguments" do
+    lambda { x = @method.call { |x| 3 + 5 }}.should.not.raise(Exception)
+  end
+
+  it "should be forceable" do
+    x = @method.call { 3 + 5 }
+    x.to_i.should == 8
+    x.should == 8
+  end
+
+  it "should respond_to? a method on the result" do
+    x = @method.call { 3 + 5 }
+    x.respond_to?(:+).should == true
+  end
+
+  it "should not respond_to? a method not on the result" do
+    x = @method.call { 3 + 5 }
+    x.respond_to?(:asdf).should == false
+  end
+
+  it "should evaluate to a value" do
+    (5 + @method.call { 1 + 2 }).should == 8
+  end
+
+  it "should hold its value" do
+    y = 5
+    x = @method.call { y = y + 5 }
+    x.should == 10
+    x.should == 10
+  end
+
+  it "should only execute once" do
+    y = 1
+    x = @method.call { (y += 1) && false }
+    x.should == false
+    x.should == false
+    y.should == 2
+  end
+
+  it "should raise exceptions raised during execution when accessed" do
+    y = Object.new
+    y = @method.call { 1 / 0 }
+    lambda { y.inspect }.should.raise(ZeroDivisionError)
+    lambda { y.inspect }.should.raise(ZeroDivisionError)
+  end
+
+  it "should only execute once when execptions are raised" do
+    y = 1
+    x = @method.call { (y += 1) ; (1 / 0) }
+    lambda { x.inspect }.should.raise(ZeroDivisionError)
+    lambda { x.inspect }.should.raise(ZeroDivisionError)
+    y.should == 2
+  end
+
+  it "should remain the same for an object reference" do
+    h = {}
+    x = Object.new
+    h[:test] = @method.call { x }
+    h[:test].should == x
+  end
+
+  it "should be eql? for results" do
+    x = Object.new
+    y = @method.call { x }
+    y.should.equal x
+    # this would be ideal, but it can't be done in Ruby.  result
+    # objects that have a redefined #eql? should do fine.  
+    #x.should eql y
+  end
+
+  it "should be equal? for results" do
+    x = Object.new
+    y = @method.call { x }
+    y.should.equal x
+    # this would be ideal, but it can't be done in Ruby.
+    #x.should equal y
+  end
+  
+
+  
+  it "should be thread safe" do
+    x = @method.call { res = 1; 3.times { res = res * 5 ; sleep 1 } ; res }
+    results = []
+    changeds = []
+    changed = false
+    Dispatch::Queue.new('future.rspec').apply(10) do |idx|
+       res = old_res = 125
+       res = x + 5
+       results[idx] = res
+       changed != (res == old_res || idx == 0)
+       changeds[idx] = changed
+    end
+    
+    results.each do |result|
+      result.should == 130
+    end
+    
+    changeds.each do |changed|
+      changed.should == false
+    end
+    
+    changeds.size.should == 10
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: futuristic
+version: !ruby/object:Gem::Version
+  version: 0.4.3
+platform: ruby
+authors:
+- Mateus Armando
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-03-21 00:00:00.000000000 Z
+dependencies: []
+description: Rubymotion Promise and Futures helper on top of Grand Central Dispatch
+email: seanlilmateus@yahoo.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- futuristic.gemspec
+- lib/futuristic.rb
+- lib/futuristic/dispatch/future.rb
+- lib/futuristic/dispatch/promise.rb
+- lib/futuristic/futuristic.rb
+- lib/futuristic/version.rb
+- spec/future_spec.rb
+- spec/promise_spec.rb
+- spec/shared_spec.rb
+homepage: http://github.com/seanlilmateus/futuristic
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Rubymotion Promise and Futures
+test_files:
+- spec/future_spec.rb
+- spec/promise_spec.rb
+- spec/shared_spec.rb