visionary 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b1f7a3de513614103461d8bc5cad045a30ef2bba
-  data.tar.gz: dca2eb952d375daa3a7a5b16b4fa134f6693e0a4
+  metadata.gz: 106d4aff2ec2c6f186337b10357075980c005983
+  data.tar.gz: 6d322855f784a1e6fbb98e71e71c50153e9e45dd
 SHA512:
-  metadata.gz: 391f4a2bf74059462dac270bba16d62edc5819e0f2c922532fac4a53209da9f26b6bbc4afcc269c67484a743d8992b3843edced5c0407952cf0539a0a6d730d1
-  data.tar.gz: 6a0aa4c2fd6316f1d486f6b989f0ddbf8654601de14cd14cd0ee1f25bb40cc786592a5b804210d4e1441ef886466e8b07721862279c240560b0676101f748026
+  metadata.gz: bbae37b484f2fa46352527c067f0568054ae720eb64d22cb4805cbaa3fd50a3a44ac145f0b3031b9f64e4f7e78bd5ea7a39a1f0ef51a569ff6e0525939c17561
+  data.tar.gz: 8b86917eab4a30c9b28766499ae527c4dba05d92e0dfcf816d7c94409bf489b13fda20619d34107d3728773932b26571ac8b8a63a89b5550b6e19e8e9cb08bd8

data/.rspec

@@ -1,2 +1,3 @@
+--require spec_helper
 --format documentation
 --color

data/README.md

@@ -1,6 +1,6 @@
 # Visionary
 
-TODO: Write a gem description
+Simple futures implementation in ruby.
 
 ## Installation
 
@@ -18,11 +18,189 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Enabling `future` and `promise` helpers
+
+```ruby
+Visionary.setup!
+```
+
+### Futures
+
+#### Deferring computation
+
+Use `Kernel#future(&blk)` to define future and run it immediately:
+
+```ruby
+future { do_some_hard_work(some: :data) }
+```
+
+it is an alternative to:
+
+```ruby
+Visionary::Future.new { do_some_hard_work(some: :data) }.run
+```
+
+#### Checking the status of computation
+
+You can check the status of computation inside of future by using `#state`:
+
+```ruby
+hard_work = future { do_some_hard_work(some: :data) }
+hard_work.state     # => :pending
+sleep(5.0)
+hard_work.state     # => :completed
+```
+
+It can have 3 values: `:pending`, `:completed` and `:failed`.
+
+#### Getting the result of computation
+
+Once future has a state of `:completed`, it will hold the result of computation in `#value`:
+
+```ruby
+hard_work = future { do_some_hard_work(some: :data) }
+do_something_else
+hard_work.value     # => 42
+```
+
+When the future is completed it becomes `frozen`:
+
+```ruby
+hard_work.state     # => :completed
+hard_work.frozen?   # => true
+hard_work.run       # raises RuntimeError: can't modify frozen Visionary::Future
+```
+
+#### Explicitly awaiting for result with blocking
+
+To block execution of until future is completed, you can use `#await` method on future:
+
+```ruby
+hard_work = future { do_some_hard_work(some: :data) }
+hard_work.await
+hard_work.state     # => :completed
+```
+
+#### Failed computations
+
+```ruby
+hard_work = future { raise RuntimeError }
+hard_work.await
+hard_work.state     # => :failed
+hard_work.error     # => #<RuntimeError: RuntimeError>
+```
+
+#### Awaiting for result without blocking
+
+To await for computation to complete and do something else after that without blocking use `#then` method on future:
+
+```ruby
+hard_work = future { do_some_hard_work(some: :data) }
+easy_task = hard_work.then { |result| make_it_awesome(result) }
+easy_task           # => #<Visionary::Future:0x0000012345678 @block=...>
+do_something_else
+easy_task.value     # => "awesome 42"
+```
+
+Under the hood it creates another future that will be run when current future is completed.
+
+When previous future have failed, the failure will propagate to all waiting futures:
+
+```ruby
+hard_work = future { do_some_hard_work_and_loudly_fail! }
+easy_task = hard_work.then { |result| make_it_awesome(result) }
+easy_task.await
+hard_work.state                         # => :failed
+easy_task.state                         # => :failed
+easy_task.error == hard_work.error      # => true
+```
+
+### Promises
+
+#### Creating a promise
+
+You could use `Kernel#promise` or `Visionary::Promise.new`. They are the same:
+
+```ruby
+p = promise                     # => #<Visionary::Promise:0x0000012345678>
+p2 = Visionary::Promise.new     # => #<Visionary::Promise:0x0000012345679>
+```
+
+#### Obtaining a promised future
+
+```ruby
+p = promise
+p.future    # => #<Visionary::Future:0x0000012345678 @block=nil, @state=:pending>
+```
+
+#### Completing a promised future
+
+```ruby
+def hard_working_task
+  p = promise
+  
+  call_some_external_api(
+    success_callback: -> { |value| p.complete(value) }
+  )
+  
+  p
+end
+```
+
+Promised future can be used as normal future:
+
+```ruby
+answer = hard_working_task
+
+answer.state    # => :pending
+
+do_something_else
+
+answer.state    # => :completed
+answer.value    # => 42
+```
+
+#### Failing a promised future
+
+```ruby
+def hard_working_task_often_fails
+  p = promise
+  
+  call_some_faulty_external_api(
+    success_callback: -> { ... }
+    failure_callback: -> { |error| p.fail(error) }
+  )
+  
+  p
+end
+```
+
+#### Complex example what it can be used for
+
+```ruby
+def gather_data_from_multiple_sources(user_name)
+  promises = {
+    user: promise,
+    friends: promise,
+    likes: promise
+  }
+  
+  user_call = future { api_call(:fetch_user, user_name) }
+  user_call.then { |user| promises[:user].complete(user) }
+  
+  friends_call = user_call.then { |user| api_call(:fetch_friends, user) }
+  friends_call.then { |friends| promises[:friends].complete(friends) }
+  
+  likes_call = user_call.then { |user| api_call(:fetch_likes, user) }
+  likes_call.then { |likes| promises[:likes].complete(likes) }
+  
+  promises.inject({}) { |acc, kv| acc.merge kv[0] => kv[1].future }
+end
+```
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/visionary/fork )
+1. Fork it ( https://github.com/waterlink/visionary/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/lib/visionary.rb

@@ -1,5 +1,10 @@
 require "visionary/version"
+require "visionary/future"
+require "visionary/promise"
 
 module Visionary
-  # Your code goes here...
+  def self.setup!
+    Future.setup!
+    Promise.setup!
+  end
 end

data/lib/visionary/future.rb

@@ -0,0 +1,94 @@
+module Visionary
+  class Future
+
+    class << self
+      def setup!
+        unless setted_up
+          Kernel.send :define_method, :future do |&blk|
+            Future.new(&blk).run
+          end
+          self.setted_up = true
+        end
+      end
+
+      private
+
+      attr_accessor :setted_up
+    end
+
+    attr_reader :state, :error, :value
+
+    def initialize(&blk)
+      @block = blk
+      self.state = :pending
+    end
+
+    def run
+      raise RuntimeError, "This future have been already started" if thread
+      @thread = Thread.new { run! }
+      self
+    end
+
+    def then(&blk)
+      fut = Future.new { blk.call(value) }
+      fut.waiting_for = self
+
+      case state
+      when :pending
+        callbacks << fut
+      when :completed
+        fut.run
+      when :failed
+        fut.fail_with(error)
+      end
+
+      fut
+    end
+
+    def await
+      waiting_for && waiting_for.await
+
+      unless thread
+        run
+      end
+
+      thread.join
+    end
+
+    protected
+
+    attr_accessor :waiting_for
+
+    def complete_with(value)
+      @value = value
+      @state = :completed
+      callbacks.each { |callback| callback.run }
+    ensure
+      freeze
+    end
+
+    def fail_with(error)
+      @error = error
+      @state = :failed
+      callbacks.each { |callback| callback.fail_with(error) }
+    ensure
+      freeze
+    end
+
+    private
+
+    attr_writer :state
+    attr_reader :block, :thread
+
+    def run!
+      complete_with(block.call)
+    rescue => e
+      fail_with(e)
+    end
+
+    def callbacks
+      @callbacks ||= []
+    end
+
+  end
+end

data/lib/visionary/promise.rb

@@ -0,0 +1,34 @@
+module Visionary
+  class Promise
+
+    class << self
+      def setup!
+        unless setted_up
+          Kernel.send :define_method, :promise do
+            Promise.new
+          end
+          self.setted_up = true
+        end
+      end
+
+      private
+
+      attr_accessor :setted_up
+    end
+
+    def future
+      @future ||= Future.new
+    end
+
+    def complete(computed_value)
+      future.instance_eval { complete_with(computed_value) }
+      freeze
+    end
+
+    def fail(provided_error)
+      future.instance_eval { fail_with(provided_error) }
+      freeze
+    end
+
+  end
+end

data/lib/visionary/version.rb

@@ -1,3 +1,3 @@
 module Visionary
-  VERSION = "0.0.1"
+  VERSION = "0.2.0"
 end

data/spec/spec_helper.rb

@@ -1,2 +1,4 @@
 $LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
 require 'visionary'
+
+Visionary.setup!

data/spec/visionary/future_spec.rb

@@ -0,0 +1,256 @@
+module Visionary
+  RSpec.describe Future do
+
+    describe "Kernel#future" do
+      it "delegates to Future.new and chains with run" do
+        fut = double("Future")
+        block = -> { :i_am_a_block }
+
+        allow(Future).to receive(:new).with(no_args) do |&blk|
+          if blk == block
+            fut
+          else
+            nil
+          end
+        end
+
+        expect(fut).to receive(:run)
+
+        future(&block)
+      end
+    end
+
+    describe "#state" do
+      it "is :pending when future is still computing the result" do
+        fut = future { do_something; 42 }
+
+        expect(fut.state).to eq(:pending)
+      end
+
+      it "is :failed when future failed to compute the result" do
+        fut = future { raise RuntimeError }
+
+        do_something
+
+        expect(fut.state).to eq(:failed)
+      end
+
+      it "is :completed when future managed to compute the result" do
+        fut = future { 42 }
+
+        do_something
+
+        expect(fut.state).to eq(:completed)
+      end
+    end
+
+    describe "#frozen?" do
+      it "is true when future is completed" do
+        fut = future { 42 }
+
+        do_something
+
+        expect(fut.frozen?).to eq(true)
+      end
+
+      it "is true when future is failed" do
+        fut = future { raise RuntimeError }
+
+        do_something
+
+        expect(fut.frozen?).to eq(true)
+      end
+
+      it "is false when future is pending" do
+        fut = future { do_something; 42 }
+
+        expect(fut.frozen?).to eq(false)
+      end
+    end
+
+    describe "#value" do
+      it "contains computation result when future is completed" do
+        fut = future { 42 }
+
+        do_something
+
+        expect(fut.value).to eq(42)
+      end
+
+      it "contains nil when future is pending" do
+        fut = future { do_something; 42 }
+
+        expect(fut.value).to eq(nil)
+      end
+
+      it "contains nil when future is failed" do
+        fut = future { raise RuntimeError }
+
+        do_something
+
+        expect(fut.value).to eq(nil)
+      end
+    end
+
+    describe "#error" do
+      it "contains error when future is failed" do
+        error = RuntimeError.new(description: "Great runtime error")
+        fut = future { raise error }
+
+        do_something
+
+        expect(fut.error).to be(error)
+      end
+    end
+
+    describe "#then" do
+      it "returns a future" do
+        fut = future { do_something; 42 }
+
+        fut2 = fut.then { do_something; :else }
+
+        expect(fut2).to be_a(Future)
+      end
+
+      it "returns a new future" do
+        fut = future { do_something; 42 }
+
+        fut2 = fut.then { do_something; :else }
+
+        expect(fut2).not_to be(fut)
+      end
+
+      it "eventually calculates something else" do
+        fut = future { do_something; 42 }
+        fut2 = fut.then { do_something; :else }
+
+        4.times { do_something }
+
+        expect(fut2.value).to eq(:else)
+      end
+
+      it "passes result to the provided block when completed" do
+        fut = future { do_something; 42 }
+        fut2 = fut.then { |answer| do_something; "answer is: #{answer}" }
+
+        4.times { do_something }
+
+        expect(fut2.value).to eq("answer is: 42")
+      end
+
+      it "raises the same error in a new future when failed" do
+        error = RuntimeError.new(description: "Great runtime error")
+        fut = future { do_something; raise error }
+        fut2 = fut.then { |answer| do_something; "answer is: #{answer}" }
+
+        2.times { do_something }
+
+        expect(fut2.error).to eq(error)
+      end
+
+      it "does not start calculation of a new future until initial is completed" do
+        fut = future { 2.times { do_something }; 42 }
+        fut2 = fut.then { |answer| "answer is: #{answer}" }
+
+        do_something
+
+        expect(fut2.state).to eq(:pending)
+      end
+
+      context "when initial future is already completed" do
+        it "immediately starts computation for a new future" do
+          something = double("Something", notify: nil)
+          fut = future { 42 }
+
+          do_something
+
+          fut2 = fut.then do |answer|
+            something.notify(answer)
+            2.times { do_something }
+            answer + 3
+          end
+
+          do_something
+
+          expect(something).to have_received(:notify).with(42)
+        end
+      end
+
+      context "when initial future is already failed" do
+        it "immediately fails a new future" do
+          fut = future { raise RuntimeError }
+          do_something
+
+          fut2 = fut.then { |answer| do_something; answer + 3 }
+
+          expect(fut2.state).to eq(:failed)
+        end
+
+      end
+    end
+
+    describe "#await" do
+      it "awaits for computation to complete" do
+        fut = future { do_something; 42 }
+
+        fut.await
+
+        expect(fut.state).to eq(:completed)
+      end
+
+      it "awaits for computation to fail" do
+        fut = future { do_something; raise RuntimeError }
+
+        fut.await
+
+        expect(fut.state).to eq(:failed)
+      end
+
+      it "awaits for computation chain to complete" do
+        fut = future { do_something; 42 }
+        fut2 = fut.then { |answer| do_something; "Answer is: #{answer}" }
+        fut3 = fut2.then { |report| do_something; "WTF? Why #{report.downcase}?" }
+
+        fut3.await
+
+        expect(fut3.value).to eq("WTF? Why answer is: 42?")
+      end
+
+      it "does not fails when awaits more than once" do
+        fut = future { do_something; 42 }
+
+        expect {
+          fut.await
+          fut.await
+          fut.await
+        }.not_to raise_error
+      end
+    end
+
+    describe "#run" do
+      it "runs future" do
+        fut = Future.new { do_something; 42 }
+
+        2.times { do_something }
+
+        fut.run
+        expect(fut.state).to eq(:pending)
+      end
+
+      it "cannot be run when it is already running" do
+        fut = future { do_something; 42 }
+
+        expect {
+          fut.run
+        }.to raise_error(RuntimeError)
+      end
+    end
+
+    private
+
+    def do_something
+      sleep(0.01)
+    end
+
+  end
+end

data/spec/visionary/promise_spec.rb

@@ -0,0 +1,75 @@
+module Visionary
+  RSpec.describe Promise do
+
+    describe "Kernel#promise" do
+      it "creates new promise" do
+        p = double("Promise")
+
+        allow(Promise).to receive(:new) { p }
+
+        expect(promise).to be(p)
+      end
+    end
+
+    describe "#future" do
+      it "returns associated future" do
+        expect(promise.future).to be_a(Future)
+      end
+
+      it "returns the exact future all the times" do
+        p = promise
+        expect(p.future).to be(p.future)
+      end
+
+      it "returns pending future" do
+        expect(promise.future.state).to eq(:pending)
+      end
+    end
+
+    describe "#complete" do
+      it "completes future" do
+        p = promise
+        expect { p.complete(42) }
+          .to change { p.future.state }
+          .from(:pending)
+          .to(:completed)
+      end
+
+      it "stores passed value as a value in future" do
+        p = promise
+        p.complete(42)
+        expect(p.future.value).to eq(42)
+      end
+
+      it "becomes frozen" do
+        p = promise
+        p.complete(42)
+        expect(p.frozen?).to eq(true)
+      end
+    end
+
+    describe "#fail" do
+      it "failes future" do
+        p = promise
+        expect { p.fail(RuntimeError.new) }
+          .to change { p.future.state }
+          .from(:pending)
+          .to(:failed)
+      end
+
+      it "stores passed error as an error in future" do
+        p = promise
+        error = RuntimeError.new("Crazy description")
+        p.fail(error)
+        expect(p.future.error).to be(error)
+      end
+
+      it "becomes frozen" do
+        p = promise
+        p.fail(RuntimeError.new)
+        expect(p.frozen?).to eq(true)
+      end
+    end
+
+  end
+end

data/spec/visionary/promised_future_spec.rb

@@ -0,0 +1 @@
+RSpec.describe "something"

data/spec/visionary_spec.rb

@@ -1,11 +1,5 @@
-require 'spec_helper'
-
 describe Visionary do
-  it 'has a version number' do
+  it "has a version number" do
     expect(Visionary::VERSION).not_to be nil
   end
-
-  it 'does something useful' do
-    expect(false).to eq(true)
-  end
 end

data/visionary.gemspec

@@ -21,4 +21,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.6"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec"
+  spec.add_development_dependency "cucumber"
+  spec.add_development_dependency "aruba"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: visionary
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Alexey Fedorov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-26 00:00:00.000000000 Z
+date: 2014-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: cucumber
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: aruba
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: ''
 email:
 - waterlink000@gmail.com
@@ -67,8 +95,13 @@ files:
 - README.md
 - Rakefile
 - lib/visionary.rb
+- lib/visionary/future.rb
+- lib/visionary/promise.rb
 - lib/visionary/version.rb
 - spec/spec_helper.rb
+- spec/visionary/future_spec.rb
+- spec/visionary/promise_spec.rb
+- spec/visionary/promised_future_spec.rb
 - spec/visionary_spec.rb
 - visionary.gemspec
 homepage: ''
@@ -97,4 +130,7 @@ specification_version: 4
 summary: Simple futures implementation in ruby.
 test_files:
 - spec/spec_helper.rb
+- spec/visionary/future_spec.rb
+- spec/visionary/promise_spec.rb
+- spec/visionary/promised_future_spec.rb
 - spec/visionary_spec.rb