aws-flow-core 1.0.0

data/lib/aws/flow/fiber.rb

@@ -0,0 +1,77 @@
+##
+# Copyright 2013 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License").
+# You may not use this file except in compliance with the License.
+# A copy of the License is located at
+#
+#  http://aws.amazon.com/apache2.0
+#
+# or in the "license" file accompanying this file. This file is distributed
+# on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+# express or implied. See the License for the specific language governing
+# permissions and limitations under the License.
+##
+
+# This file contains our implementation of fibers for 1.8
+module AWS
+  module Flow
+    module Core
+      require 'fiber'
+      class FlowFiber < Fiber
+        def initialize(*args)
+          ObjectSpace.define_finalizer(self, self.class.finalize(self.object_id))
+          super(args)
+        end
+        class << self
+          attr_accessor :local_variables
+        end
+        @local_variables = Hash.new {|hash, key| hash[key] = {}}
+        def self.finalize(obj_id)
+          proc { FlowFiber.local_variables.delete(obj_id) }
+        end
+        def self.[](index)
+          self.local_variables[index]
+        end
+        def self.[]=(key, value)
+          self.local_variables[key] = value
+        end
+
+        # Will unset all the values for ancestors of this fiber, assuming that
+        # they have the same value for key. That is, they will unset upwards until
+        # the first time the value stored at key is changed
+        def self.unset(current_fiber, key)
+          current_value = FlowFiber[current_fiber.object_id][key]
+          parent = FlowFiber[current_fiber.object_id][:parent]
+          ancestor_fibers = []
+          while parent != nil
+            ancestor_fibers << parent
+            parent = FlowFiber[parent.object_id][:parent]
+          end
+          ancestor_fibers.each do |fiber|
+            FlowFiber[fiber.object_id].delete(key) if FlowFiber[fiber.object_id][key] == current_value
+          end
+          FlowFiber[current_fiber.object_id].delete(key)
+        end
+
+        def initialize
+          # Child fibers should inherit their parents FiberLocals
+          FlowFiber[Fiber.current.object_id].each_pair do |key, val|
+            FlowFiber[self.object_id][key] = val
+          end
+          FlowFiber[self.object_id][:parent] = Fiber.current
+          super
+        end
+
+        def [](key)
+          FlowFiber[self.object_id][key]
+        end
+        def []=(key, value)
+          FlowFiber[self.object_id][key] = value
+        end
+
+      end
+
+    end
+  end
+end

data/lib/aws/flow/flow_utils.rb

@@ -0,0 +1,50 @@
+##
+# Copyright 2013 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License").
+# You may not use this file except in compliance with the License.
+# A copy of the License is located at
+#
+#  http://aws.amazon.com/apache2.0
+#
+# or in the "license" file accompanying this file. This file is distributed
+# on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+# express or implied. See the License for the specific language governing
+# permissions and limitations under the License.
+##
+
+# This file simply contains definitions and functions useful to the overall running of flow
+module AWS
+  module Flow
+    module Core
+      class IllegalStateException < Exception; end
+      class CancellationException < Exception
+        attr_accessor :reason, :details
+        def initialize(reason = nil, details = nil)
+          @reason = reason
+          @details = details
+        end
+      end
+
+      def make_backtrace(parent_backtrace)
+        # 1 frame for the function that actually removes the stack traces
+        # 1 frame for the function that calls into the function that removes
+        # frames in AsyncBacktrace
+        # 1 frame for the call into this function
+        # 1 frame for the initialize call of the BRE or External Task
+        # 1 frame for the new call into the BRE or ET
+        # 1 frame for the AsyncScope initialize that the BRE/ET has to be in
+
+        # "./lib/aws/rubyflow/asyncBacktrace.rb:75:in `caller'"
+        # "./lib/aws/rubyflow/asyncBacktrace.rb:21:in `create'"
+        # "./lib/aws/rubyflow/flow.rb:16:in `make_backtrace'"
+        # "./lib/aws/rubyflow/flow.rb:103:in `initialize'"
+        # "./lib/aws/rubyflow/asyncScope.rb:17:in `new'"
+        # "./lib/aws/rubyflow/asyncScope.rb:17:in `initialize'"
+
+        frames_to_skip = 7
+        backtrace = AsyncBacktrace.create(parent_backtrace, frames_to_skip)
+      end
+    end
+  end
+end

data/lib/aws/flow/future.rb

@@ -0,0 +1,109 @@
+##
+# Copyright 2013 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License").
+# You may not use this file except in compliance with the License.
+# A copy of the License is located at
+#
+#  http://aws.amazon.com/apache2.0
+#
+# or in the "license" file accompanying this file. This file is distributed
+# on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+# express or implied. See the License for the specific language governing
+# permissions and limitations under the License.
+##
+
+# This file contains our Future implementation, which allows us to have asynchronous, blocking promises
+
+module AWS
+  module Flow
+    module Core
+      class AlreadySetException < Exception; end
+
+      # A Future represents the result of an asynchronous computation. Methods are
+      # provided to check if the computation is complete(Future#set), to wait for
+      # its completion(Future#wait), and to retrieve the result of the
+      # computation(Future#get). The result can only be retrieved using method get
+      # when the computation has completed, blocking if necessary until it is
+      # ready. This is okay, however, because it will block that Fiber, and
+      # another Fiber will start executing
+      class Future
+
+        # Sets the value of the future, and notifies all of the Fibers that tried
+        # to get when this future wasn't ready.
+        def set(result=nil)
+          raise AlreadySetException if @set
+          @set = true
+          @result = result
+          @conditional.broadcast if @conditional
+          @listeners.each { |b| b.call(self) } if @listeners
+          self
+        end
+
+        # Blocks if Future is not set
+        # raises CancellationError when task is cancelled
+        def get
+          until @set
+            @conditional ||= FiberConditionVariable.new
+            @conditional.wait
+          end
+          @result
+        end
+
+        def set?
+          @set
+        end
+
+        def unset
+          @set = nil
+          @result = nil
+        end
+
+        # Add a callback, block, which will fire when the future is set
+        def on_set(&block)
+          @listeners ||= []
+          # TODO probably want to use lambda here
+          @listeners << block
+        end
+      end
+
+      # Based on the ruby core source:
+      # https://github.com/ruby/ruby/blob/trunk/lib/thread.rb
+      class FiberConditionVariable
+        #
+        # Creates a new ConditionVariable
+        #
+        def initialize
+          @waiters = []
+        end
+
+
+        # Have the current fiber wait on this condition variable, and wake up when
+        # the FiberConditionVariable is signalled/broadcaster
+        def wait
+          fiber = ::Fiber.current
+          @waiters << fiber
+          Fiber.yield
+          self
+        end
+
+        #
+        # Wakes up the first fiber in line waiting for this lock.
+        #
+        def signal
+          t = @waiters.shift
+          t.schedule if t && t.alive?
+          self
+        end
+
+        #
+        # Wakes up all fibers waiting for this lock.
+        #
+        def broadcast
+          signal until @waiters.empty?
+          self
+        end
+      end
+    end
+  end
+end

data/lib/aws/flow/implementation.rb

@@ -0,0 +1,151 @@
+#--
+# Copyright 2013 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License").
+# You may not use this file except in compliance with the License.
+# A copy of the License is located at
+#
+#  http://aws.amazon.com/apache2.0
+#
+# or in the "license" file accompanying this file. This file is distributed
+# on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+# express or implied. See the License for the specific language governing
+# permissions and limitations under the License.
+#++
+
+# This file contains the externally visible parts of flow that are expected to be used by customers of flow
+module AWS
+  module Flow
+    module Core
+      class NoContextException < Exception; end
+
+      # @param block
+      #   The block of code to be executed when the task is run.
+      #
+      # @raise [NoContextException]
+      #   If the current fiber does not respond to {#__context__}.
+      #
+      # @return [Future]
+      #   The tasks result, which is a {Future}.
+      #
+      def task(future = nil, &block)
+        fiber = ::Fiber.current
+        raise NoContextException unless fiber.respond_to? :__context__
+        context = fiber.__context__
+        t = Task.new(nil, &block)
+        task_context = TaskContext.new(:parent => context.get_closest_containing_scope, :task => t)
+        context << t
+        t.result
+      end
+
+      #
+      # @param block
+      #   The block of code to be executed when the daemon task is run.
+      #
+      # @return [Future]
+      #   The tasks result, which is a {Future}.
+      #
+      # @raise [NoContextException]
+      #   If the current fiber does not respond to {#__context__}.
+      #
+      def daemon_task(&block)
+        fiber = ::Fiber.current
+        raise NoContextException unless fiber.respond_to? :__context__
+        context = fiber.__context__
+        t = DaemonTask.new(nil, &block)
+        task_context = TaskContext.new(:parent => context.get_closest_containing_scope, :task => t)
+        context << t
+        t.result
+      end
+
+      #
+      # @param block
+      #   The block of code to be executed when the external task is run.
+      #
+      # @return [nil]
+      #
+      # @raise [NoContextException]
+      #   If the current fiber does not respond to {#__context__}.
+      #
+      def external_task(&block)
+        fiber = ::Fiber.current
+        raise NoContextException unless fiber.respond_to? :__context__
+        context = fiber.__context__
+        t = ExternalTask.new(:parent => context.get_closest_containing_scope, &block)
+        task_context = TaskContext.new(:parent => context.get_closest_containing_scope, :task => t)
+        context << t
+        nil
+      end
+
+
+      #
+      #
+      # * *Args*    :
+      #   - block -> a block, which is passed in a BeginRescueEnsureWrapper, and which will define the BeginRescueEnsure#begin, BeginRescueEnsure#rescue, and BeginRescueEnsure#ensure methods
+      # * *Returns* :
+      #   - The result of the begin statement, if there is no error, otherwise the value of the return statement
+      # * *Raises* :
+      #   - +NoContextException+ -> If the current fiber does not respond to #__context__
+      #
+      def error_handler(&block)
+        fiber = ::Fiber.current
+        raise NoContextException unless fiber.respond_to? :__context__
+        context = fiber.__context__
+        begin_rescue_ensure = BeginRescueEnsure.new(:parent => context.get_closest_containing_scope)
+        bge = BeginRescueEnsureWrapper.new(block, begin_rescue_ensure)
+        context << bge
+        context << begin_rescue_ensure
+        begin_rescue_ensure
+      end
+
+      # @param block
+      #   A code block, which is passed within a {BeginRescueEnsureWrapper}, and which must define the
+      #   {BeginRescueEnsure#begin}, {BeginRescueEnsure#rescue}, and {BeginRescueEnsure#ensure} methods.
+      # @!visibility private
+      def _error_handler(&block)
+        error_handler(&block).result
+      end
+
+
+      def wait_for_function(function, *futures)
+        conditional = FiberConditionVariable.new
+        futures.flatten!
+        return nil if futures.empty?
+        result = futures.select(&:set?)
+        return futures.find(&:set?)if function.call(result, futures)
+        futures.each do |f|
+          f.on_set do |set_one|
+            result << set_one
+            conditional.broadcast if function.call(result, futures)
+          end
+        end
+        conditional.wait
+        result
+      end
+
+      # Blocks until *any* of the arguments are set.
+      #
+      # @param [Array] futures
+      #   A list of futures to wait for. The function will return when at least one of these is set.
+      #
+      # @return [Array]
+      #   A list of the set futures, in the order of being set.
+      #
+      def wait_for_any(*futures)
+        wait_for_function(lambda {|result, future_list| result.length >= 1 }, futures)
+      end
+
+      # Blocks until *all* of the arguments are set.
+      #
+      # @param [Array<Future>] futures
+      #   A list of futures to wait for. The function will return only when all of them are set.
+      #
+      # @return [Array]
+      #   A list of the set futures, in the order of being set.
+      #
+      def wait_for_all(*futures)
+        wait_for_function(lambda {|result, future_list| result.size == future_list.size}, futures)
+      end
+    end
+  end
+end

data/lib/aws/flow/simple_dfa.rb

@@ -0,0 +1,85 @@
+##
+# Copyright 2013 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License").
+# You may not use this file except in compliance with the License.
+# A copy of the License is located at
+#
+#  http://aws.amazon.com/apache2.0
+#
+# or in the "license" file accompanying this file. This file is distributed
+# on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+# express or implied. See the License for the specific language governing
+# permissions and limitations under the License.
+##
+
+module AWS
+  module Flow
+    module Core
+
+      # Contains a Data Flow Analysis (DFA)-like framework, where transition functions can perform arbitrary computation
+      # before moving to the next state
+      module SimpleDFA
+        attr_accessor :transitions, :symbols, :states, :start_state
+
+        # Creates a new SimpleDFA instance.
+        #
+        # @param start_state
+        #   The state with which to start the framework.
+        #
+        def init(start_state)
+          include InstanceMethods
+          @start_state = start_state
+          @symbols = []
+          @states = []
+          @transitions = {}
+          @states << start_state
+        end
+
+        # @return the start state
+        #   The start state that was provided when this instance was created.
+        #
+        def get_start_state
+          @start_state
+        end
+
+        # @return [Array]
+        #   The list of all transitions that were added with {#add_transition}.
+        #
+        def get_transitions
+          @transitions
+        end
+
+        def define_general(state, &block)
+          @symbols.each do |symbol|
+            if @transitions[[state, symbol]].nil?
+              @transitions[[state, symbol]] = block
+            end
+          end
+        end
+
+        def add_transition(state, symbol, &block)
+          @symbols << symbol unless @symbols.include? symbol
+          @states << state unless @states.include? state
+          @transitions[[state, symbol]] = block
+        end
+
+        def uncovered_transitions
+          @states.product(@symbols) - @transitions.keys
+        end
+
+        module InstanceMethods
+          attr_accessor :current_state
+
+          def consume(symbol)
+            @current_state ||= self.class.get_start_state
+            func_to_call = self.class.get_transitions[[@current_state, symbol]]
+            raise "This is not a legal transition" unless func_to_call
+            func_to_call.call(self)
+          end
+        end
+      end
+
+    end
+  end
+end