delayer-deferred 1.1.1 → 2.0.0

data/lib/delayer/deferred/deferredable/awaitable.rb

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+
+module Delayer::Deferred::Deferredable
+  module Awaitable
+
+    # _self_ が終了して結果が出るまで呼び出し側のDeferredを停止し、 _self_ の結果を返す。
+    # 呼び出し側はDeferredブロック内でなければならないが、 _Deferred#next_ を使わずに
+    # 直接戻り値を得ることが出来る。
+    # _self_ が失敗した場合は、呼び出し側のDeferredの直近の _trap_ ブロックが呼ばれる。
+    def +@
+      response = Fiber.yield(Delayer::Deferred::Request::Await.new(self))
+      if response.ok?
+        response.value
+      else
+        Delayer::Deferred.fail(response.value)
+      end
+    end
+
+    def enter_await
+      change_sequence(:await)
+    end
+
+    def exit_await
+      change_sequence(:resume)
+    end
+  end
+end

data/lib/delayer/deferred/deferredable/chainable.rb

@@ -0,0 +1,155 @@
+# -*- coding: utf-8 -*-
+require "delayer/deferred/deferredable/awaitable"
+require "delayer/deferred/deferredable/graph"
+require "delayer/deferred/deferredable/node_sequence"
+
+module Delayer::Deferred::Deferredable
+  module Chainable
+    include Awaitable
+    include Graph
+    include NodeSequence
+
+    attr_reader :child
+
+    # このDeferredが成功した場合の処理を追加する。
+    # 新しいDeferredのインスタンスを返す。
+    # このメソッドはスレッドセーフです。
+    # TODO: procが空のとき例外を発生させる
+    def next(&proc)
+      add_child(Delayer::Deferred::Chain::Next.new(&proc))
+    end
+    alias deferred next
+
+    # このDeferredが失敗した場合の処理を追加する。
+    # 新しいDeferredのインスタンスを返す。
+    # このメソッドはスレッドセーフです。
+    # TODO: procが空のとき例外を発生させる
+    def trap(&proc)
+      add_child(Delayer::Deferred::Chain::Trap.new(&proc))
+    end
+    alias error trap
+
+    # この一連のDeferredをこれ以上実行しない。
+    # このメソッドはスレッドセーフです。
+    def cancel
+      change_sequence(:genocide) unless spoiled?
+    end
+
+    def has_child?
+      child ? true : false
+    end
+
+    # 子を追加する。
+    # _Delayer::Deferred::Chainable_ を直接指定できる。通常外部から呼ぶときは _next_ か _trap_ メソッドを使うこと。
+    # このメソッドはスレッドセーフです。
+    # ==== Args
+    # [chainable] 子となるDeferred
+    # ==== Return
+    # 必ず _chainable_ を返す
+    # ==== Raise
+    # [Delayer::Deferred::SequenceError]
+    #   既に子が存在している場合
+    def add_child(chainable)
+      change_sequence(:get_child) do
+        chainable.parent = self
+        @child = chainable
+      end
+    end
+
+    # 子が追加された時に一度だけコールバックするオブジェクトを登録する。
+    # observerと言っているが、実際には _Delayer::Deferred::Worker_ を渡して利用している。
+    # このメソッドはスレッドセーフです。
+    # ==== Args
+    # [observer] pushメソッドを備えているもの。引数に _@child_ の値が渡される
+    # ==== Return
+    # self
+    def add_child_observer(observer)
+      change_sequence(:gaze) do
+        @child_observer = observer
+      end
+      self
+    end
+
+    def awaited
+      @awaited ||= [].freeze
+    end
+
+    def has_awaited?
+      not awaited.empty?
+    end
+
+    def add_awaited(awaitable)
+      @awaited = [*awaited, awaitable].freeze
+      self
+    end
+
+    # activateメソッドを呼ぶDelayerジョブを登録する寸前に呼ばれる。
+    def reserve_activate
+      change_sequence(:reserve)
+    end
+
+    def enter_pass
+      change_sequence(:pass)
+    end
+
+    def exit_pass
+      change_sequence(:resume)
+    end
+
+    protected
+
+    # 親を再帰的に辿り、一番最初のノードを返す。
+    # 親が複数見つかった場合は、それらを返す。
+    def ancestor
+      if @parent
+        @parent.ancestor
+      else
+        self
+      end
+    end
+
+    # cancelとかデバッグ用のコールグラフを得るために親を登録しておく。
+    # add_childから呼ばれる。
+    def parent=(chainable)
+      @parent = chainable
+    end
+
+    private
+
+    def call_child_observer
+      if has_child? and defined?(@child_observer)
+        change_sequence(:called)
+        @child_observer.push(@child)
+      end
+    end
+
+    def on_sequence_changed(old_seq, flow, new_seq)
+      case new_seq
+      when NodeSequence::BURST_OUT
+        call_child_observer
+      when NodeSequence::GENOCIDE
+        @parent.cancel if defined?(@parent) and @parent
+      when NodeSequence::RESERVED_C, NodeSequence::RUN_C, NodeSequence::PASS_C, NodeSequence::AWAIT_C, NodeSequence::GRAFT_C
+        if !has_child?
+          notice "child: #{@child.inspect}"
+          raise Delayer::Deferred::SequenceError.new("Sequence changed `#{old_seq.name}' to `#{flow}', but it has no child")
+        end
+      end
+    end
+
+    # ノードの名前。サブクラスでオーバライドし、ノードが定義されたファイルの名前や行数などを入れておく。
+    def node_name
+      self.class.to_s
+    end
+
+    def graph_mynode
+      if defined?(@seq_logger)
+        label = "#{node_name}\n(#{@seq_logger.map(&:name).join('→')})"
+      else
+        label = "#{node_name}\n(#{sequence.name})"
+      end
+      "#{__id__} [shape=#{graph_shape},label=#{label.inspect}]"
+    end
+
+  end
+end

data/lib/delayer/deferred/deferredable/graph.rb

@@ -0,0 +1,118 @@
+# -*- coding: utf-8 -*-
+
+module Delayer::Deferred::Deferredable
+=begin rdoc
+graphvizによってChainableなDeferredをDOT言語形式でダンプする機能を追加するmix-in。
+いずれかのノードに対して _graph_ メソッドを呼ぶと、再帰的に親子を全て辿り、digraphの断片の文字列を得ることが出来る。
+
+== 出力例
+
+  20892180 [shape=egg,label="#<Class:0x000000027da288>.Promise\n(reserved)"]
+  20892480 [shape=box,label="test/thread_test.rb:53\n(connected)"]
+  20891440 [shape=diamond,label="test/thread_test.rb:56\n(fresh)"]
+  20892480 -> 20891440
+  20892180 -> 20892480
+
+=end
+  module Graph
+    # この一連のDeferredチェインの様子を、DOT言語フォーマットで出力する
+    # ==== Args
+    # [child_only:]
+    #   _true_ なら、このノードとその子孫のみを描画する。
+    #   _false_ なら、再帰的に親を遡り、そこから描画を開始する。
+    # [output:]
+    #   このオブジェクトに、 _<<_ メソッドで内容が書かれる。
+    #   省略した場合は、戻り値が _String_ になる。
+    # ==== Return
+    # [String] DOT言語によるグラフ
+    # [output:] 引数 output: に指定されたオブジェクト
+    def graph(child_only: false, output: String.new)
+      if child_only
+        output << "digraph Deferred {\n".freeze
+        Enumerator.new{ |yielder|
+          graph_child(output: yielder)
+        }.lazy.each{|l|
+          output << "\t#{l}\n"
+        }
+        output << '}'.freeze
+      else
+        ancestor.graph(child_only: true, output: output)
+      end
+    end
+
+    # Graph.graph の結果を内容とする一時ファイルを作成して返す。
+    # ただし、ブロックを渡された場合は、一時ファイルを引数にそのブロックを一度だけ実行し、ブロックの戻り値をこのメソッドの戻り値とする。
+    # ==== Args
+    # [&block] 一時ファイルを利用する処理
+    # ==== Return
+    # [Tempfile] ブロックを指定しなかった場合。作成された一時ファイルオブジェクト
+    # [Object] ブロックが指定された場合。ブロックの実行結果。
+    def graph_save(permanent: false, &block)
+      if block
+        Tempfile.open{|tmp|
+          graph(output: tmp)
+          tmp.seek(0)
+          block.(tmp)
+        }
+      else
+        tmp = Tempfile.open
+        graph(output: tmp).tap{|t|t.seek(0)}
+      end
+    end
+
+    # 画像ファイルとしてグラフを書き出す。
+    # dotコマンドが使えないと失敗する。
+    # ==== Args
+    # [format:] 画像の拡張子
+    # ==== Return
+    # [String] 書き出したファイル名
+    def graph_draw(dir: '/tmp', format: 'svg'.freeze)
+      graph_save do |dotfile|
+        base = File.basename(dotfile.path)
+        dest = File.join(dir, "#{base}.#{format}")
+        system("dot -T#{format} #{dotfile.path} -o #{dest}")
+        dest
+      end
+    end
+
+    # このノードとその子全てのDeferredチェインの様子を、DOT言語フォーマットで出力する。
+    # Delayer::Deferred::Deferredable::Graph#graph の内部で利用されるため、将来このメソッドのインターフェイスは変更される可能性がある。
+    def graph_child(output:)
+      output << graph_mynode
+      if has_child?
+        @child.graph_child(output: output)
+        output << "#{__id__} -> #{@child.__id__}"
+      end
+      if has_awaited?
+        awaited.each do |awaitable|
+          if awaitable.is_a?(Delayer::Deferred::Deferredable::Chainable)
+            awaitable.ancestor.graph_child(output: output)
+          else
+            label = "#{awaitable.class}"
+            output << "#{awaitable.__id__} [shape=oval,label=#{label.inspect}]"
+          end
+          output << "#{awaitable.__id__} -> #{__id__} [label = \"await\", style = \"dotted\"]"
+        end
+      end
+      nil
+    end
+
+    private
+
+    # このノードを描画する時の形の名前を文字列で返す。
+    # 以下のページにあるような、graphvizで取り扱える形の中から選ぶこと。
+    # http://www.graphviz.org/doc/info/shapes.html
+    def graph_shape
+      'oval'.freeze
+    end
+
+    # このノードの形などをDOT言語の断片で返す。
+    # このメソッドをオーバライドすることで、描画されるノードの見た目を自由に変更することが出来る。
+    # ただし、簡単な変更だけなら別のメソッドをオーバライドするだけで可能なので、このmix-inの他のメソッドも参照すること。
+    def graph_mynode
+      label = "#{node_name}\n(#{sequence.name})"
+      "#{__id__} [shape=#{graph_shape},label=#{label.inspect}]"
+    end
+
+  end
+end

data/lib/delayer/deferred/deferredable/node_sequence.rb

@@ -0,0 +1,158 @@
+# -*- coding: utf-8 -*-
+require 'delayer/deferred/error'
+
+require 'thread'
+
+module Delayer::Deferred::Deferredable
+  module NodeSequence
+    class Sequence
+      attr_reader :name
+
+      def initialize(name)
+        @name = name.to_sym
+        @map = {}
+        @exceptions = Hash.new(Delayer::Deferred::SequenceError)
+      end
+
+      def add(seq, flow = seq.name)
+        @map[flow] = seq
+        self
+      end
+
+      def exception(exc, flow)
+        @exceptions[flow] = exc
+        self
+      end
+
+      def pull(flow)
+        if @map.has_key?(flow.to_sym)
+          @map[flow.to_sym]
+        else
+          raise @exceptions[flow.to_sym], "Invalid sequence flow `#{name}' to `#{flow}'."
+        end
+      end
+
+      def inspect
+        "#<#{self.class}: #{name}>"
+      end
+    end
+
+    FRESH     = Sequence.new(:fresh)
+    CONNECTED = Sequence.new(:connected)      # 子がいる、未実行
+    RESERVED  = Sequence.new(:reserved)       # 実行キュー待ち
+    RESERVED_C= Sequence.new(:reserved)       # 実行キュー待ち(子がいる)
+    RUN       = Sequence.new(:run)            # 実行中
+    RUN_C     = Sequence.new(:run)            # 実行中(子がいる)
+    PASS      = Sequence.new(:pass)           # パス中
+    PASS_C    = Sequence.new(:pass)           # パス中
+    AWAIT     = Sequence.new(:await)          # Await中
+    AWAIT_C   = Sequence.new(:await)          # Await中(子がいる)
+    GRAFT     = Sequence.new(:graft)          # 戻り値がAwaitableの時
+    GRAFT_C   = Sequence.new(:graft)          # 戻り値がAwaitableの時(子がいる)
+    CALL_CHILD= Sequence.new(:call_child)     # 完了、子がいる
+    STOP      = Sequence.new(:stop)           # 完了、子なし
+    WAIT      = Sequence.new(:wait)           # 完了、オブザーバ登録済み
+    BURST_OUT = Sequence.new(:burst_out)      # 完了、オブザーバ登録済み、子追加済み
+    ROTTEN    = Sequence.new(:rotten).freeze  # 終了
+    GENOCIDE  = Sequence.new(:genocide).freeze# この地ではかつて大量虐殺があったという。
+
+    FRESH
+      .add(CONNECTED, :get_child)
+      .add(RESERVED, :reserve)
+      .add(GENOCIDE).freeze
+    CONNECTED
+      .add(RESERVED_C, :reserve)
+      .exception(Delayer::Deferred::MultipleAssignmentError, :get_child)
+      .add(GENOCIDE).freeze
+    RESERVED
+      .add(RUN, :activate)
+      .add(RESERVED_C, :get_child)
+      .add(GENOCIDE).freeze
+    RESERVED_C
+      .add(RUN_C, :activate)
+      .exception(Delayer::Deferred::MultipleAssignmentError, :get_child)
+      .add(GENOCIDE).freeze
+    RUN
+      .add(RUN_C, :get_child)
+      .add(PASS)
+      .add(AWAIT, :await)
+      .add(STOP, :complete)
+      .add(GENOCIDE).freeze
+    RUN_C
+      .add(PASS_C)
+      .add(AWAIT_C, :await)
+      .add(CALL_CHILD, :complete)
+      .exception(Delayer::Deferred::MultipleAssignmentError, :get_child)
+      .add(GENOCIDE).freeze
+    PASS
+      .add(PASS_C, :get_child)
+      .add(RUN, :resume)
+      .add(GENOCIDE).freeze
+    PASS_C
+      .add(RUN_C, :resume)
+      .add(GENOCIDE).freeze
+    AWAIT
+      .add(RUN, :resume)
+      .add(AWAIT_C, :get_child)
+      .add(GENOCIDE).freeze
+    AWAIT_C
+      .add(RUN_C, :resume)
+      .exception(Delayer::Deferred::MultipleAssignmentError, :get_child)
+      .add(GENOCIDE).freeze
+    CALL_CHILD
+      .add(GRAFT_C, :await)
+      .add(ROTTEN, :called)
+      .add(GENOCIDE).freeze
+    GRAFT
+      .add(STOP, :resume)
+      .add(GRAFT_C, :get_child)
+      .add(GENOCIDE).freeze
+    GRAFT_C
+      .add(CALL_CHILD, :resume)
+      .add(GENOCIDE).freeze
+    STOP
+      .add(GRAFT, :await)
+      .add(WAIT, :gaze)
+      .add(GENOCIDE).freeze
+    WAIT
+      .add(BURST_OUT, :get_child)
+      .add(GENOCIDE).freeze
+    BURST_OUT
+      .add(ROTTEN, :called)
+      .add(GENOCIDE).freeze
+
+    SEQUENCE_LOCK = Monitor.new
+
+    def sequence
+      @sequence ||= FRESH
+    end
+
+    # このメソッドはスレッドセーフです
+    def change_sequence(flow, &block)
+      SEQUENCE_LOCK.synchronize do
+        old_seq = sequence
+        new_seq = @sequence = sequence.pull(flow)
+        (@seq_logger ||= [old_seq]) << new_seq
+        if block
+          result = block.()
+          on_sequence_changed(old_seq, flow, new_seq)
+          result
+        else
+          on_sequence_changed(old_seq, flow, new_seq)
+          nil
+        end
+      end
+    end
+
+    def on_sequence_changed(old_seq, flow, new_seq)
+    end
+
+    def activated?
+      ![FRESH, CONNECTED, RUN, RUN_C].include?(sequence)
+    end
+
+    def spoiled?
+      sequence == ROTTEN || sequence == GENOCIDE
+    end
+  end
+end