aws-flow 1.0.8 → 1.0.9

data/lib/aws/decider/state_machines.rb

@@ -16,7 +16,7 @@
 module AWS
   module Flow
 
-    # @!visibility private
+    # @api private
     module DecisionStateMachineDFA
       attr_accessor :transitions, :symbols, :states, :start_state
 
@@ -40,7 +40,7 @@ module AWS
       end
 
       def get_transitions
-        # Turns out, you are your own ancestor
+        # Turns out, you are your own ancestor.
         ancestors.slice(1..-1).map {|x| x.transitions if x.respond_to? :transitions}.compact.
           inject({}) {|x, y| x.merge(y)}.merge(@transitions)
       end
@@ -77,7 +77,7 @@ module AWS
       end
     end
 
-    # @!visibility private
+    # @api private
     class CompleteWorkflowStateMachine
       extend DecisionStateMachineDFA
       attr_reader :id
@@ -86,10 +86,10 @@ module AWS
         return if symbol == :handle_decision_task_started_event
         raise "UnsupportedOperation"
       end
-      # Creates a new CompleteWorkflowStateMachine
+      # Creates a new `CompleteWorkflowStateMachine`.
       #
       # @param id
-      #   The decider id.
+      #   The decider ID.
       #
       # @param attributes
       #
@@ -110,7 +110,7 @@ module AWS
     end
 
 
-    # @!visibility private
+    # @api private
     class DecisionStateMachineBase
       extend DecisionStateMachineDFA
       attr_reader :id
@@ -152,7 +152,7 @@ module AWS
     end
 
 
-    # @!visibility private
+    # @api private
     class ActivityDecisionStateMachine < DecisionStateMachineBase
 
       attr_reader :attributes
@@ -207,7 +207,7 @@ module AWS
     end
 
 
-    # @!visibility private
+    # @api private
     class TimerDecisionStateMachine < DecisionStateMachineBase
       attr_accessor :cancelled
       def initialize(decision_id, attributes)
@@ -257,7 +257,7 @@ module AWS
     end
 
 
-    # @!visibility private
+    # @api private
     class SignalDecisionStateMachine < DecisionStateMachineBase
       def initialize(decision_id, attributes)
         @attributes = attributes
@@ -305,7 +305,7 @@ module AWS
     end
 
 
-    # @!visibility private
+    # @api private
     class ChildWorkflowDecisionStateMachine < DecisionStateMachineBase
       attr_accessor :run_id, :attributes
       def initialize(decision_id, attributes)

data/lib/aws/decider/task_handler.rb

@@ -17,11 +17,11 @@ module AWS
   module Flow
 
 
-    # A decision task handler to work with a {WorkflowTaskPoller}. Create a DecisionTaskHandler and pass it to
-    # WorkflowTaskPoller on {WorkflowTaskPoller#initialize construction}.
+    # A decision task handler to work with a {WorkflowTaskPoller}. Create a `DecisionTaskHandler` and pass it to
+    # {WorkflowTaskPoller} on {WorkflowTaskPoller#initialize construction}.
     class DecisionTaskHandler
 
-      # Creates a new DecisionTaskHandler
+      # Creates a new `DecisionTaskHandler`.
       #
       # @param workflow_definition_map
       #
@@ -35,7 +35,7 @@ module AWS
       end
 
 
-      # Handles a decision task
+      # Handles a decision task.
       #
       # @param decision_task_iterator
       #
@@ -58,7 +58,7 @@ module AWS
       #
       # @param history_helper
       #
-      # @return [AsyncDecider] the created AsyncDecider.
+      # @return [AsyncDecider] The created {AsyncDecider}.
       #
       def create_async_decider(history_helper)
         task = history_helper.get_decision_task

data/lib/aws/decider/task_poller.rb

@@ -21,7 +21,7 @@ module AWS
     class WorkflowTaskPoller
 
 
-      # Creates a new WorkflowTaskPoller
+      # Creates a new `WorkflowTaskPoller`.
       #
       # @param service
       #   The Amazon SWF service object on which this task poller will operate.
@@ -72,15 +72,46 @@ module AWS
           end
           @service.respond_decision_task_completed(task_completed_request)
         rescue AWS::SimpleWorkflow::Errors::UnknownResourceFault => e
-          @logger.debug "Error in the poller, #{e}"
-          @logger.debug "The error class in #{e.class}"
+          @logger.error "Error in the poller, #{e}"
+          @logger.error "The error class in #{e.class}"
         rescue Exception => e
-          @logger.debug "Error in the poller, #{e}"
+          @logger.error "Error in the poller, #{e}"
         end
       end
     end
 
+    # A poller for activity tasks.
+    #
     class ActivityTaskPoller
+
+      # Initializes a new `ActivityTaskPoller`.
+      #
+      # @param service
+      #   *Required*. The AWS::SimpleWorkflow instance to use.
+      #
+      # @param domain
+      #   *Required*. The domain used by the workflow.
+      #
+      # @param task_list
+      #   *Required*. The task list used to poll for activity tasks.
+      #
+      # @param activity_definition_map
+      #   *Required*. The {ActivityDefinition} instance that implements the
+      #   activity to run. This map is in the form:
+      #
+      #       { :activity_type => 'activity_definition_name' }
+      #
+      #   The named activity definition will be run when the {#execute} method
+      #   is called.
+      #
+      # @param options
+      #   *Optional*. Options to set for the activity poller. You can set the
+      #   following options:
+      #
+      #   * `logger` - The logger to use.
+      #   * `max_workers` - The maximum number of workers that can be running at
+      #       once. The default is 20.
+      #
       def initialize(service, domain, task_list, activity_definition_map, executor, options=nil)
         @service = service
         @domain = domain
@@ -91,6 +122,13 @@ module AWS
         @executor = executor
       end
 
+      # Executes the specified activity task.
+      #
+      # @param task
+      #   *Required*. The
+      #   [AWS::SimpleWorkflow::ActivityTask](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/ActivityTask.html)
+      #   object to run.
+      #
       def execute(task)
         activity_type = task.activity_type
         begin
@@ -106,13 +144,34 @@ module AWS
             @service.respond_activity_task_completed(:task_token => task.task_token, :result => output)
           end
         rescue ActivityFailureException => e
-          @logger.debug "The activity failed, with original output of #{original_result} and dataconverted result of #{output}. aws-flow will now attempt to fail it."
+          @logger.error "The activity failed, with original output of #{original_result} and dataconverted result of #{output}. aws-flow will now attempt to fail it."
           respond_activity_task_failed_with_retry(task.task_token, e.message, e.details)
 
         end
         #TODO all the completion stuffs
       end
 
+      # Responds to the decider that the activity task has failed, and attempts
+      # to retry the task.
+      #
+      # @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.
+      #
       def respond_activity_task_failed_with_retry(task_token, reason, details)
         #TODO Set up this variable
         if @failure_retrier.nil?
@@ -121,6 +180,20 @@ module AWS
         end
       end
 
+      # Responds to the decider that the activity task should be canceled, and
+      # attempts to retry the task.
+      #
+      # @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.
+      #
       def respond_activity_task_canceled_with_retry(task_token, message)
         if @failure_retrier.nil?
           respond_activity_task_canceled(task_token, message)
@@ -128,20 +201,68 @@ module AWS
         #TODO Set up other stuff to do if we have it
       end
 
+      # Responds to the decider that the activity task should be canceled. No
+      # retry is attempted.
+      #
+      # @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.
+      #
       def respond_activity_task_canceled(task_token, message)
         @service.respond_activity_task_canceled({:task_token => task_token, :details => message})
       end
 
+      # Responds to the decider that the activity task has failed. No retry is
+      # attempted.
+      #
+      # @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.
+      #
       def respond_activity_task_failed(task_token, reason, details)
         @logger.debug "The task token to be reported on is #{task_token}"
         @service.respond_activity_task_failed(:task_token => task_token, :reason => reason.to_s, :details => details.to_s)
       end
 
+      # Processes the specified activity task.
+      #
+      # @param task
+      #   *Required*. The
+      #   [AWS::SimpleWorkflow::ActivityTask](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/ActivityTask.html)
+      #   object to process.
+      #
       def process_single_task(task)
-        previous_config = @service.config.to_h
-        previous_config.delete(:http_handler)
-        @service = AWS::SimpleWorkflow.new(previous_config).client
-        @service = @service.with_http_handler(AWS::Core::Http::NetHttpHandler.new(previous_config))
+
+        # 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 
+        # 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.
+
+        options = @service.config.to_h
+        options[:connection_pool] = AWS::Core::Http::ConnectionPool.build(options[:http_handler].pool.options)
+        options[:http_handler] = AWS::Core::Http::NetHttpHandler.new(options)
+        @service = AWS::SimpleWorkflow.new(options).client
+
         begin
           begin
             execute(task)
@@ -157,13 +278,24 @@ module AWS
           end
         rescue Exception => e
           semaphore_needs_release = true
-          @logger.debug "Got into the other error mode"
+          @logger.error "Got into the other error mode"
           raise e
         ensure
           @poll_semaphore.release if semaphore_needs_release
         end
       end
 
+      # Polls the task list for a new activity task, and executes it if one is
+      # found.
+      #
+      # If `use_forking` is set to `true` and the maximum number of workers (as
+      # set in {#initialize}) are already executing, this method will block
+      # until the number of running workers is less than the maximum.
+      #
+      # @param use_forking
+      #   *Optional*. Whether to use forking to execute the task. On Windows,
+      #   you should set this to `false`.
+      #
       def poll_and_process_single_task(use_forking = true)
         @poll_semaphore ||= SuspendableSemaphore.new
         @poll_semaphore.acquire
@@ -171,16 +303,17 @@ module AWS
         @logger.debug "before the poll\n\n"
         # This is to warm the lazily loaded clients in the @service, so we don't
         # pay for their loading in every forked client
-        @service.config.to_h
         begin
           if use_forking
             @executor.block_on_max_workers
           end
           task = @domain.activity_tasks.poll_for_single_task(@task_list)
-          @logger.error "got a task, #{task.activity_type.name}"
-          @logger.error "The task token I got was: #{task.task_token}"
+          if task
+            @logger.info "got a task, #{task.activity_type.name}"
+            @logger.info "The task token I got was: #{task.task_token}"
+          end
         rescue Exception => e
-          @logger.debug "I have not been able to poll successfully, and am now bailing out, with error #{e}"
+          @logger.error "I have not been able to poll successfully, and am now bailing out, with error #{e}"
           @poll_semaphore.release
           return false
         end
@@ -202,15 +335,19 @@ module AWS
       end
     end
 
+    # @api private
+    # @note This class is currently not implemented.
     class SuspendableSemaphore
 
+      # @note This method is not implemented.
       def initialize
-
       end
 
+      # @note This method is not implemented.
       def acquire
       end
 
+      # @note This method is not implemented.
       def release
       end
     end

data/lib/aws/decider/utilities.rb

@@ -17,9 +17,9 @@ require 'tmpdir'
 
 module AWS
   module Flow
-    # Utilities for the AWS Flow Framework for Ruby
+    # Utilities for the AWS Flow Framework for Ruby.
     module Utilities
-      # @!visibility private
+      # @api private
       class LogFactory
         def self.make_logger(klass, name)
           logname = "#{Dir.tmpdir}/#{klass.class.to_s}_#{name}"
@@ -31,7 +31,7 @@ module AWS
       end
 
 
-      # @!visibility private
+      # @api private
       def self.drill_on_future(future)
         while (future.respond_to? :is_flow_future?) && future.is_flow_future?
           future = future.get
@@ -39,7 +39,7 @@ module AWS
         future
       end
 
-      # @!visibility private
+      # @api private
       def self.merge_all_options(*args)
         args.compact!
         youngest = args.last
@@ -49,7 +49,7 @@ module AWS
       end
 
 
-      # @!visibility private
+      # @api private
       def self.interpret_block_for_options(option_class, block, use_defaults = false)
 
         return option_class.new({}, use_defaults) if block.nil?
@@ -87,7 +87,7 @@ module AWS
           @return_value = Future.new
         end
 
-        # determines whether the object is a flow future. The contract is that
+        # Determines whether the object is a flow future. The contract is that
         # flow futures must have a #get method.
         def is_flow_future?
           true
@@ -102,7 +102,7 @@ module AWS
         end
       end
 
-      # @!visibility private
+      # @api private
       def self.is_external
         if (defined? Fiber).nil?
           return true
@@ -112,9 +112,9 @@ module AWS
         return true
       end
 
-      # @!visibility private
+      # @api private
       module SelfMethods
-        # @!visibility private
+        # @api private
         def handle_event(event, options)
           id = options[:id_lambda].call(event) if options[:id_lambda]
           id = event.attributes
@@ -139,11 +139,11 @@ module AWS
         end
       end
 
-      # @!visibility private
+      # @api private
       module UpwardLookups
         attr_accessor :precursors
 
-        # @!visibility private
+        # @api private
         def held_properties
           precursors = self.ancestors.dup
           precursors.delete(self)
@@ -152,7 +152,7 @@ module AWS
           result.flatten
         end
 
-        # @!visibility private
+        # @api private
         def property(name, methods_to_prepare = [lambda(&:to_s)])
           @held_properties ||= []
           @held_properties << name
@@ -170,12 +170,12 @@ module AWS
           end
         end
 
-        # @!visibility private
+        # @api private
         def properties(*args)
           args.each { |arg| property(arg) }
         end
 
-        # @!visibility private
+        # @api private
         module InstanceMethods
           attr_accessor :precursors
           def look_upwards(variable)