aws-flow 1.0.8 → 1.0.9

data/lib/aws/decider/async_retrying_executor.rb

@@ -92,7 +92,7 @@ module AWS
     # Represents a policy for retrying failed tasks.
     class RetryPolicy
 
-      # Creates a new RetryPolicy instance
+      # Creates a new `RetryPolicy` instance.
       #
       # @param retry_function
       #   The method to be called for each retry attempt.
@@ -134,7 +134,7 @@ module AWS
          #return (!@exceptions_to_exclude.include?(failure) && @exceptions_to_include.include?(failure))
       end
 
-      # Schedules a new retry attempt
+      # Schedules a new retry attempt.
       #
       # @param first_attempt
       #
@@ -156,7 +156,6 @@ module AWS
         end
         return -1 if failure == nil
 
-
         # For reverse compatbility purposes, we must ensure that this function
         # can take 3 arguments. However, we must also consume options in order
         # for the default retry function to work correctly. Because we support
@@ -168,8 +167,8 @@ module AWS
         retry_seconds = @retry_function.call(*call_args)
         # Check to see if we should jitter or not and pass in the jitter
         # function to retry function accordingly.
-        if @should_jitter
-           retry_seconds += @jitter_function.call(execution_id, retry_seconds/2)
+        if @should_jitter && retry_seconds > 0
+          retry_seconds += @jitter_function.call(execution_id, retry_seconds/2)
         end
         return retry_seconds
       end

data/lib/aws/decider/data_converter.rb

@@ -15,8 +15,8 @@
 
 module AWS
   module Flow
-    # We special case exception for now, as YAML doesn't propagate backtraces
-    # properly, and they are very handy for debugging
+    # Converts an object to YAML. Exceptions are handled differently because YAML doesn't propagate backtraces
+    # properly, and they are very handy for debugging.
     class YAMLDataConverter
 
       def dump(object)

data/lib/aws/decider/decider.rb

@@ -16,7 +16,7 @@
 module AWS
   module Flow
 
-    # A MethodPair groups a method name with an associated data converter.
+    # Groups a method name with an associated data converter.
     class MethodPair
       # The method name for the method pair.
       attr_accessor :method_name
@@ -61,17 +61,19 @@ module AWS
         @workflow_context = workflow_context
       end
 
-      # Handler for the ExternalWorkflowExecutionCancelRequested event.
+      # Handler for the `ExternalWorkflowExecutionCancelRequested` event.
       #
-      # @param [Object] event The event instance.
+      # @param [Object] event
+      #   The event instance.
       #
       def handle_external_workflow_execution_cancel_requested(event)
         # NOOP
       end
 
-      # Handler for the ChildWorkflowExecutionCanceled event.
+      # Handler for the `ChildWorkflowExecutionCanceled` event.
       #
-      # @param [Object] event The event instance.
+      # @param [Object] event
+      #   The event instance.
       #
       def handle_child_workflow_execution_canceled(event)
         handle_event(event,
@@ -87,11 +89,11 @@ module AWS
       end
 
 
-      # Handler for the ChildWorkflowExecutionCompleted event.
+      # Handler for the `ChildWorkflowExecutionCompleted` event.
       #
-      # @param [Object] event The event instance.
+      # @param [Object] event
+      #   The event instance.
       #
-
       def handle_child_workflow_execution_completed(event)
         handle_event(event,
                      {:id_methods => [:workflow_execution, :workflow_id],
@@ -101,9 +103,10 @@ module AWS
                      })
       end
 
-      # Handler for the ChildWorkflowExecutionFailed event.
+      # Handler for the `ChildWorkflowExecutionFailed` event.
       #
-      # @param [Object] event The event instance.
+      # @param [Object] event
+      #   The event instance.
       #
       def handle_child_workflow_execution_failed(event)
         handle_event(event,
@@ -126,9 +129,10 @@ module AWS
       end
 
 
-      # Handler for the ChildWorkflowExecutionStarted event.
+      # Handler for the `ChildWorkflowExecutionStarted` event.
       #
-      # @param [Object] event The event instance.
+      # @param [Object] event
+      #   The event instance.
       #
       def handle_child_workflow_execution_started(event)
         handle_event(event,
@@ -141,9 +145,10 @@ module AWS
                      })
       end
 
-      # Handler for the ChildWorkflowExecutionTerminated event.
+      # Handler for the `ChildWorkflowExecutionTerminated` event.
       #
-      # @param [Object] event The event instance.
+      # @param [Object] event
+      #   The event instance.
       #
       def handle_child_workflow_execution_terminated(event)
         handle_event(event,
@@ -157,9 +162,10 @@ module AWS
                      })
       end
 
-      # Handler for the ChildWorkflowExecutionTimedOut event.
+      # Handler for the `ChildWorkflowExecutionTimedOut` event.
       #
-      # @param [Object] event The event instance.
+      # @param [Object] event
+      #   The event instance.
       #
       def handle_child_workflow_execution_timed_out(event)
         handle_event(event,
@@ -173,9 +179,10 @@ module AWS
                      })
       end
 
-      # Handler for the ExternalWorkflowExecutionSignaled event.
+      # Handler for the `ExternalWorkflowExecutionSignaled` event.
       #
-      # @param [Object] event The event instance.
+      # @param [Object] event
+      #   The event instance.
       #
       def handle_external_workflow_execution_signaled(event)
         signal_id = @decision_helper.signal_initiated_event_to_signal_id[event.attributes[:initiated_event_id]]
@@ -188,9 +195,10 @@ module AWS
         end
       end
 
-      # Handler for the SignalExternalWorkflowExecutionFailed event.
+      # Handler for the `SignalExternalWorkflowExecutionFailed` event.
       #
-      # @param [Object] event The event instance.
+      # @param [Object] event
+      #   The event instance.
       #
       def handle_signal_external_workflow_execution_failed(event)
         handle_event(event, {
@@ -205,9 +213,10 @@ module AWS
                      })
       end
 
-      # Handler for the StartChildWorkflowExecutionFailed event.
+      # Handler for the `StartExternalWorkflowExecutionFailed` event.
       #
-      # @param [Object] event The event instance.
+      # @param [Object] event
+      #   The event instance.
       #
       def handle_start_child_workflow_execution_failed(event)
         handle_event(event, {
@@ -225,11 +234,10 @@ module AWS
       end
     end
 
-
     # Types and methods related to workflow execution. Extend this to implement a workflow decider.
     #
     # @!attribute version
-    #   Sets or returns the Decider version.
+    #   Sets or returns the decider version.
     #
     # @!attribute options
     #   Sets or returns the {WorkflowOptions} for this decider.
@@ -249,10 +257,9 @@ module AWS
         base.send :include, InstanceMethods
       end
 
-      #  This method is for internal use only and may be changed or removed
-      #   without prior notice.  Use {#workflows} instead. Set the entry point
-      #   in the {#workflow} method when creating a new workflow.
-      # @!visibility private
+      # @deprecated Set the entry point with {Workflows#workflow} instead.
+      #
+      # @api private
       def entry_point(input=nil)
         if input
           @entry_point = input
@@ -267,10 +274,8 @@ module AWS
         raise "You must set an entry point on the workflow definition"
       end
 
-      #  This method is for internal use only and may be changed or removed
-      # without prior notice.  Use {#workflows} instead.
-      # Set the version in the {WorkflowOptions} passed in to the {#workflow} method.
-      # @!visibility private
+      # @deprecated Set the version in the {WorkflowOptions} passed in to the {#workflow} method.
+      # @api private
       def version(arg = nil)
         if arg
           self.workflows.each { |workflow| workflow.version = arg }
@@ -321,10 +326,10 @@ module AWS
       end
 
 
-      # @!visibility private
+      # @api private
       def _options; self.workflows.map(&:options); end
 
-      # Defines a new workflow
+      # Defines a new workflow.
       #
       # @param entry_point
       #   The entry point (method) that starts the workflow.
@@ -341,7 +346,7 @@ module AWS
       end
 
       # @return [MethodPair]
-      #   A {MethodPair} object
+      #   A {MethodPair} object.
       #
       def get_state_method(get_state_method = nil, options = {})
         data_converter = options[:data_converter]
@@ -375,7 +380,7 @@ module AWS
       end
 
 
-      # Instance methods for {DecisionContext}
+      # Instance methods for {DecisionContext}.
       module InstanceMethods
 
         # Returns the {DecisionContext} instance.
@@ -389,7 +394,7 @@ module AWS
         # Returns the workflow ID.
         #
         # @return
-        #   The workflow ID
+        #   The workflow ID.
         #
         def workflow_id
           self.decision_context.workflow_context.decision_task.workflow_execution.workflow_id
@@ -451,7 +456,7 @@ module AWS
         # @deprecated
         #   Use {#create_timer_async} instead.
         #
-        # @!visibility private
+        # @api private
         def async_create_timer(delay_seconds, &block)
           task { self.decision_context.workflow_clock.create_timer(delay_seconds, block) }
         end
@@ -482,12 +487,12 @@ module AWS
             continue_as_new_options.input = input
           end
           known_workflows = self.class.workflows
-          # If there is only one workflow, we can unambiguously say that we should use that one
+          # If there is only one workflow, we can unambiguously say that we should use that one.
 
           if known_workflows.length == 1
             continue_as_new_options.precursors << known_workflows.first.options
           end
-          # If we can find a name that matches, use that one
+          # If we can find a name that matches, use that one.
           if continue_as_new_options.execution_method
             matching_option = self.class.workflows.map(&:options).find {|x| x.execution_method == continue_as_new_options.execution_method }
             continue_as_new_options.precursors << matching_option unless matching_option.nil?
@@ -501,7 +506,7 @@ module AWS
     # without prior notice.
     #  Use {Workflows} instead.
     #
-    # @!visibility private
+    # @api private
     module Decider
       include Workflows
 

data/lib/aws/decider/decision_context.rb

@@ -27,7 +27,7 @@
      end
 
 
-     # The context for a workflow
+     # The context for a workflow.
      class WorkflowContext
 
        attr_accessor :continue_as_new_options
@@ -37,7 +37,7 @@
        # The {WorkflowClock} for this workflow.
        attr_accessor :workflow_clock
 
-       # Creates a new `WorkflowContext`
+       # Creates a new `WorkflowContext`.
        #
        # @param decision_task
        #   The decision task method for this workflow. This is accessible after instance creation by using the

data/lib/aws/decider/exceptions.rb

@@ -88,7 +88,7 @@ module AWS
       # Creates a new `ChildWorkflowFailedException`
       #
       # @param event_id
-      #   The event id for the exception.
+      #   The event ID for the exception.
       #
       # @param execution
       #   The child workflow execution that raised the exception.
@@ -112,7 +112,7 @@ module AWS
 
 
     # This exception is used by the framework internally to communicate activity failure. When an activity fails due to
-    # an unhandled exception, it is wrapped in ActivityFailureException and reported to Amazon SWF. You need to deal
+    # an unhandled exception, it is wrapped in {ActivityFailureException} and reported to Amazon SWF. You need to deal
     # with this exception only if you use the activity worker extensibility points. Your application code will never
     # need to deal with this exception.
     #
@@ -139,12 +139,12 @@ module AWS
     # This exception is thrown if an activity was timed out by Amazon SWF. This could happen if the activity task could
     # not be assigned to the worker within the require time period or could not be completed by the worker in the
     # required time. You can set these timeouts on the activity using the @ActivityRegistrationOptions annotation or
-    # using the ActivitySchedulingOptions parameter when calling the activity method.
+    # using the `ActivitySchedulingOptions` parameter when calling the activity method.
     #
     # @abstract An exception raised when the activity task has timed out.
     class ActivityTaskTimedOutException < ActivityFailureException
 
-      # Creates a new ActivityTaskTimeoutException
+      # Creates a new `ActivityTaskTimeoutException`.
       def initialize(id, activity_id, reason, details)
         @id = id
         @activity_id = activity_id
@@ -159,14 +159,14 @@ module AWS
     end
 
     # Unhandled exceptions in activities are reported back to the workflow implementation by throwing an
-    # `ActivityTaskFailedException`. The original exception can be retrieved from the reason attribute of this
+    # `ActivityTaskFailedException`. The original exception can be retrieved from the `reason` attribute of this
     # exception. The exception also provides information in the `details` attribute that is useful for debugging
     # purposes, such as the unique activity identifier in the history.
     #
     # @abstract An exception raised when the activity task has failed.
     class ActivityTaskFailedException < ActivityFailureException
       attr_accessor :cause, :details
-      # Creates a new ActivityTaskFailedException
+      # Creates a new `ActivityTaskFailedException`.
       def initialize(id, activity_id, reason, details)
         @id = id
         @activity_id = activity_id

data/lib/aws/decider/executor.rb

@@ -19,6 +19,7 @@ require 'logger'
 module AWS
   module Flow
 
+    # @api private
     class LogMock
       attr_accessor :log_level
       def initialize()
@@ -39,6 +40,7 @@ module AWS
     end
     class RejectedExecutionException < Exception; end
 
+    # @api private
     class ForkingExecutor
 
       class << self
@@ -47,12 +49,12 @@ module AWS
       attr_accessor :max_workers, :pids, :is_shutdown
 
       def initialize(options = {})
-        @log = options[:logger]
-        @log ||= Logger.new("#{Dir.tmpdir}/forking_log")
+        unless @log = options[:logger]
+          @log = Logger.new("#{Dir.tmpdir}/forking_log")
+          @log.level = options[:log_level] || Logger::ERROR
+          @log.info("LOG INITIALIZED")
+        end
         @semaphore = Mutex.new
-        log_level = options[:log_level] || 4
-        @log.level = Logger::DEBUG
-        @log.info("LOG INITIALIZED")
         @max_workers = options[:max_workers] || 1
         @pids = []
         @is_shutdown = false
@@ -114,6 +116,7 @@ module AWS
         end
       end
 
+      # @api private
       def block_on_max_workers
         @log.debug "block_on_max_workers workers=#{@pids.size}, max_workers=#{@max_workers}"
         if @pids.size >= @max_workers
@@ -127,18 +130,19 @@ module AWS
 
       private
 
-      # Remove all child processes from @pids list that have finished
-      # Block for at least one child to finish if block argument is set to true
+      # Removes all child processes from @pids list that have finished.
+      # Block for at least one child to finish if block argument is set to `true`.
+      # @api private
       def remove_completed_pids(block=false)
         loop do
           # waitpid2 throws an Errno::ECHILD if there are no child processes,
-          # so we don't even call it if there aren't any pids to wait on
+          # so we don't even call it if there aren't any pids to wait on.
           break if @pids.empty?
-          # non-blocking wait - only returns a non-null pid
-          # if the child process has exited
+          # Non-blocking wait only returns a non-null pid
+          # if the child process has exited.
           pid, status = Process.waitpid2(-1, block ? 0 : Process::WNOHANG)
           @log.debug "#{pid}"
-          # no more children have finished
+          # No more children have finished.
           break unless pid
 
           if status.success?

data/lib/aws/decider/flow_defaults.rb

@@ -15,30 +15,61 @@
 
 module AWS
   module Flow
+
+    # Constants used by the AWS Flow Framework for Ruby.
+    #
+    # @!attribute exponential_retry_maximum_retry_interval_seconds
+    #   The maximum exponential retry interval in seconds.
+    #
+    #   Use the value `-1` (the default) to set *no maximum*.
+    #
+    # @!attribute exponential_retry_retry_expiration_seconds
+    #   The maximum time that can pass, in seconds, before the exponential retry
+    #   attempt is considered to be a failure.
+    #
+    #   Use the value -1 (the default) to set *no maximum*.
+    #
+    # @!attribute exponential_retry_backoff_coefficient
+    #
+    #   The coefficient used to determine how much to back off the interval
+    #   timing for an exponential retry scenario. The default value, `2.0`,
+    #   causes each retry attempt to wait twice as long as the previous attempt.
+    #
+    # @!attribute exponential_retry_maximum_attempts
+    #   The maximum number of attempts to make for an exponential retry of a
+    #   failed task. The default value is `Float::INFINITY`, which indicates
+    #   that there should be *no* limit to the number of retry attempts.
+    #
+    # @!attribute exponential_retry_function
+    #   The default exponential retry function.
+    #
+    # @!attribute default_data_converter
+    #   The DataConverter used to interpret results from Amazon SWF. By
+    #   default, this is {YAMLDataConverter}.
+    #
+    # @!attribute exponential_retry_exceptions_to_include
+    #   A list of the exception types to include for initiating retry attempts.
+    #   By default, all exceptions are included (the default value is
+    #   `Exception`, which is the base class for all exceptions.)
+    #
+    # @!attribute exponential_retry_exceptions_to_exclude
+    #   A list of the exception types to exclude from initiating retry attempts.
+    #   By default, no exceptions are excluded; this is an empty list.
+    #
+    # @!attribute jitter_function
+    #   The function that is used to determine how long to wait for the next
+    #   retry attempt when *should_jitter* is set to `true`.
+    #
+    # @!attribute should_jitter
+    #   Indicates whether there should be any randomness built in to the timing of
+    #   the retry attempt. The default value is `true`.
+    #
     class FlowConstants
+
       class << self
         attr_reader :exponential_retry_maximum_retry_interval_seconds, :exponential_retry_retry_expiration_seconds, :exponential_retry_backoff_coefficient, :exponential_retry_maximum_attempts, :exponential_retry_function, :default_data_converter, :exponential_retry_exceptions_to_include, :exponential_retry_exceptions_to_exclude, :jitter_function, :should_jitter, :exponential_retry_initial_retry_interval
-        # # The maximum exponential retry interval, in seconds. Use the value -1 (the default) to set <i>no maximum</i>.
-        # attr_reader :exponential_retry_maximum_retry_interval_seconds
-
-        # # The maximum time that can pass, in seconds, before the exponential retry attempt is considered a failure. Use
-        # # the value -1 (the default) to set <i>no maximum</i>.
-        # attr_reader :exponential_retry_retry_expiration_seconds
-
-        # # The coefficient used to determine how much to back off the interval timing for an exponential retry scenario.
-        # # The default value, 2.0, causes each attempt to wait twice as long as the previous attempt.
-        # attr_reader :exponential_retry_backoff_coefficient
-
-        # # The maximum number of attempts to make for an exponential retry of a failed task. The default value is
-        # # Float::INFINITY.
-        # attr_reader :exponential_retry_maximum_attempts
-
-        # # The default exponential retry function.
-        # attr_reader :exponential_retry_function
-
-        # The DataConverter for instances of this class.
-        attr_reader :default_data_converter
       end
+
       INFINITY = -1
       @exponential_retry_maximum_attempts = Float::INFINITY
       @exponential_retry_maximum_retry_interval_seconds = -1
@@ -70,8 +101,9 @@ module AWS
       end
 
       @jitter_function = lambda do |seed, max_value|
-         random = Random.new(seed.to_i)
-         random.rand(max_value)
+        raise ArgumentError.new("max_value should be greater than 0") unless max_value > 0
+        random = Random.new(seed.to_i)
+        random.rand(max_value)
       end
 
       @default_data_converter = YAMLDataConverter.new