aws-flow 1.0.8 → 1.0.9

data/lib/aws/flow/async_scope.rb

@@ -13,40 +13,43 @@
 # permissions and limitations under the License.
 ##
 
-# This module contains the Root of the heirarchy for calls into flow, the AsyncScope
+# This module contains the root of the hierarchy for calls into flow.
 
 module AWS
   module Flow
     module Core
 
+      # @api private
       def gate_by_version(version, method, &block)
         if RUBY_VERSION.send(method, version)
           block.call
         end
       end
 
-      # @!visibility private
+      # @api private
       class AsyncScope
         attr_accessor :stackTrace, :root, :failure, :root_context
 
+        # @api private
         def is_complete?
           @root_context.complete
         end
 
+        # @api private
         def get_closest_containing_scope
           @root_error_handler
         end
 
+        # @api private
         def cancel(error); @root_error_handler.cancel(error); end
 
+        # @api private
         def initialize(&block)
           @root_context = RootAsyncScope.new
 
-
-
           # 1 for the function that skips frames
           # 1 for the create function
-          # 1 for the the initialize of the backtrace
+          # 1 for the initialize of the backtrace
 
           # "./lib/aws/rubyflow/asyncBacktrace.rb:75:in `caller'"
           # "./lib/aws/rubyflow/asyncBacktrace.rb:21:in `create'"
@@ -62,11 +65,12 @@ module AWS
         end
 
         # Collects all the heirs of a task for use in async_stack_dump
+        # @api private
         def get_heirs
           @root_error_handler.get_heirs
         end
 
-        # Execute all queued tasks. If execution of those tasks results in addition of new tasks to the queue, execute
+        # Execute all queued tasks. If execution of those tasks results in the addition of new tasks to the queue, execute
         # them as well.
         #
         # Unless there are external dependencies or bugs in the tasks to be executed, a single call to this method
@@ -75,6 +79,7 @@ module AWS
         # @note In the presence of external dependencies, it is expected that {AsyncScope#eventLoop} is called every
         # time after a change in the state in a dependency can unblock asynchronous execution.
         #
+        # @api private
         def eventLoop
           #TODO Figure out when to raise Done raise "Done" if ! @root_task.alive?
           raise IllegalStateException, "Already complete" if is_complete?
@@ -82,7 +87,7 @@ module AWS
           # TODO Does this need to be taken care of? It's supposed to protect
           # against people having errors that are classes, so like, passing
           # Exception into cancel. We might want to just catch that at the
-          # entry point
+          # entry point.
           if @root_context.failure
             if @root_context.failure.respond_to? :message
               failure_message = @root_context.failure.message + "\n" +
@@ -96,17 +101,19 @@ module AWS
           return is_complete?
         end
 
+        # @api private
         def <<(task)
           @root_context << task
           task.parent = @root_context
         end
       end
 
-      # @!visibility private
+      # @api private
       class RootAsyncScope < FlowFiber
 
         attr_accessor :backtrace, :failure, :executor, :complete
 
+        # @api private
         def initialize(options = {}, &block)
           @parent = options[:parent_context]
           @daemon = options[:daemon]
@@ -118,7 +125,8 @@ module AWS
         end
 
         # The only thing that should be removed from the RootAsyncScope is the
-        # root BeginRescueEnsure, so upon removal we are complete
+        # root BeginRescueEnsure, so upon removal we are complete.
+        # @api private
         def remove(task)
           @complete = true
         end
@@ -126,21 +134,25 @@ module AWS
         # As with remove, the only thing that is under RootAsyncScope should be
         # the root BeginRescueEnsure, so upon failure we will be complete. Also
         # sets failure variable for later raising.
+        # @api private
         def fail(task, error)
           @failure = error
           @complete = true
         end
 
+        # @api private
         def <<(this_task)
           @executor << this_task
         end
 
-        # Reture self, a RootAsyncScope is the closest containing scope
+        # Return self, a RootAsyncScope is the closest containing scope.
+        # @api private
         def get_closest_containing_scope
           self
         end
 
-        # Call out to the AsyncEventLoop
+        # Call out to the AsyncEventLoop.
+        # @api private
         def eventLoop
           @executor.executeQueuedTasks
         end
@@ -149,6 +161,7 @@ module AWS
         private
         DELEGATED_METHODS = [:push, :<<, :enq, :empty?, :length, :size, :delete, :shift]
 
+        # @api private
         def method_missing(method_name, *args)
           if DELEGATED_METHODS.include? method_name
             @executor.send(method_name, *args)
@@ -158,30 +171,34 @@ module AWS
         end
       end
 
-      # @!visibility private
+      # @api private
       class AsyncEventLoop
 
+        # @api private
         def initialize
           @tasks = []
         end
 
+        # @api private
         def remove(task)
           @tasks.delete(task)
         end
         # TODO Make sure that it's okay to fail from the AsyncEventLoop, and that
-        # this is the correct behavior
+        # this is the correct behavior.
         def fail(task, error)
           raise error
         end
+
+        # @api private
         def <<(task)
           @tasks << task
 
         end
 
-
         # TODO should this be synchronized somehow?
 
-        # Actually executes the eventLoop
+        # Actually executes the eventLoop.
+        # @api private
         def executeQueuedTasks
           until @tasks.empty?
             task = @tasks.shift
@@ -189,7 +206,6 @@ module AWS
           end
         end
       end
-
     end
   end
 end

data/lib/aws/flow/begin_rescue_ensure.rb

@@ -20,16 +20,17 @@ module AWS
   module Flow
     module Core
 
-      # This class allows asynchronous error handling within the AWS Flow Framework for Ruby.  Calling
-      # {#begin}/{#rescue}/{#ensure} is similar to Ruby's native `begin`/`rescue`/`end` semantics.
+      # Enables asynchronous error handling within the AWS Flow Framework for Ruby. Calling {#begin}/{#rescue}/{#ensure}
+      # is similar to Ruby's native `begin`/`rescue`/`end` semantics.
+      #
       class BeginRescueEnsure < FlowFiber
 
         extend SimpleDFA
-        attr_accessor :parent, :begin_task, :ensure_task, :rescue_tasks,
-        :rescue_exceptions, :failure, :cancelled, :heirs, :nonDaemonHeirsCount, :executor, :result
+        attr_accessor :parent, :begin_task, :ensure_task, :rescue_hash,
+          :failure, :cancelled, :heirs, :nonDaemonHeirsCount, :executor, :result
         attr_reader :backtrace, :__context__
 
-        # Create a new BeginRescueEnsure object, with the provided options.
+        # Create a new `BeginRescueEnsure` object, with the provided options.
         #
         # @param options
         #   Options to set for the class.
@@ -37,13 +38,13 @@ module AWS
         # @option options [Object] :parent
         #   The parent object.
         #
+        # @api private
         def initialize(options = {})
           # We have two different arrays, rather than a hash,
           # because we want to ensure that we process the rescues in the order
           # they are written, and because prior to Ruby 1.9, hashes will not
           # return their elements in the order they were inserted.
-          @rescue_exceptions = []
-          @rescue_tasks = []
+          @rescue_hash = {}
           @parent = options[:parent] || Fiber.current.__context__
           @current = @parent
           @executor = @parent.executor
@@ -57,16 +58,16 @@ module AWS
         end
 
 
-        # @!visibility private
+        # @api private
         def is_daemon?
           false
         end
 
 
-        # @!visibility private
+        # @api private
         def <<(async_task)
           # Not going to include the promise to wait for, as it would appear that
-          # Fibers can wait on futures from their point of origin as part of their
+          # fibers can wait on futures from their point of origin as part of their
           # implementation, as opposed to adding the callback here.
           check_closed
           if ! @heirs.member? async_task
@@ -79,15 +80,15 @@ module AWS
           self
         end
 
-        # @!visibility private
+        # @api private
         def get_closest_containing_scope
-          # BRE's are special in that they act as a containing scope, so that things
-          # created in BRE's treat it as the parent, so that it can track the heirs
-          # correctly and close only when nonDaemonHeirsCount is 0
+          # BeginRescueEnsure's are special in that they act as a containing scope, so that things
+          # created in BeginRescueEnsure's treat it as the parent, so that it can track the heirs
+          # correctly and close only when nonDaemonHeirsCount is 0.
           self
         end
 
-        # @!visibility private
+        # @api private
         def check_closed
           raise IllegalStateException, @failure if @current_state == :closed
         end
@@ -100,6 +101,7 @@ module AWS
         # @param error
         #   The error associated with the failure.
         #
+        # @api private
         def fail(this_task, error)
           check_closed
           if ( ! (error.class <= CancellationException) || @failure == nil && !@daemondCausedCancellation)
@@ -109,38 +111,39 @@ module AWS
           end
           task_out = @heirs.delete?(this_task)
           raise "There was a task attempted to be removed from a BRE, when the BRE did not have that task as an heir" unless task_out
-          @nonDaemonHeirsCount -= 1 if ! this_task.is_daemon?
+          @nonDaemonHeirsCount -= 1 unless this_task.is_daemon?
           cancelHeirs
           update_state
         end
 
-        # Removes the task and updates the state
+        # Removes the task and updates the state.
         #
         # @param this_task
         #   The task to remove.
         #
+        # @api private
         def remove(this_task)
           check_closed
 
           task_out = @heirs.delete?(this_task)
           raise "There was a task attempted to be removed from a BRE, when the BRE did not have that task as an heir" unless task_out
-          @nonDaemonHeirsCount -= 1 if ! this_task.is_daemon?
+          @nonDaemonHeirsCount -= 1 unless this_task.is_daemon?
           update_state
         end
 
-        # @!visibility private
+        # @api private
         def cancelHeirs
           toCancel = @heirs.dup
           toCancel.each { |heir|  heir.cancel(@failure) }
         end
 
-        # @!visibility private
+        # @api private
         def merge_stacktraces(failure, this_backtrace, error)
           backtrace = AsyncBacktrace.create_from_exception(this_backtrace, error)
           failure.set_backtrace(backtrace.backtrace) if backtrace
         end
 
-        # @!visibility private
+        # @api private
         def cancel(error)
           if @current_state == :created
             @current_state = :closed
@@ -159,8 +162,8 @@ module AWS
           end
         end
 
-        # Actually runs the BRE, by going through the DFA with the symbol :run.
-        # @!visibility private
+        # Actually runs the BeginRescueEnsure, by going through the data flow analysis with the symbol :run.
+        # @api private
         def run
           this_failure = @failure
           begin
@@ -178,13 +181,13 @@ module AWS
           end
         end
 
-        # @!visibility private
+        # @api private
         def alive?
           @current_state != :closed
         end
 
-        # Updates the state based on the most recent transitions in the DFA
-        # @!visibility private
+        # Updates the state based on the most recent transitions in the data flow analysis.
+        # @api private
         def update_state
           #TODO ? Add the ! @executed part
           #return if @current_state == :closed || ! @executed
@@ -199,7 +202,7 @@ module AWS
           end
         end
 
-        # @!visibility private
+        # @api private
         def get_heirs
           # TODO fix this so it returns string instead of printing to stdout
           str =  "I am a BeginRescueEnsure with #{heirs.length} heirs
@@ -209,7 +212,7 @@ module AWS
           # (@heirs.each(&:get_heirs) + [self]).flatten
         end
 
-        # @!visibility private
+        # @api private
         init(:created)
         {
           [:created, :run] => lambda { |bre| bre.current_state = :begin; bre.run },
@@ -226,15 +229,15 @@ module AWS
             # Emulates the behavior of the actual Ruby rescue, see
             # http://Ruby-doc.org/docs/ProgrammingRuby/html/tut_exceptions.html
             # for more details
-            bre.rescue_exceptions.each_index do |index|
+            bre.rescue_hash.each_pair do |exception_class, exception_function|
               this_failure = bre.failure
               failure_class = bre.failure.is_a?(Exception) ? bre.failure.class : bre.failure
-              if failure_class <=  bre.rescue_exceptions[index]
+              # TODO change <=  to something more explicit about subclass check
+              unless exception_class.select { |x| failure_class <= x }.empty?
                 bre.result.unset
                 bre.failure = nil
-                task = bre.rescue_tasks[index]
+                task = exception_function
                 bre << Task.new(bre) { bre.result.set(task.call(this_failure)) }
-                # bre.rescue_tasks[index].call(this_failure)
                 break
               end
             end
@@ -257,7 +260,7 @@ module AWS
         # That is, any transition from closed leads back to itself
         define_general(:closed) { |t| t.current_state = :closed }
 
-        # Binds the block to the a lambda to be called when we get to the begin part of the DFA
+        # Binds the block to a lambda to be called when we get to the begin part of the data flow analysis.
         #
         # @param block
         #   The code block to be called when asynchronous *begin* starts.
@@ -268,24 +271,24 @@ module AWS
           @begin_task = Task.new(self) { @result.set(block.call) }
         end
 
-        # Binds the block to the a lambda to be called when we get to the rescue part of the DFA
+        # Binds the block to a lambda to be called when we get to the rescue part of the DFA
         #
-        # @param error_type
-        #   The error type.
+        # @param error_types
+        #   The error types.
         #
         # @param block
         #   The code block to be called when asynchronous *rescue* starts.
         #
-        def rescue(error_type, block)
+        def rescue(error_types, block)
+          error_types = [error_types] unless error_types.is_a? Array
           this_task = lambda { |failure| block.call(failure) }
-          if @rescue_exceptions.include? error_type
-            raise "You have already registered #{error_type}!"
+          if @rescue_hash.key? error_types
+            raise "You have already registered #{error_types}"
           end
-          @rescue_exceptions << error_type
-          @rescue_tasks << this_task
+          @rescue_hash[error_types] = this_task
         end
 
-        # Binds the block to the a lambda to be called when we get to the ensure part of the DFA
+        # Binds the block to a lambda to be called when we get to the ensure part of the data flow analysis.
         #
         # @param block
         #   The code block to be called when asynchronous *ensure* starts.
@@ -300,7 +303,7 @@ module AWS
         end
       end
 
-      # Class to ensure that all the inner guts of BRE aren't exposed. This function is passed in when error_handler is
+      # Ensures that {BeginRescueEnsure} isn't exposed directly. This function is passed in when {#error_handler} is
       # called, like this:
       #
       #     error_handler do |t|
@@ -309,21 +312,23 @@ module AWS
       #       t.ensure { trace << t.begin_task }
       #     end
       #
-      # The *t* that is passed in is actually a {BeginRescueEnsureWrapper}, which will only pass begin/rescue/ensure
-      # onto the {BeginRescueEnsure} class itself.
+      # In this example, *t* is a {BeginRescueEnsureWrapper} which passes the begin/rescue/ensure calls to the
+      # {BeginRescueEnsure} class itself.
       #
+      # @api private
       class BeginRescueEnsureWrapper < FlowFiber
-        # Also has a few methods to ensure Fiber-ness, such as get_heirs and cancel.
+        # Also has a few methods to ensure fiber-ness, such as get_heirs and cancel.
         attr_reader :__context__
 
-        # Creates a new BeginRescueEnsureWrapper instance.
+        # Creates a new `BeginRescueEnsureWrapper` instance.
         #
         # @param block
-        #   A code block to be called.
+        #   *Required*. A code block to be called.
         #
         # @param begin_rescue_ensure
         #   The {BeginRescueEnsure} instance to wrap.
         #
+        # @api private
         def initialize(block, begin_rescue_ensure)
           @beginRescueEnsure = begin_rescue_ensure
           @__context__ = @beginRescueEnsure
@@ -337,26 +342,24 @@ module AWS
           end
         end
 
-        # @!visibility private
+        # @api private
         def get_heirs
           p "I am a BREWrapper"
           return
         end
 
+        # @api private
         def cancel(error_type)
           @beginRescueEnsure.parent.cancel(self)
         end
 
-        # @!visibility private
-        #
-        # @return [false]
-        #   Always returns `false`.
-        #
+        # @api private
         def is_daemon?
           false
         end
 
         # Gets the parent of the {BeginRescueEnsure} instance held by this class.
+        # @api private
         def get_closest_containing_scope
           @beginRescueEnsure.parent
         end
@@ -368,15 +371,17 @@ module AWS
         def ensure(&block) @beginRescueEnsure.ensure(block) end
 
         # (see BeginRescueEnsure#rescue)
-        def rescue(error_type, &block)
-          @beginRescueEnsure.rescue(error_type, block)
+        def rescue(*error_types, &block)
+          @beginRescueEnsure.rescue(error_types, block)
         end
 
         private
         attr_accessor :beginRescueEnsure
       end
 
+      # @api private
       class DaemonBeginRescueEnsure < BeginRescueEnsure
+        # @api private
         def is_daemon?
           true
         end