aws-flow-core 1.0.0

data/lib/aws/flow/tasks.rb

@@ -0,0 +1,405 @@
+##
+# 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.
+##
+
+# Contains all the task methods, which allow arbitrary blocks of code to be run asynchronously
+
+module AWS
+  module Flow
+    module Core
+      class Task < FlowFiber
+        attr_reader :result, :block
+        attr_accessor :backtrace, :__context__, :parent
+
+        # Creates a new Task.
+        #
+        # @param __context__
+        #   A Task needs a reference to the __context__ that created it so that when the "task" macro is called it can
+        #   find the __context__ which the new Task should be added to.
+        #
+        # @param block
+        #   A block of code that will be run by the task.
+        #
+        def initialize(__context__, &block)
+          @__context__ = __context__
+          @result = Future.new
+          @block = block
+
+          # Is the task alive?
+          def alive?
+            super && !@cancelled
+            #!!@alive# && !@cancelled
+          end
+
+          # @return
+          #   The executor for this task.
+          def executor
+            @__context__.executor
+          end
+
+          super() do
+            begin
+              # Not return because 1.9 will freak about local jump problems if you
+              # try to return, as this is inside a block
+              next if @cancelled
+              @result.set(lambda(&block).call)
+              next if @cancelled
+              @__context__.remove(self)
+            rescue Exception => e
+              if @backtrace != e
+                backtrace = AsyncBacktrace.create_from_exception(@backtrace, e)
+                e.set_backtrace(backtrace.backtrace) if backtrace
+              end
+              @__context__.fail(self, e)
+            ensure
+            end
+          end
+        end
+
+        #
+        # Passes the get_heirs calls to the context, to ensure uniform handling of get_heirs
+        #
+        def get_heirs
+          @__context__.get_heirs
+        end
+
+        #
+        # Returns true/false, depending on if we are in a daemon task or not
+        #
+        def is_daemon?
+          return false
+        end
+
+        # Used by Future#signal to schedule the task for re-evaluation.
+        #
+        # This will simply add the task back to the list of things to be run in the parent's event loop.
+        #
+        def schedule
+          @__context__ << self
+        end
+
+        # Cancel will prevent the execution of this particular task, if possible
+        #
+        # @param error
+        #   The error that is the cause of the cancellation
+        #
+        def cancel(error)
+          @cancelled = true
+          @__context__.remove(self)
+        end
+
+        # Fails the given task with the specified error.
+        #
+        # @param error
+        #   The error that is the cause of the cancellation
+        #
+        # @!visibility private
+        def fail(this_task, error)
+          @__context__.fail(this_task, error)
+        end
+        # def fail(this_task, error)
+        #   raise error
+        # end
+
+        # Adds a task to this task's context
+        #
+        # @param this_task
+        #   The task to add.
+        #
+        def <<(this_task)
+          @__context__.parent << this_task
+        end
+
+        # Removes a task from this task's context
+        #
+        # @param this_task
+        #   The task to remove.
+        #
+        def remove(this_task)
+          @__context__.remove(this_task)
+        end
+
+
+      end
+
+
+      # Similar to a regular Task in all functioning except that it is not assured a chance to execute. Whereas a
+      # begin/run/execute block cannot be closed out while there are still nonDaemonHeirs, it can happily entered the
+      # closed state with daemon heirs, making them essentially unrunnable.
+      class DaemonTask < Task
+
+        def is_daemon?
+          return true
+        end
+
+      end
+
+      # External Tasks are used to bridge asynchronous execution to external asynchronous APIs or events. It is passed a block, like so
+      #
+      #     external_task do |t|
+      #       t.cancellation_handler { |h, cause| h.fail(cause) }
+      #       t.initiate_task { |h| trace << :task_started; h.complete; }
+      #     end
+      #
+      # The {ExternalTask#initiate_task} method is expected to call an external API and return without blocking.
+      # Completion or failure of the external task is reported through ExternalTaskCompletionHandle, which is passed into
+      # the initiate_task and cancellation_handler blocks. The cancellation handler, defined in the same block as the
+      # initiate_task, is used to report the cancellation of the external task.
+      #
+      class ExternalTask < FlowFiber
+        attr_reader :block
+        attr_accessor :cancelled, :inCancellationHandler, :parent, :backtrace, :__context__
+
+
+        # Will always be false, provides a common api for BRE's to ensure they are maintaining their nonDaemonHeirsCount
+        # correctly
+        # @!visibility private
+        def is_daemon?
+          false
+        end
+
+        #
+        #  Passes the get_heirs calls to the context, to ensure uniform handling of
+        #  get_heirs
+        #
+        # @!visibility private
+        def get_heirs
+          @__context__.get_heirs
+        end
+
+        # @!visibility private
+        def initialize(options = {}, &block)
+          @inCancellationHandler = false
+          @block = block
+          # TODO: What should the default value be?
+          @parent = options[:parent]
+          @handle = ExternalTaskCompletionHandle.new(self)
+          block.call(self)
+        end
+
+        # This method is here because the way we create ExternalTasks is a little
+        # tricky - if the parent isn't passed in on construction(as is the case with
+        # the external_task function), then the parent will only be set after
+        # ExternalTask#initialize is called. We'd prefer to set it in the initiailze,
+        # however, the backtrace relies on the parent's backtrace, and so we cannot do
+        # that. Instead, we use this method to lazily create it, when it is
+        # called. The method itself simply sets the backtrace to the the
+        # make_backtrace of the parent's backtrace, if the backtrace is not already
+        # set, and will otherwise simply return the backtrace
+        # @!visibility private
+        def backtrace
+          @backtrace ||= make_backtrace(@parent.backtrace)
+        end
+
+        # Add a task which removes yourself, and pass it through the parents executor
+        # @!visibility private
+        def remove_from_parent
+          @__context__.executor << FlowFiber.new { @parent.remove(self) }
+        end
+
+        # Add a task which fails yourself with the suppiled error, and pass it through
+        # the parents executor
+        # @!visibility private
+        def fail_to_parent(error)
+          @__context__.executor << FlowFiber.new { @parent.fail(self, error) }
+        end
+
+
+        # Part of the interface provided by Fiber, has to overridden to properly
+        # reflect that an ExternalTasks alive-ness relies on it's
+        # ExternalTaskCompletionHandle
+        # @!visibility private
+        def alive?
+          ! @handle.completed
+        end
+
+        # @!visibility private
+        def cancel(cause)
+          return if @cancelled
+          return if @handle.failure != nil || @handle.completed
+          @cancelled = true
+          if @cancellation_task != nil
+            begin
+              @inCancellationHandler = true
+              @cancellation_task.call(cause)
+            rescue Exception => e
+              if ! self.backtrace.nil?
+                backtrace = AsyncBacktrace.create_from_exception(@backtrace, e)
+                e.set_backtrace(backtrace.backtrace) if backtrace
+              end
+              @handle.failure = e
+            ensure
+              @inCancellationHandler = false
+              if ! @handle.failure.nil?
+                fail_to_parent(@handle.failure)
+              elsif @handle.completed
+                remove_from_parent
+              end
+            end
+          else
+            remove_from_parent
+          end
+        end
+
+        # Store the cancellation handler block passed in for later reference
+        # @!visibility private
+        def cancellation_handler(&block)
+          @cancellation_task = lambda { |cause| block.call(@handle, cause) }
+        end
+
+        # Store the block passed in for later
+        # @!visibility private
+        def initiate_task(&block)
+          @initiation_task = lambda { block.call(@handle) }
+        end
+
+        # From the interface provided by Fiber, will execute the External Task
+        # @!visibility private
+        def resume
+          return if @cancelled
+          begin
+            @cancellation_handler = @initiation_task.call
+          rescue Exception => e
+            backtrace = AsyncBacktrace.create_from_exception(self.backtrace, e)
+            e.set_backtrace(backtrace.backtrace) if backtrace
+            @parent.fail(self, e)
+          end
+        end
+      end
+
+      # Used to complete or fail an external task initiated through
+      # ExternalTask#initiate_task, and thus handles the logic of what to do when the
+      # external task is failed.
+      # @!visibility private
+      class ExternalTaskCompletionHandle
+        attr_accessor :completed, :failure, :external_task
+
+        # @!visibility private
+        def initialize(external_task)
+          @external_task = external_task
+        end
+
+        # Will merge the backtrace, set the @failure, and then fail the task from the parent
+        # @!visibility private
+        #
+        # @param error
+        #   The exception to fail on
+        #
+        # @raise IllegalStateException
+        #   Raises if failure hasn't been set, or if the task is already completed
+        #
+        # @!visibility private
+        def fail(error)
+          if ! @failure.nil?
+            raise IllegalStateException, "Invalid ExternalTaskCompletionHandle"
+          end
+          if @completed
+            raise IllegalStateException, "Already completed"
+          end
+          #TODO Might want to flip the logic to only alert if variable is set
+          if @stacktrace.nil?
+            if ! @external_task.backtrace.nil?
+              backtrace = AsyncBacktrace.create_from_exception(@external_task.backtrace, error)
+              error.set_backtrace(backtrace.backtrace) if backtrace
+            end
+          end
+          @failure = error
+          if ! @external_task.inCancellationHandler
+            @external_task.fail_to_parent(error)
+          end
+        end
+
+        # Set's the task to complete, and removes it from it's parent
+        #
+        # @raise IllegalStateException
+        #   If the failure hasn't been set, or if the task is already completed
+        #
+        # @!visibility private
+        def complete
+          if ! failure.nil?
+            raise IllegalStateException, ""
+          end
+
+          if @completed
+            raise IllegalStateException, "Already Completed"
+          end
+          @completed = true
+          @external_task.remove_from_parent if ! @external_task.inCancellationHandler
+        end
+      end
+
+      # TaskContext is the class that holds some meta-information for tasks, and which stores the parent link for tasks.
+      # It seperates some of the concerns between tasks and what they have to know to follow back up the chain.
+      #
+      #  All the methods here will simply delegate calls, either up to the parent, or down to the task
+      # @!visibility private
+      class TaskContext
+
+        attr_accessor :daemon, :parent, :backtrace, :cancelled
+
+        def initialize(options = {})
+          @parent = options[:parent]
+          @task = options[:task]
+          @task.__context__ = self
+          @non_cancelling = options[:non_cancelling]
+          @daemon = options[:daemon]
+        end
+
+        # @!visibility private
+        def get_closest_containing_scope
+          @task
+          # @ parent
+        end
+
+        # @!visibility private
+        def alive?
+          @task.alive?
+        end
+
+        # @!visibility private
+        def executor
+          @parent.executor
+        end
+
+        # @!visibility private
+        def get_heirs
+          str = "I am a #{@task.class}
+        and my block looks like #{@task.block}"
+        end
+
+        # @!visibility private
+        def fail(this_task, error)
+          @parent.fail(this_task, error)
+        end
+
+        # @!visibility private
+        def remove(thread)
+          @parent.remove(thread)
+        end
+
+        # @!visibility private
+        def cancel(error_type)
+          @task.cancelled = true
+          @parent.cancel(self)
+        end
+
+        # @!visibility private
+        def <<(task)
+          @parent << task
+        end
+
+      end
+    end
+  end
+end

data/test/aws/async_backtrace_spec.rb

@@ -0,0 +1,41 @@
+##
+# 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.
+##
+
+def validate_stacktrace_content(method_to_call_on_async_backtrace, thing_to_look_for, should_it_be_there)
+    it "makes sure that any of #{thing_to_look_for.join", "} #{should_it_be_there} be printed when we call #{method_to_call_on_async_backtrace} on AsyncBacktrace" do
+    AsyncBacktrace.enable
+    AsyncBacktrace.send(method_to_call_on_async_backtrace)
+    scope = AsyncScope.new do
+    error_handler do |t|
+      t.begin { raise StandardError.new }
+      t.rescue(IOError) {}
+    end
+  end
+  begin
+    scope.eventLoop
+  rescue Exception => e
+    matching_lines = thing_to_look_for.select { |part| e.backtrace.to_s.include? part.to_s }
+
+    matching_lines.send(should_it_be_there, be_empty)
+    end
+  end
+end
+
+describe AsyncBacktrace do
+  validate_stacktrace_content(:enable, [:continuation], :should_not)
+  validate_stacktrace_content(:disable, [:continuation], :should)
+  validate_stacktrace_content(:enable_filtering, $RUBY_FLOW_FILES, :should)
+  validate_stacktrace_content(:disable_filtering, $RUBY_FLOW_FILES, :should_not)
+end

data/test/aws/async_scope_spec.rb

@@ -0,0 +1,118 @@
+##
+# 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.
+##
+
+describe AsyncScope do
+
+  it "makes sure that basic AsyncScoping works" do
+    trace = []
+    this_scope = AsyncScope.new() do
+      task { trace << :inside_task}
+    end
+    trace.should == []
+    this_scope.eventLoop
+    trace.should == [:inside_task]
+  end
+
+  context "empty AsyncScope" do
+    let(:scope) { AsyncScope.new }
+    let(:trace) { [] }
+
+    it "adds tasks like a queue" do
+      scope << Task.new(scope.root_context) { trace << :task }
+      scope.eventLoop
+      trace.should == [:task]
+    end
+
+    it "adds a task if given one on construction" do
+      scope = AsyncScope.new { trace << :task }
+      scope.eventLoop
+      trace.should == [:task]
+    end
+
+
+    it "runs a task asynchronously" do
+      scope << Task.new(scope.root_context) { trace << :inner }
+      trace << :outer
+      scope.eventLoop
+      trace.should == [:outer, :inner]
+    end
+
+    it "runs multiple tasks in order" do
+      scope << Task.new(scope.root_context) { trace << :first_task }
+      scope << Task.new(scope.root_context) { trace << :second_task }
+      scope.eventLoop
+      trace.should == [:first_task, :second_task]
+    end
+
+    it "resumes tasks after a Future is ready" do
+      f = Future.new
+      scope = AsyncScope.new do
+        task do
+          trace << :first
+          f.get
+          trace << :fourth
+        end
+
+        task do
+          trace << :second
+          f.set(:foo)
+          trace << :third
+        end
+      end
+      scope.eventLoop
+      trace.should == [:first, :second, :third, :fourth]
+    end
+
+    it "tests to make sure that scopes complete after an event loop" do
+      scope = AsyncScope.new do
+        error_handler do |t|
+          t.begin do
+            x = Future.new
+            y = Future.new
+            error_handler do |t|
+              t.begin {}
+              t.ensure { x.set }
+            end
+            x.get
+            error_handler do |t|
+              t.begin {}
+              t.ensure { y.set }
+            end
+            y.get
+            error_handler do |t|
+              t.begin {}
+              t.ensure {}
+            end
+          end
+        end
+      end
+
+      completed = scope.eventLoop
+      completed.should == true
+    end
+    it "ensures you can cancel an async scope " do
+      condition = FiberConditionVariable.new
+      @task = nil
+      scope = AsyncScope.new do
+        task do
+          condition.wait
+        end
+      end
+      scope.eventLoop
+      scope.cancel(CancellationException.new)
+      expect { scope.eventLoop }.to raise_error CancellationException
+    end
+  end
+end