aws-flow 2.0.1 → 2.0.2

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MmYyYmFhNGY4YzQ4OTE2ZjUyYjY5ZjgwZWY5Y2U5MjZhMTQ4MTE1Yw==
+    OTZjNzcwMDhjZjc5MzZlNjZjOTlmZDgxYjQzMmNlZmVkOWE1YTFhZA==
   data.tar.gz: !binary |-
-    ZThmYzg3OTUxYjJkY2IyNzg4NzI4MjllZGQ5ZjRmMDljNWYxNDZjMg==
+    NzNhZDZlZmI5Y2JiMGU1OTY2NjEwNGIzZDEwZTJjNDAyYTVhMmVkNQ==
 SHA512:
   metadata.gz: !binary |-
-    NjNkODJiYzMzNDdlNjBlOTJiMzM5NGFlYmYwNTFlOWY3ZTAwOTI1NWM4OWI0
-    ZDYwMGNkMDgwMGFjOWY3MzZmOGUwMGIxZjU1YzE0MTU3YzUyMWE5Njc2MjIw
-    MmY5Mzk1MTZhNWRkZDM3M2Q2MzE0NGMxMjRkZTI1NmNhNjAxODY=
+    N2U0N2RjOWIzYWExM2JmMzI2ZDc2NjgyNzNmNjA0OThlZjcyNGM2YTQwNDEy
+    NTg5ZTVlZTU3MmYwMjU5NzA3NzgyNzUwOWE2ZGMwNmU1YzE1MWE1Njk3MjBh
+    ODBjM2I5NjMyNWM5MGExYWE2NjdiMGM5MjA5NTQ2YTY1OGZiZTQ=
   data.tar.gz: !binary |-
-    M2E1YmRiZmI2NjZlZWIzMjRjODE3Mzg1ZTU0ZmUwMmVkNjJmODZlMmEyNWNm
-    MDJiNTdmZTZlNzcyYTBmOGI0YmEzMzc2Njk4ZTc3YTBjOTFmNDg3NmJmOGVl
-    MTE0NzZhZDAxMjAwYmY5OWQ5NDlhNmQyYWNhNDY2Y2I5ZWM0ZTU=
+    ODFiYmQyY2NmNTA0MTg0OGIzOGI0Y2Q5ZTUyZmVjNWE1ZTBhMDI5MzQ1OThl
+    NDNjNDhhN2U2ODNjYWU1ZGQ1MTM2NDkyNDJjNDlhYmEzYTcwNzFlOWQzOGQ0
+    ZDg5NTMzYmI2OWE4NmExMTEzZjZjMzA4ZTVhZTBmM2MxZjk4MmE=

data/aws-flow.gemspec

@@ -13,5 +13,5 @@ Gem::Specification.new do |s|
   s.files       = `git ls-files`.split("\n").reject {|file| file =~ /aws-flow-core/}
   s.require_paths << "lib/aws/"
   s.required_ruby_version = ">= 1.9.1"
-  s.add_dependency "aws-sdk", "~> 1", ">= 1.39.0"
+  s.add_dependency "aws-sdk-v1", "~> 1", ">= 1.39.0"
 end

data/lib/aws/decider.rb

@@ -16,7 +16,7 @@
 require 'aws/flow'
 include AWS::Flow::Core
 
-require 'aws-sdk'
+require 'aws-sdk-v1'
 require 'securerandom'
 
 # Setting the user-agent as ruby-flow for all calls to the service

data/lib/aws/decider/activity.rb

@@ -313,9 +313,14 @@ module AWS
     end
 
     # Represents an activity client.
+    # @api private
     class ActivityClient
+      # TODO -- Is this class used anywhere? It might be helpful to remove it,
+      # if it is not. Most of its functionality seems to be implemented in the
+      # GenericClient and GenericActivityClient classes.
 
       # Gets the data converter for the activity client.
+      # @api private
       def data_converter
         @generic_client.data_converter
       end
@@ -325,6 +330,7 @@ module AWS
       # @param other
       #   The data converter to set.
       #
+      # @api private
       def data_converter=(other)
         @generic_client.data_converter = other
       end
@@ -337,6 +343,7 @@ module AWS
       # @param [ExponentialRetryOptions] block
       #   A hash of {ExponentialRetryOptions} to use.
       #
+      # @api private
       def exponential_retry(method_name, &block)
         @generic_client.retry(method_name, lambda {|first, time_of_failure, attempts| 1}, block)
       end

data/lib/aws/decider/async_retrying_executor.rb

@@ -16,13 +16,18 @@
 module AWS
   module Flow
 
+    # internal AsyncRetryingExecutor class
+    # @api private
     class AsyncRetryingExecutor
+      # @api private
       def initialize(retrying_policy, clock, execution_id, return_on_start = false)
         @retrying_policy = retrying_policy
         @clock = clock
         @return_on_start = return_on_start
         @execution_id = execution_id
       end
+
+      # @api private
       def execute(command, options = nil)
         return schedule_with_retry(command, nil, Hash.new { |hash, key| hash[key] = 1 }, @clock.current_time, nil) if @return_on_start
         output = Utilities::AddressableFuture.new
@@ -44,6 +49,7 @@ module AWS
         output
       end
 
+      # @api private
       def schedule_with_retry(command, failure, attempts, first_attempt_time, time_of_recorded_failure)
         delay = -1
         if attempts.values.reduce(0, :+) > 1
@@ -60,6 +66,7 @@ module AWS
         end
       end
 
+      # @api private
       def invoke(command, attempts, first_attempt_time)
         failure_to_retry = nil
         should_retry = Future.new
@@ -86,7 +93,6 @@ module AWS
         return output if @return_on_start
         output.get
       end
-
     end
 
     # Represents a policy for retrying failed tasks.
@@ -95,10 +101,10 @@ module AWS
       # Creates a new `RetryPolicy` instance.
       #
       # @param retry_function
-      #   The method to be called for each retry attempt.
+      #   The method that will be called for each retry attempt.
       #
       # @param options
-      #   A set of {RetryOptions} to modify the retry behavior.
+      #   A set of {RetryOptions} used to modify the retry behavior.
       #
       def initialize(retry_function, options)
         @retry_function = retry_function
@@ -115,7 +121,8 @@ module AWS
       #   The failure to test.
       #
       # @return [true, false]
-      #   Returns `true` if the task can be retried for this failure.
+      #   Returns `true` if the task can be retried for this failure; `false`
+      #   otherwise.
       #
       def isRetryable(failure)
         if failure.respond_to? :cause
@@ -126,23 +133,31 @@ module AWS
 
         return true if @exceptions_to_exclude.empty? && @exceptions_to_include.empty?
         raise "#{failure} appears in both exceptions_to_include and exceptions_to_exclude" if @exceptions_to_exclude.include?(failure_class) && @exceptions_to_include.include?(failure_class)
-        # In short, default to false
-        # the second part of the statement does an intersection of the 2 arrays to see if any of the ancestors of
-        # failure exists in @exceptions_to_include
+        # In short, default to false.
+        # The second part of the statement does an intersection of the 2 arrays
+        # to see if any of the ancestors of failure exists in
+        # @exceptions_to_include
         return (!@exceptions_to_exclude.include?(failure_class) && !(@exceptions_to_include & failure_class.ancestors).empty?)
 
          #return (!@exceptions_to_exclude.include?(failure) && @exceptions_to_include.include?(failure))
       end
 
-      # Schedules a new retry attempt.
+      # Schedules a new retry attempt with an initial delay.
       #
       # @param first_attempt
+      #   The time to delay before the first retry attempt is made.
       #
       # @param time_of_recorded_failure
       #
       # @param attempts
+      #   The number of retry attempts to make before the task is considered to
+      #   be failed.
       #
       # @param failure
+      #   The type of failure to retry. If not specified, then all types of
+      #   failures will be retried.
+      #
+      # @param execution_id
       #
       def next_retry_delay_seconds(first_attempt, time_of_recorded_failure, attempts, failure = nil, execution_id)
         if attempts.values.reduce(0, :+) < 2

data/lib/aws/decider/decider.rb

@@ -335,7 +335,7 @@ module AWS
       #   The entry points (methods) that starts the workflow.
       #
       # @param block
-      #   A block of {WorflowRegistrationOptions} for the workflow.
+      #   A block of {WorkflowRegistrationOptions} for the workflow.
       #
       def workflow(*workflow_names, &block)
         workflow_names.each do |workflow_name| 

data/lib/aws/decider/exceptions.rb

@@ -45,6 +45,7 @@ module AWS
       #
       def initialize(reason = "Something went wrong in Flow",
                      details = "But this indicates that it got corrupted getting out")
+        super(reason)
         @reason = reason
         @details = details
         details = details.message if details.is_a? Exception

data/lib/aws/decider/flow_defaults.rb

@@ -18,51 +18,77 @@ module AWS
 
     # Constants used by the AWS Flow Framework for Ruby.
     #
-    # @!attribute exponential_retry_maximum_retry_interval_seconds
-    #   The maximum exponential retry interval in seconds.
+    # @!attribute [r] default_data_converter
+    #   The DataConverter used to interpret results from Amazon SWF.
     #
-    #   Use the value `-1` (the default) to set *no maximum*.
+    #   @return [Object] {YAMLDataConverter}
     #
-    # @!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.
+    # @!attribute [r] exponential_retry_backoff_coefficient
+    #   The coefficient used to determine how much to back off the interval
+    #     timing for an exponential retry scenario.
     #
-    #   Use the value -1 (the default) to set *no maximum*.
+    #   @return [Float] `2.0` (each retry takes twice as long as the previous
+    #     attempt)
     #
-    # @!attribute exponential_retry_backoff_coefficient
+    # @!attribute [r] exponential_retry_exceptions_to_exclude
+    #   A list of the exception types to exclude from initiating retry attempts.
     #
-    #   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.
+    #   @return [Array<Object>] an empty list. No exceptions are excluded.
     #
-    # @!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 [r] exponential_retry_exceptions_to_include
+    #   A list of the exception types to include for initiating retry attempts.
     #
-    # @!attribute exponential_retry_function
+    #   @return [Array<Class>] `Exception` (all exceptions are included)
+    #
+    # @!attribute [r] 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}.
+    #   @return A *lambda* that takes four parameters: an initial time, a time
+    #     of failure, a number of attempts, and a set of
+    #     {ExponentialRetryOptions}.
     #
-    # @!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 [r] exponential_retry_initial_retry_interval
+    #   The initial retry interval.
     #
-    # @!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.
+    #   @return [Fixnum] `2`
+    #
+    # @!attribute [r] exponential_retry_maximum_attempts
+    #   The maximum number of attempts to make for an exponential retry of a
+    #     failed task.
     #
-    # @!attribute jitter_function
+    #   @return [Float] `Float::INFINITY` (there is no limit to the number of
+    #     retry attempts)
+    #
+    # @!attribute [r] exponential_retry_maximum_retry_interval_seconds
+    #   The maximum interval that can pass, in seconds, before a retry occurs.
+    #
+    #   @return [Fixnum] `-1` (no maximum)
+    #
+    # @!attribute [r] exponential_retry_retry_expiration_seconds
+    #   The maximum time that can pass, in seconds, before an exponential retry
+    #     attempt is considered to be a failure.
+    #
+    #   @return [Fixnum] `-1` (no expiration for a retry attempt)
+    #
+    # @!attribute [r] 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`.
+    #     retry attempt when *should_jitter* is set to `true`.
+    #
+    #   @return a *lambda* that takes a random number seed and a maximum value
+    #     (must be > 0).
+    #
+    # @!attribute [r] should_jitter
+    #   Indicates whether there should be any randomness built in to the timing
+    #     of the retry attempt.
+    #
+    #   @return [Boolean] `true`
+    #
+    # @!attribute [r] use_worker_task_list
+    #   Used with activity and workflow options. Indicates that the activity
+    #     and/or workflow should use the same task list that the associated
+    #     worker is polling on.
     #
-    # @!attribute should_jitter
-    #   Indicates whether there should be any randomness built in to the timing of
-    #   the retry attempt. The default value is `true`.
+    #   @return [String] "USE_WORKER_TASK_LIST"
     #
     class FlowConstants
 

data/lib/aws/decider/generic_client.rb

@@ -16,7 +16,8 @@
 module AWS
   module Flow
 
-    # A generic activity client.
+    # A generic activity client. This class is not usually used directly; it
+    # serves as the base class for both activity and workflow client classes.
     class GenericClient
 
       # The option map for the client.
@@ -27,11 +28,14 @@ module AWS
         @option_map = {}
       end
 
-
-      # Sets a map of options for this client.
+      # Creates a new client that is a copy of this client instance, modified by
+      # a hash of passed-in options.
       #
       # @param opts
-      #   The options to set.
+      #   The options to set on the new client. Any options that are not set
+      #   here are copied from the original client.
+      #
+      # @return [GenericClient] A new client instance.
       #
       def with_opts(opts = {})
         modified_instance = self.dup
@@ -41,6 +45,16 @@ module AWS
         modified_instance
       end
 
+      # Reconfigures an activity client with a block of passed-in options.
+      #
+      # @note This functionality is limited to activity clients only.
+      #
+      # @param method_names
+      #   The activity methods to modify with the options passed in.
+      #
+      # @param block
+      #   A block of {ActivityOptions} to use to reconfigure the client.
+      #
       def reconfigure(*method_names, &block)
         options = Utilities::interpret_block_for_options(self.class.default_option_class, block)
         method_names.each { |method_name| @option_map[method_name.to_sym] = options }
@@ -51,17 +65,18 @@ module AWS
         raise "You cannot use this function outside of a workflow definition" if Utilities::is_external
       end
 
-
-      # Starts an asynchronous execution of a task. This method returns immediately; it does not wait for the task to
-      # complete.
+      # Starts an asynchronous execution of a task. This method returns
+      # immediately; it does not wait for the task to complete.
       #
-      # @note Trying to use {#send_async} outside of a workflow will fail with an exception.
+      # @note Trying to use {#send_async} outside of a workflow will fail with
+      #       an exception.
       #
       # @param task The task to execute.
       #
       # @param args A number of arguments used to start the task execution.
       #
-      # @param block A code block with additional options to start the task execution.
+      # @param block
+      #   A code block with additional options to start the task execution.
       #
       # @example The following two calls are equivalent.
       #    foo.send_async :bar # plus args and block if appropriate
@@ -75,7 +90,8 @@ module AWS
         # If there is no block, just make a block for immediate return.
         if block.nil?
           modified_options = Proc.new{ {:return_on_start => true } }
-          # If there is a block, and it doesn't take any arguments, it will evaluate to a hash. Add an option to the hash.
+          # If there is a block, and it doesn't take any arguments, it will
+          # evaluate to a hash. Add an option to the hash.
         elsif block.arity == 0
           modified_options = Proc.new do
             result = block.call
@@ -99,16 +115,25 @@ module AWS
         self.send(task, *args, &modified_options)
       end
 
-
       # Retries the given method using an exponential fallback function.
+      #
+      # @param method_name
+      #   The method to retry.
+      #
+      # @param args
+      #   Arguments (parameters) that are passed to the method specified in
+      #   *method_name*.
+      #
+      # @param block
+      #   A block of {RetryOptions} used to specify retry behavior.
+      #
       def exponential_retry(method_name, *args, &block)
         future = self._retry(method_name, FlowConstants.exponential_retry_function, block, args)
         Utilities::drill_on_future(future)
       end
 
-
-
       # Used by {#retry}
+      #
       # @api private
       def _retry_with_options(lambda_to_execute, retry_function, retry_options, args = NoInput.new)
         retry_policy = RetryPolicy.new(retry_function, retry_options)
@@ -137,7 +162,6 @@ module AWS
         return output.get
       end
 
-
       # Retries the given method using an optional retry function and block of {RetryOptions}.
       #
       # @param (see #retry)
@@ -149,20 +173,22 @@ module AWS
         _retry_with_options(lambda { self.send(method_name, *args) }, retry_function, retry_options)
       end
 
-
-      # Retries the given method using an optional retry function and block of {RetryOptions}.
+      # Retries the given method using an optional retry function and block of
+      # {RetryOptions}.
       #
       # @param method_name
-      #   The activity to retry.
+      #   The method to retry.
       #
       # @param retry_function
-      #   The retry function to use.
+      #   The function to use in order to determine if a retry should be
+      #   attempted.
       #
       # @param args
-      #   Arguments to send to the method named in the `method_name` parameter.
+      #   Arguments to send to the method provided in the *method_name*
+      #   parameter.
       #
       # @param block
-      #   The {RetryOptions} to set.
+      #   A block of {RetryOptions} used to specify retry behavior.
       #
       def retry(method_name, retry_function, *args, &block)
         if retry_function.is_a? Fixnum
@@ -173,8 +199,10 @@ module AWS
         Utilities::drill_on_future(future)
       end
 
-
-      # @return The decision context for this client.
+      # Returns the decision context for this client.
+      #
+      # @return The decision context.
+      #
       def decision_context
         FlowFiber.current[:decision_context]
       end

data/lib/aws/decider/options.rb

@@ -58,7 +58,7 @@ module AWS
       # class, and returns the result.
       #
       # @return [Hash]
-      #   The merged set of options, defined as a hash.
+      #   The merged set of options, returned as a hash.
       #
       # @param [Options] options
       #   An {Options}-derived class containing a set of options to use if this
@@ -116,8 +116,10 @@ module AWS
     class WorkerDefaults < Defaults
 
       # Whether to use Ruby's `fork` for launching new workers. The default is
-      # `true`. On Windows, you should override this default value and set
-      # `use_forking` to `false`.
+      # `true`.
+      #
+      # On Windows, you should override this default value and set `use_forking`
+      # to `false`. See {WorkerOptions} for more information.
       #
       # @return [Boolean]
       #   Returns `true`.
@@ -139,9 +141,13 @@ module AWS
     #   Whether to use Ruby's `fork` for launching new workers. The default is
     #   `true`.
     #
-    #   On Windows, this should be set to `false` unless you are running Ruby
-    #   under Cygwin. For more information, see [Important
-    #   Notes](http://docs.aws.amazon.com/amazonswf/latest/awsrbflowguide/important-notes.html#forking-windows-note)
+    #   On Windows, `use_forking` should generally be set to `false`:
+    #
+    #       AWS::Flow::ActivityWorker.new(
+    #           @domain.client, @domain, ACTIVITY_TASKLIST, klass) { { use_forking: false } }
+    #
+    #   For more information, see
+    #   [Important Notes](http://docs.aws.amazon.com/amazonswf/latest/awsrbflowguide/welcome.html#forking-windows-note)
     #   in the *AWS Flow Framework for Ruby Developer Guide*.
     #
     class WorkerOptions < Options
@@ -195,23 +201,40 @@ module AWS
 
       #  The default maximum number of attempts to make before the task is
       #  marked as failed.
+      #
+      #  @see FlowConstants.exponential_retry_maximum_attempts
       def maximum_attempts; FlowConstants.exponential_retry_maximum_attempts; end
 
       #  The default retry function to use.
+      #
+      #  @see FlowConstants.exponential_retry_function
       def retry_function; FlowConstants.exponential_retry_function; end
 
       #  The exceptions that will initiate a retry attempt. The default is to
       #  use *all* exceptions.
+      #
+      #  @see FlowConstants.exponential_retry_exceptions_to_include
       def exceptions_to_include; FlowConstants.exponential_retry_exceptions_to_include; end
 
       #  The exceptions that will *not* initiate a retry attempt. The default is
       #  an empty list; no exceptions are excluded.
+      #
+      #  @see FlowConstants.exponential_retry_exceptions_to_exclude
       def exceptions_to_exclude; FlowConstants.exponential_retry_exceptions_to_exclude; end
 
+      # Sets the backoff coefficient to use for retry attempts.
+      #
+      # @see FlowConstants.exponential_retry_backoff_coefficient
       def backoff_coefficient; FlowConstants.exponential_retry_backoff_coefficient; end
 
+      # @desc (see FlowConstants#should_jitter)
+      # @return the value of {FlowConstants#should_jitter}
       def should_jitter; FlowConstants.should_jitter; end
+
+      # @see FlowConstants.jitter_function
       def jitter_function; FlowConstants.jitter_function; end
+
+      # @see FlowConstants.exponential_retry_initial_retry_interval
       def initial_retry_interval; FlowConstants.exponential_retry_initial_retry_interval; end
     end
 
@@ -263,14 +286,15 @@ module AWS
       #  The retry function to use.
       #
       # @param [true, false] use_defaults
-      #   If set to `true`, the default options specified will be used as the runtime options.
+      #   If set to `true`, the default options specified will be used as the
+      #   runtime options.
       #
       def initialize(hash={}, use_defaults=false)
         super(hash, use_defaults)
       end
 
-      # Tests whether this activity can be retried based on the `:exceptions_to_retry` and
-      # `:exceptions_to_exclude` options.
+      # Tests whether this activity can be retried based on the
+      # `exceptions_to_retry` and `exceptions_to_exclude` options.
       #
       # @param [Object] failure
       #   The failure type to test.
@@ -351,10 +375,12 @@ module AWS
     #   The supported child policies are:
     #
     #   * `TERMINATE`: the child executions will be terminated.
+    #
     #   * `REQUEST_CANCEL`: a request to cancel will be attempted for each child
-    #     execution by recording a `WorkflowExecutionCancelRequested` event in its
-    #     history. It is up to the decider to take appropriate actions when it
-    #     receives an execution history with this event.
+    #      execution by recording a `WorkflowExecutionCancelRequested` event in its
+    #      history. It is up to the decider to take appropriate actions when it
+    #      receives an execution history with this event.
+    #
     #   * `ABANDON`: no action will be taken. The child executions will continue
     #     to run.
     #
@@ -460,7 +486,7 @@ module AWS
     class WorkflowRegistrationOptions < WorkflowOptions
       class << self
         def registration_options
-          [ 
+          [
             :default_task_start_to_close_timeout,
             :default_execution_start_to_close_timeout,
             :default_task_list,
@@ -710,6 +736,7 @@ module AWS
         @_exponential_retry = retry_options
       end
 
+      # Return the full set of options for the Activity.
       def get_full_options
         result = {}
         usable_properties = self.class.held_properties
@@ -725,6 +752,14 @@ module AWS
     # This class is used to capture the options passed during activity declaration.
     class ActivityRegistrationOptions < ActivityOptions
       class << self
+        # Default registration options. These can be set only during Activity
+        # registration.
+        #
+        # * `default_task_heartbeat_timeout`
+        # * `default_task_schedule_to_close_timeout`
+        # * `default_task_schedule_to_start_timeout`
+        # * `default_task_start_to_close_timeout`
+        #
         def registration_options
           [
             :default_task_heartbeat_timeout,
@@ -747,6 +782,7 @@ module AWS
 
       default_classes << ActivityRegistrationDefaults.new
 
+      # Return the options for this Activity that are set during registration.
       def get_registration_options
         get_options(self.class.registration_options)
       end
@@ -763,7 +799,8 @@ module AWS
       #   options in this class.
       #
       # @param [true, false] use_defaults
-      #   Set to `true` to use the default runtime options for the activity.
+      #   Set to `true` to use the default runtime options for the activity. The
+      #   default is `false`.
       #
       def initialize(default_options = {}, use_defaults=false)
         super(default_options, use_defaults)

data/lib/aws/decider/task_poller.rb

@@ -20,7 +20,6 @@ module AWS
 
     class WorkflowTaskPoller
 
-
       # Creates a new `WorkflowTaskPoller`.
       #
       # @param service
@@ -47,8 +46,6 @@ module AWS
         @logger ||= Utilities::LogFactory.make_logger(self)
       end
 
-
-
       # @api private
       # Retrieves any decision tasks that are ready.
       def get_decision_task
@@ -176,21 +173,7 @@ module AWS
       # @note Retry behavior for this method is currently *not implemented*. For
       #       now, it simply wraps {#respond_activity_task_failed}.
       #
-      # @param task_token
-      #   *Required*. The task token from the {ActivityDefinition} object to
-      #   retry. The task token is generated by the service and should be
-      #   treated as an opaque value.
-      #
-      # @param reason
-      #   *Required*. Description of the error that may assist in diagnostics.
-      #   Although this value is *required*, you can set it to an empty string
-      #   if you don't need this information.
-      #
-      # @param details
-      #   *Required*. Detailed information about the failure. Although this
-      #   value is *required*, you can set it to an empty string if you don't
-      #   need this information.
-      #
+      # @api private
       def respond_activity_task_failed_with_retry(task_token, reason, details)
         #TODO Set up this variable
         if @failure_retrier.nil?
@@ -205,14 +188,7 @@ module AWS
       # @note Retry behavior for this method is currently *not implemented*. For
       #       now, it simply wraps {#respond_activity_task_canceled}.
       #
-      # @param task_token
-      #   *Required*. The task token from the {ActivityDefinition} object to
-      #   retry.
-      #
-      # @param message
-      #   *Required*. A message that provides detail about why the activity task
-      #   is cancelled.
-      #
+      # @api private
       def respond_activity_task_canceled_with_retry(task_token, message)
         if @failure_retrier.nil?
           respond_activity_task_canceled(task_token, message)
@@ -270,10 +246,11 @@ module AWS
         # We are using the 'build' method to create a new ConnectionPool here to
         # make sure that connection pools are not shared among forked processes.
         # The default behavior of the ConnectionPool class is to cache a pool
-        # for a set of options created by the 'new' method and always use the 
+        # for a set of options created by the 'new' method and always use the
         # same pool for the same set of options. This is undesirable when
         # multiple processes want to use different connection pools with same
         # options as is the case here.
+        #
         # Since we can't change the pool of an already existing NetHttpHandler,
         # we also create a new NetHttpHandler in order to use the new pool.
 
@@ -350,19 +327,22 @@ module AWS
       end
     end
 
-    # @api private
     # @note This class is currently not implemented.
+    # @api private
     class SuspendableSemaphore
 
       # @note This method is not implemented.
+      # @api private
       def initialize
       end
 
       # @note This method is not implemented.
+      # @api private
       def acquire
       end
 
       # @note This method is not implemented.
+      # @api private
       def release
       end
     end

data/lib/aws/decider/version.rb

@@ -16,7 +16,7 @@
 module AWS
   module Flow
     def self.version
-      "2.0.1"
+      "2.0.2"
     end
   end
 end

data/lib/aws/runner.rb

@@ -1,58 +1,54 @@
 module AWS
   module Flow
+    # The Runner is a command-line utility that can spawn workflow and activity workers according to a specification
+    # that you provide in a [JSON](http://json.org/) configuration file. It is available beginning with version 1.3.0 of
+    # the AWS Flow Framework for Ruby.
+    #
+    # ## Invoking the Runner
+    #
+    # It is invoked like so:
+    #
+    #     aws-flow-ruby -f runspec.json
+    #
+    # Where **runspec.json** represents a local JSON file that specifies how to run your activities and workflows.
+    #
+    # ## The Runner Specification File
+    #
+    # The runner is configured by passing it a JSON-formatted configuration file. Here is a minimal example, providing
+    # only the required fields:
+    #
+    #     {
+    #       "domain": { "name": "ExampleDomain" },
+    #       "workflow_workers": [
+    #         {
+    #           "task_list": "example_workflow_tasklist"
+    #         }
+    #       ],
+    #       "activity_workers": [
+    #         {
+    #           "task_list": "example_activity_tasklist"
+    #         }
+    #       ],
+    #     }
+    #
+    # ## For More Information
+    #
+    # For a complete description of the runner's specification, with examples of both configuring and using the runner,
+    # see [The Runner](http://docs.aws.amazon.com/amazonswf/latest/awsrbflowguide/the-runner.html) in the *AWS Flow
+    # Framework for Ruby Developer Guide*.
+    #
     module Runner
 
-      # import the necessary gems to run Ruby Flow code
+      # Import the necessary gems to run Ruby Flow code.
       require 'aws/decider'
       include AWS::Flow
       require 'json'
       require 'optparse'
       require 'socket'
 
-
-      ##
-      ## Helper to start workflow and activity workers according to a predefined
-      ## JSON file format that decribes where to find the required elements
-      ## 
-
-      # Example of the format:
-      # {
-      #     "domain":
-      #     {
-      #        "name": <name_of_the_domain>,
-      #        "retention_in_days": <days>
-      #     }
-      #     "activity_workers": [
-      #         
-      #        {
-      #             "task_list": <name_of_the_task_list>,
-      #             "activity_classes": [ <name_of_class_containing_the_activities_to_be_worked_on> ],
-      #             "number_of_workers": <number_of_activity_workers_to_spawn>,
-      #             "number_of_forks_per_worker": <number_of_forked_workers>
-      #         }
-      #         //, ... can add more
-      #     ],
-      #     "workflow_workers": [
-      #         {
-      #             "task_list": <name_of_the_task_list>,
-      #             "workflow_classes": [ <name_of_class_containing_the_workflows_to_be_worked_on> ],
-      #             "number_of_workers": <number_of_workflow_workers_to_spawn>
-      #         }
-      #         //, ... can add more
-      #     ],
-      #     // Configure which files are 'require'd in order to load the classes
-      #     "workflow_paths": [
-      #         "lib/workflow.rb"
-      #     ],
-      #     "activity_paths": [
-      #         "lib/activity.rb"
-      #     ],
-      #     // This is used by the opsworks recipe
-      #     "user_agent_prefix" : "ruby-flow-opsworks"
-      # }
-
-
-      # registers the domain if it is not
+      # Registers the domain if it is not already registered.
+      #
+      # @api private
       def self.setup_domain(json_config)
 
         swf = create_service_client(json_config)
@@ -72,18 +68,27 @@ module AWS
         return AWS::SimpleWorkflow::Domain.new( domain['name'] )
       end
 
+      # @api private
       def self.set_process_name(name)
         $0 = name
       end
 
-      # searches the object space for all subclasses of clazz
+      # Searches the object space for all subclasses of `clazz`.
+      #
+      # @api private
       def self.all_subclasses(clazz)
         ObjectSpace.each_object(Class).select { |klass| klass.is_a? clazz }
       end
 
-      # used to extract and validate the 'activity_classes'
-      # and 'workflow_classes' fields from the config, or autodiscover 
-      # subclasses in the ObjectSpace
+      # Gets the classes to run.
+      #
+      # This method extracts and validates the 'activity_classes' and
+      # 'workflow_classes' fields from the runner specification file, or by
+      # autodiscovery of subclasses of [AWS::Flow::Activities]] and
+      # [AWS::Flow::Workflows] in the object space.
+      #
+      #
+      # @api private
       def self.get_classes(json_fragment, what)
         classes = json_fragment[what[:config_key]]
         if classes.nil? || classes.empty? then
@@ -99,12 +104,18 @@ module AWS
         classes
       end
 
-      # used to add implementations to workers; see get_classes
+      # Used to add implementations to workers; see [get_classes] for more
+      # information.
+      #
+      # @api private
       def self.add_implementations(worker, json_fragment, what)
         classes = get_classes(json_fragment, what)
         classes.each { |c| worker.add_implementation(c) }
       end
 
+      # Spawns the workers.
+      #
+      # @api private
       def self.spawn_and_start_workers(json_fragment, process_name, worker)
         workers = []
         num_of_workers = json_fragment['number_of_workers'] || FlowConstants::NUM_OF_WORKERS_DEFAULT
@@ -117,9 +128,10 @@ module AWS
         workers
       end
 
-      # used to support host-specific task lists
-      # when the string "|hostname|" is found in the task list
-      # it is replaced by the host name
+      # Used to support host-specific task lists. When the string "|hostname|"
+      # is found in the task list it is replaced by the actual host name.
+      #
+      # @api private
       def self.expand_task_list(value)
         raise ArgumentError.new unless value
         ret = value
@@ -127,23 +139,30 @@ module AWS
         ret
       end
 
+      # @api private
       def self.is_empty_field?(json_fragment, field_name)
         field = json_fragment[field_name]
         field.nil? || field.empty?
       end
 
-      # This is used to issue the necessary "require" commands to 
-      # load the code needed to run a module
+      # Runs the necessary "require" commands to load the code needed to run a
+      # module.
       #
-      # config_path: the path where the config file is, to be able to 
+      # config_path: the path where the config file is, to be able to
       #     resolve relative references
+      #
       # json_config: the content of the config
+      #
       # what: what should loaded. This is a hash expected to contain two keys:
+      #
       #     - :default_file : the file to load unless a specific list is provided
+      #
       #     - :config_key : the key of the config element which can contain a
-      #             specific list of files to load
+      #           specific list of files to load
+      #
+      # @api private
       def self.load_files(config_path, json_config, what)
-        if is_empty_field?(json_config, what[:config_key]) then 
+        if is_empty_field?(json_config, what[:config_key]) then
           file = File.join(File.dirname(config_path), what[:default_file])
           require file if File.exists? file
         else
@@ -151,6 +170,14 @@ module AWS
         end
       end
 
+      # Starts the activity workers.
+      #
+      # The activities run by the workers consist of each class that extends
+      # [AWS::Flow::Activities] in the paths provided in the `activity_paths`
+      # section of [the runner specification file][], or that are loaded from
+      # `require` statements in the `workflows.rb` file.
+      #
+      # @api private
       def self.start_activity_workers(swf, domain = nil, config_path, json_config)
         workers = []
         # load all classes for the activities
@@ -178,6 +205,14 @@ module AWS
         return workers
       end
 
+      # Starts the workflow workers.
+      #
+      # The workflows run by the workers consist of each class that extends
+      # [AWS::Flow::Workflows] in the paths provided in the `workflow_paths`
+      # section of [the runner specification file][], or that are loaded from
+      # `require` statements in the `workflows.rb` file.
+      #
+      # @api private
       def self.start_workflow_workers(swf, domain = nil, config_path, json_config)
         workers = []
         # load all the classes for the workflows
@@ -202,23 +237,23 @@ module AWS
         return workers
       end
 
+      # @api private
       def self.create_service_client(json_config)
         # set the UserAgent prefix for all clients
         if json_config['user_agent_prefix'] then
           AWS.config(user_agent_prefix: json_config['user_agent_prefix'])
         end
-        
+
         swf = AWS::SimpleWorkflow.new
       end
 
+      # Starts the workers and returns an array of process IDs (pids) for the
+      # worker processes.
       #
-      # this will start all the workers and return an array of pids for the worker
-      # processes
-      # 
+      # @api private
       def self.start_workers(domain = nil, config_path, json_config)
-        
         workers = []
-        
+
         swf = create_service_client(json_config)
 
         workers << start_activity_workers(swf, domain, config_path, json_config)
@@ -226,17 +261,20 @@ module AWS
 
         # needed to avoid returning nested arrays based on the calls above
         workers.flatten!
-
       end
 
-      # setup forwarding of signals to child processes, to facilitate and support
-      # orderly shutdown
+      # Sets up forwarding of signals to child processes to facilitate and
+      # support orderly shutdown.
+      #
+      # @api private
       def self.setup_signal_handling(workers)
         Signal.trap("INT") { workers.each { |w| Process.kill("INT", w) }  }
       end
 
+      # Waits until all the child workers are finished.
+      #
       # TODO: use a logger
-      # this will wait until all the child workers have died
+      # @api private
       def self.wait_for_child_processes(workers)
         until workers.empty?
           puts "waiting on workers " + workers.to_s + " to complete"
@@ -245,23 +283,32 @@ module AWS
         end
       end
 
-      # this is used to extend the load path so that the 'require' 
-      # of workflow and activity implementation files can succeed
-      # before adding the implementation classes to the workers
+      # Extends the load path so that the 'require' of workflow and activity
+      # implementation files can succeed before adding the implementation
+      # classes to the workers.
+      #
+      # @api private
       def self.add_dir_to_load_path(path)
         raise ArgumentError.new("Invalid directory path: \"" + path.to_s + "\"") if not FileTest.directory? path
         $LOAD_PATH.unshift path.to_s
       end
 
       #
-      # loads the configuration from a JSON file
+      # Loads the runner specification from a JSON file (passed in with the
+      # `--file` parameter when run from the shell).
       #
+      # @api private
       def self.load_config_json(path)
         raise ArgumentError.new("Invalid file path: \"" + path.to_s + "\"") if not File.file? path
         config = JSON.parse(File.open(path) { |f| f.read })
       end
 
-
+      # Interprets the command-line paramters pased in from the shell.
+      #
+      # The parameter `--file` (short: `-f`) is *required*, and must provide the
+      # path to the runner configuration file.
+      #
+      # @api private
       def self.parse_command_line(argv = ARGV)
         options = {}
         optparse = OptionParser.new do |opts|
@@ -272,12 +319,16 @@ module AWS
 
         optparse.parse!(argv)
 
-        # file parameter is not optional
+        # The `--file` parameter is not optional.
         raise OptionParser::MissingArgument.new("file") if options[:file].nil?
 
         return options
       end
 
+      #
+      # Invoked from the shell.
+      #
+      # @api private
       def self.main
         options = parse_command_line
         config_path =  options[:file]
@@ -287,12 +338,10 @@ module AWS
         workers = start_workers(domain, config_path, config)
         setup_signal_handling(workers)
 
-        # hang there until killed: this process is used to relay signals to children
-        # to support and facilitate an orderly shutdown
+        # Hang there until killed: this process is used to relay signals to
+        # children to support and facilitate an orderly shutdown.
         wait_for_child_processes(workers)
-
       end
-
     end
   end
 end

data/spec/aws/decider/integration/integration_spec.rb

@@ -14,7 +14,7 @@
 ##
 
 require 'yaml'
-require 'aws-sdk'
+require 'aws-sdk-v1'
 require 'logger'
 require_relative 'setup'
 

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: aws-flow
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.0.2
 platform: ruby
 authors:
 - Michael Steger, Paritosh Mohan, Jacques Thomas
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-22 00:00:00.000000000 Z
+date: 2014-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: aws-sdk
+  name: aws-sdk-v1
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
@@ -133,4 +133,3 @@ signing_key:
 specification_version: 4
 summary: AWS Flow Framework for Ruby
 test_files: []
-has_rdoc: