delayer-deferred 1.1.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 37e4d01b997cbcc9e878f5743755883123843d4f
-  data.tar.gz: f43c013e223a6f30da88a500237fbb1920473e26
+  metadata.gz: 5fe3336ed51fed19dfd37766cf6b1144a6a8de45
+  data.tar.gz: ceb10cb5738de56ccd937ef6e8ee253ca6c0756e
 SHA512:
-  metadata.gz: e53e3785d68e9c69431742d81efaa936ee80a93cf726c0c42f022732e120cbb7b5a08036743081b780e9548d7fbe4d797b1688c2a4ec68fd8a4e0a072770a860
-  data.tar.gz: dd6d334922b6e999fd2f2eb90fc3fccd656d038d76cfa10b6742961246c1feaca452862837a57c8a3dc33d2ed4257df38fbc401f15e5a40f505f8b8fdab53c6f
+  metadata.gz: f7e52f1cf451cfc12e61d9712d55113e7d42a8f68b57459b7b9c55a9b04e93c6fad6a171a0de157f40583b5fac29f350ab1204513ddd100801da468baf47e87c
+  data.tar.gz: a72e6d3f75728f7b93296acc387207ec2aaa4e3ce809cd564bff82ef298934168b769af87d2ead3b22752bcd2ab29e6f7de0d15924b25aec83114e609fa143ed

data/README.md

@@ -1,7 +1,6 @@
 # Delayer::Deferred
 
-Delayerを使って、jsdeferredをRubyに移植したものです。
-jsdeferredでできること以外に、Thread、Enumeratorを拡張します。
+Delayerの、ブロックを実行キューにキューイングする機能を利用し、エラー処理やasync/awaitのような機能をサポートするライブラリです。
 
 ## Installation
 
@@ -101,7 +100,7 @@ Error occured!
 ```
 
 ### Thread
-Threadには、Delayer::Deferred::Deferredableモジュールがincludeされていて、nextやtrapメソッドが使えます。
+Threadには、nextやtrapメソッドが実装されているので、Deferredのように扱うことができます。
 
 ```ruby
 Delayer.default = Delayer.generate_class  # Delayerの準備
@@ -117,6 +116,8 @@ Delayer.run
 2
 ```
 
+この場合、nextやtrapのブロックは、全て `Delayer.run` メソッドが実行された側のThreadで実行されます。
+
 ### Automatically Divide a Long Loop
 `Enumerable#deach`, `Enumerator#deach`はeachの変種で、Delayerのexpireの値よりループに時間がかかったら一旦処理を中断して、続きを実行するDeferredを新たに作ります。
 
@@ -156,6 +157,79 @@ divided
 
 また、このメソッドはDeferredを返すので、ループが終わった後に処理をしたり、エラーを受け取ったりできます。
 
+### Pass to another Delayer
+
+Deferredのコンテキストの中で `Deferred.pass` を呼ぶと、そこで一旦処理が中断し、キューの最後に並び直します。
+他のDelayerが処理され終わると `Deferred.pass` から処理が戻ってきて、再度そこから実行が再開されます。
+
+`Deferred.pass` は常に処理を中断するわけではなく、Delayerの時間制限を過ぎている場合にのみ処理をブレークします。
+用途としては `Enumerator#deach` が使えないようなループの中で毎回呼び出して、長時間処理をブロックしないようにするといった用途が考えられます。
+
+`Enumerator#deach` は `Deferred.pass` を用いて作られています。
+
+### Combine Deferred
+
+`Deferred.when` は、引数に2つ以上のDeferredを受け取り、新たなDeferredを一つ返します。
+
+引数のDeferredすべてが正常に終了したら、戻り値のDeferredのnextブロックが呼ばれ、whenの引数の順番通りに戻り値が渡されます。
+複数のDeferredがあって、それらすべてが終了するのを待ち合わせる時に使うと良いでしょう。
+
+```ruby
+web_a = Thread.new{ open("http://example.com/a.html") }
+web_b = Thread.new{ open("http://example.com/b.html") }
+web_c = Thread.new{ open("http://example.com/c.html") }
+
+# 引数の順番は対応している
+Deferred.when(web_a, web_b, web_c).next do |a, b, c|
+  ...
+end
+
+# 配列を渡すことも出来る
+Deferred.when([web_a, web_b, web_c]).next do |a, b, c|
+  ...
+end
+
+```
+
+引数のDeferredのうち、どれか一つでも失敗すると、直ちに `Deferred.when` の戻り値のtrapブロックが呼ばれます。trapの引数は、失敗したDeferredのそれです。
+
+どれか一つでも失敗すると、他のDeferredが成功していたとしてもその結果は破棄されるということに気をつけてください。より細かく制御したい場合は、Async/Awaitを利用しましょう。
+
+```ruby
+divzero = Delayer::Deferred.new {
+  1 / 0
+}
+web_a = Thread.new{ open("http://example.com/a.html") }
+
+Deferred.when(divzero, web_a).next{
+  puts 'success'
+}.trap{|err|
+  p err
+}
+```
+
+```
+\#<ZeroDivisionError: divided by 0>
+```
+
+### Async/Await
+
+Deferred#next や Deferred#trap のブロック内では、Deferredable#+@ が使えます。非同期な処理を同期処理のように書くことができます。
+
++@を呼び出すと、呼び出し元のDeferredの処理が一時停止し、+@のレシーバになっているDeferredableが完了した後に処理が再開されます。また、戻り値はレシーバのDeferredableのそれになります。
+
+```
+request = Thread.new{ open("http://mikutter.hachune.net/download/unstable.json").read }
+Deferred.next{
+  puts "最新の不安定版mikutterのバージョンは"
+  response = JSON.parse(+request)
+  puts response.first["version_string"]
+  puts "です"
+}
+```
+
+`+request` が呼ばれた時、リクエスト完了まで処理は一時止まりますが、他にDelayerキューにジョブが溜まっていたら、そちらが実行されます。この機能を使わない場合は、HTTPレスポンスを受け取るまでDelayerの他のジョブは停止してしまいます。
+
 ## Contributing
 
 1. Fork it ( https://github.com/toshia/delayer-deferred/fork )

data/delayer-deferred.gemspec

@@ -25,6 +25,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.7"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "minitest", "~> 5.7"
+  spec.add_development_dependency "simplecov"
   spec.add_development_dependency "ruby-prof"
   spec.add_development_dependency 'guard'
   spec.add_development_dependency 'guard-shell'

data/lib/delayer/deferred.rb

@@ -10,25 +10,26 @@ require "delayer/deferred/version"
 
 module Delayer
   module Deferred
-    extend Delayer::Deferred::Tools
-
     class << self
       #真ならデバッグ情報を集める
       attr_accessor :debug
 
-      def new(*rest, &proc)
-        Delayer::Deferred::Deferred.new(*rest, &proc) end
+      def method_missing(*rest, &block)
+        Delayer::Deferred::Deferred.__send__(*rest, &block)
+      end
     end
   end
 
   module Extend
-    def Deferred
-      @deferred ||= begin
-                      the_delayer = self
-                      Class.new(::Delayer::Deferred::Deferred) {
-                        define_singleton_method(:delayer) {
-                          the_delayer } } end
+    def Promise
+      @promise ||= begin
+                     the_delayer = self
+                     Class.new(::Delayer::Deferred::Promise) {
+                       define_singleton_method(:delayer) {
+                         the_delayer } } end
     end
+    alias :Deferred :Promise
+    #deprecate :Deferred, "Promise", 2018, 03
   end
 end
 

data/lib/delayer/deferred/chain.rb

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+
+module Delayer::Deferred
+  module Chain; end
+end
+
+require "delayer/deferred/chain/await"
+require "delayer/deferred/chain/base"
+require "delayer/deferred/chain/next"
+require "delayer/deferred/chain/trap"

data/lib/delayer/deferred/chain/await.rb

@@ -0,0 +1,43 @@
+# -*- coding: utf-8 -*-
+require "delayer/deferred/chain/base"
+
+module Delayer::Deferred::Chain
+  class Await < Base
+    def initialize(worker:, deferred:)
+      super()
+      @worker, @awaiting_deferred = worker, deferred
+      deferred.add_awaited(self)
+    end
+
+    def activate(response)
+      change_sequence(:activate)
+      @worker.give_response(response, @awaiting_deferred)
+    # TODO: 即座にspoilさせてよさそう
+    ensure
+      change_sequence(:complete)
+    end
+
+    def graph_child(output:)
+      output << graph_mynode
+      if has_child?
+        @child.graph_child(output: output)
+        @awaiting_deferred.graph_child(output: output)
+        output << "#{__id__} -> #{@child.__id__}"
+      end
+      nil
+    end
+
+    def node_name
+      "Await"
+    end
+
+    def graph_shape
+      'circle'.freeze
+    end
+
+    def graph_mynode
+      label = "#{node_name}\n(#{sequence.name})"
+      "#{__id__} [shape=#{graph_shape},label=#{label.inspect}]"
+    end
+  end
+end

data/lib/delayer/deferred/chain/base.rb

@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+require "delayer/deferred/deferredable/chainable"
+require "delayer/deferred/deferredable/node_sequence"
+
+module Delayer::Deferred::Chain
+  class Base
+    include Delayer::Deferred::Deferredable::NodeSequence
+    include Delayer::Deferred::Deferredable::Chainable
+
+    def initialize(&proc)
+      fail Error, "Delayer::Deferred::Chain can't create instance." if self.class == Delayer::Deferred::Chain::Base
+      @proc = proc
+    end
+
+    def activate(response)
+      change_sequence(:activate)
+      if evaluate?(response)
+        @proc.(response.value)
+      else
+        response
+      end
+    ensure
+      change_sequence(:complete)
+    end
+
+    def inspect
+      "#<#{self.class} seq:#{sequence.name} child:#{has_child?}>"
+    end
+
+    def node_name
+      @proc.source_location.join(':'.freeze)
+    end
+  end
+end
+

data/lib/delayer/deferred/chain/next.rb

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+require "delayer/deferred/chain/base"
+
+module Delayer::Deferred::Chain
+  class Next < Base
+    def evaluate?(response)
+      response.ok?
+    end
+
+    private
+
+    def graph_shape
+      'box'.freeze
+    end
+  end
+end

data/lib/delayer/deferred/chain/trap.rb

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+require "delayer/deferred/chain/base"
+
+module Delayer::Deferred::Chain
+  class Trap < Base
+    def evaluate?(response)
+      response.ng?
+    end
+
+    private
+
+    def graph_shape
+      'diamond'.freeze
+    end
+  end
+end

data/lib/delayer/deferred/deferred.rb

@@ -1,78 +1,10 @@
 # -*- coding: utf-8 -*-
+require "delayer/deferred/promise"
+require "delayer/deferred/chain"
 require "delayer/deferred/deferredable"
-require "delayer/deferred/tools"
+require "delayer/deferred/worker"
 require "delayer/deferred/version"
 
 module Delayer::Deferred
-  class Deferred
-    extend Delayer::Deferred::Tools
-    include Deferredable
-
-    def self.inherited(subclass)
-      subclass.extend(::Delayer::Deferred)
-    end
-
-    def self.Thread
-      @thread_class ||= gen_thread_class end
-
-    def self.gen_thread_class
-      the_delayer = delayer
-      Class.new(Thread) do
-        define_singleton_method(:delayer) do
-          the_delayer end end end
-
-    def self.delayer
-       ::Delayer end
-
-    def self.new(*args)
-      deferred = super(*args)
-      if block_given?
-        deferred.next(&Proc.new)
-      else
-        deferred end
-    end
-
-    def initialize(follow = nil)
-      super()
-      @follow = follow
-      @backtrace = caller if ::Delayer::Deferred.debug end
-
-    alias :deferredable_cancel :cancel
-    def cancel
-      deferredable_cancel
-      @follow.cancel if @follow.is_a? Deferredable end
-
-    def inspect
-      if ::Delayer::Deferred.debug
-        sprintf("#<%s: %p %s follow:%p stat:%s value:%s>".freeze, self.class, object_id, @backtrace.find{|n|not n.include?("delayer/deferred".freeze)}, @follow ? @follow.object_id : 0, @next_call_stat.inspect, @next_call_value.inspect)
-      else
-        sprintf("#<%s: %p stat:%s value:%s>".freeze, self.class, object_id, @next_call_stat.inspect, @next_call_value.inspect)
-      end
-    end
-
-    def self.fiber(&block)
-      @_fiber ||= _gen_new_fiber
-      begin
-        result = @_fiber.resume(block)
-      rescue FiberError
-        @_fiber = _gen_new_fiber
-        result = @_fiber.resume(block)
-      end
-      if result.is_a?(Delayer::Deferred::ResultContainer)
-        result
-      else
-        _fiber = @_fiber
-        @_fiber = nil
-        return result, _fiber
-      end
-    end
-
-    def self._gen_new_fiber
-      Fiber.new do |b|
-        loop do
-          b = Fiber.yield(b.())
-        end
-      end
-    end
-  end
+  Deferred = Promise
 end

data/lib/delayer/deferred/deferredable.rb

@@ -1,162 +1,12 @@
 # -*- coding: utf-8 -*-
 require "delayer/deferred/version"
-require "delayer/deferred/result_container"
-
-# なんでもDeferred
-module Delayer::Deferred::Deferredable
-  Callback = Struct.new(*%i<ok ng backtrace>)
-  CallbackDefaultOK = lambda{ |x| x }
-  CallbackDefaultNG = lambda{ |err| Delayer::Deferred.fail(err) }
-
-  # このDeferredが成功した場合の処理を追加する。
-  # 新しいDeferredのインスタンスを返す
-  def next(&proc)
-    _post(:ok, &proc) end
-  alias deferred next
-
-  # このDeferredが失敗した場合の処理を追加する。
-  # 新しいDeferredのインスタンスを返す
-  def trap(&proc)
-    _post(:ng, &proc) end
-  alias error trap
-
-  # Deferredを直ちに実行する
-  def call(value = nil)
-    _call(:ok, value) end
-
-  # Deferredを直ちに失敗させる
-  def fail(exception = nil)
-    _call(:ng, exception) end
-
-  # _self_ が終了して結果が出るまで呼び出し側のDeferredを停止し、 _self_ の結果を返す。
-  # 呼び出し側はDeferredブロック内でなければならないが、 _Deferred#next_ を使わずに
-  # 直接戻り値を得ることが出来る。
-  # _self_ が失敗した場合は、呼び出し側のDeferredの直近の _trap_ ブロックが呼ばれる。
-  def +@
-    interrupt = Fiber.yield(self)
-    if interrupt.ok?
-      interrupt.value
-    else
-      Delayer::Deferred.fail(interrupt.value)
-    end
-  end
-
-  # この一連のDeferredをこれ以上実行しない
-  def cancel
-    @callback = Callback.new(CallbackDefaultOK,
-                             CallbackDefaultNG).freeze end
-
-  def callback
-    @callback ||= Callback.new(CallbackDefaultOK,
-                               CallbackDefaultNG) end
-
-  # second 秒待って次を実行する
-  # ==== Args
-  # [second] 待つ秒数(second)
-  # ==== Return
-  # Deferred
-  def wait(second)
-    self.next{ Thread.new{ sleep(second) } } end
-
-  private
-
-  def delayer
-    self.class.delayer
-  end
-
-  def _call(stat = :ok, value = nil)
-    delayer.new do
-      result, fiber = delayer.Deferred.fiber do
-        begin
-          result = catch(:__deferredable_fail) do
-            Delayer::Deferred::ResultContainer.new(true, _execute(stat, value))
-          end
-          if result.is_a?(Delayer::Deferred::ResultContainer)
-            result
-          else
-            Delayer::Deferred::ResultContainer.new(false, result)
-          end
-        rescue Exception => exception
-          Delayer::Deferred::ResultContainer.new(false, exception)
-        end
-      end
-      #_wait_fiber(fiber, nil)
-      if fiber
-        _fiber_stopped(result){|i| _wait_fiber(fiber, i) }
-      else
-        _fiber_completed(result)
-      end
-    end
-  end
-
-
-  def _execute(stat, value)
-    callback[stat].call(value)
-  end
-
-  def _wait_fiber(fiber, resume_value)
-    result = fiber.resume(resume_value)
-    if result.is_a?(Delayer::Deferred::ResultContainer)
-      _fiber_completed(result)
-    else
-      _fiber_stopped(result){|i| _wait_fiber(fiber, i) }
-    end
-  end
-
-  # Deferredブロックが最後まで終わり、これ以上やることがない時に呼ばれる
-  def _fiber_completed(result)
-    result_value = result.value
-    if result.ok?
-      if result_value.is_a?(Delayer::Deferred::Deferredable)
-        result_value.next{|v|
-          _success_action(v)
-        }.trap{|v|
-          _fail_action(v)
-        }
-      else
-        _success_action(result_value)
-      end
-    else
-      _fail_action(result_value)
-    end
-  end
-
-  # Deferredable#@+によって停止され、 _defer_ の完了次第処理を再開する必要がある時に呼ばれる
-  def _fiber_stopped(defer, &cont)
-    defer.next{|v|
-      cont.(Delayer::Deferred::ResultContainer.new(true, v))
-    }.trap{|v|
-      cont.(Delayer::Deferred::ResultContainer.new(false, v))
-    }
-  end
-
-  def _post(kind, &proc)
-    @next = delayer.Deferred.new(self)
-    @next.callback[kind] = proc
-    if defined?(@next_call_stat) and defined?(@next_call_value)
-      @next.__send__({ok: :call, ng: :fail}[@next_call_stat], @next_call_value)
-    elsif defined?(@follow) and @follow.nil?
-      call end
-    @next end
-
-  def register_next_call(stat, value)
-    @next_call_stat, @next_call_value = stat, value
-    self end
-
-  def _success_action(obj)
-    if defined?(@next)
-      @next.call(obj)
-    else
-      register_next_call(:ok, obj)
-    end
-  end
-
-  def _fail_action(err_obj)
-    if defined?(@next)
-      @next.fail(err_obj)
-    else
-      register_next_call(:ng, err_obj)
-    end
-  end
 
+module Delayer::Deferred
+  module Deferredable; end
 end
+
+require "delayer/deferred/deferredable/awaitable"
+require "delayer/deferred/deferredable/chainable"
+require "delayer/deferred/deferredable/graph"
+require "delayer/deferred/deferredable/node_sequence"
+require "delayer/deferred/deferredable/trigger"