aws-flow 1.0.8 → 1.0.9

data/lib/aws/decider/version.rb

@@ -16,7 +16,7 @@
 module AWS
   module Flow
     def self.version
-      "1.0.8"
+      "1.0.9"
     end
   end
 end

data/lib/aws/decider/worker.rb

@@ -20,12 +20,12 @@ module AWS
 
     # A generic Activity/Workflow worker class.
     class GenericWorker
-      # Creates a new GenericWorker
+      # Creates a new `GenericWorker`.
       # @param service
       #   The AWS service class to use.
       #
       # @param domain
-      #   The SWF domain to use.
+      #   The Amazon SWF domain to use.
       #
       # @param task_list_to_poll
       #   The list of tasks to poll for this worker.
@@ -56,7 +56,7 @@ module AWS
         end
       end
 
-      # @!visibility private
+      # @api private
       def camel_case_to_snake_case(camel_case)
         camel_case.
           gsub(/(.)([A-Z])/,'\1_\2').
@@ -113,7 +113,7 @@ module AWS
       #   The service used with this workflow worker.
       #
       # @param [String] domain
-      #   The SWF domain to operate on.
+      #   The Amazon SWF domain to operate on.
       #
       # @param [Array] task_list
       #   The default task list to put all of the decision requests.
@@ -137,8 +137,8 @@ module AWS
         add_workflow_implementation(workflow_class)
       end
 
-      # Called by {#add_implementation}
-      # @!visibility private
+      # Called by {#add_implementation}.
+      # @api private
       def add_workflow_implementation(workflow_class)
         workflow_class.workflows.delete_if do |workflow_type|
           workflow_type.version.nil? || workflow_type.name.nil?
@@ -183,7 +183,7 @@ module AWS
       # Starts the workflow with a {WorkflowTaskPoller}.
       #
       # @param [true,false] should_register
-      #   Indicates whether or not the workflow needs to be registered with SWF first. If {#register} was already called
+      #   Indicates whether the workflow needs to be registered with Amazon SWF first. If {#register} was already called
       #   for this workflow worker, specify `false`.
       #
       def start(should_register = true)
@@ -216,24 +216,24 @@ module AWS
     end
 
 
-    # For implementing activity workers, you can use the ActivityWorker class to conveniently poll a task list for
+    # Used to implement an activity worker. You can use the `ActivityWorker` class to conveniently poll a task list for
     # activity tasks.
     #
     # You configure the activity worker with activity implementation objects. This worker class then polls for activity
     # tasks in the specified task list. When an activity task is received, it looks up the appropriate implementation
     # that you provided, and calls the activity method to process the task. Unlike the {WorkflowWorker}, which creates a
-    # new instance for every decision task, the ActivityWorker simply uses the object you provided.
+    # new instance for every decision task, the `ActivityWorker` simply uses the object you provided.
     #
     class ActivityWorker < GenericWorker
 
-      # Creates a new ActivityWorker instance.
+      # Creates a new `ActivityWorker` instance.
       #
       # @param service
-      #   The SWF [Client](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/Client.html) used to register
+      #   The Amazon SWF [Client](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/Client.html) used to register
       #   this activity worker.
       #
       # @param [String] domain
-      #   The SWF [Domain](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/Domain.html) to operate on.
+      #   The Amazon SWF [Domain](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/Domain.html) to operate on.
       #
       # @param [Array] task_list
       #   The default task list to put all of the activity requests.
@@ -257,7 +257,7 @@ module AWS
         super(service, domain, task_list, *args)
       end
 
-      # Adds an Activity implementation to this ActivityWorker.
+      # Adds an activity implementation to this `ActivityWorker`.
       #
       # @param [Activity] class_or_instance
       #   The {Activity} class or instance to add.
@@ -267,7 +267,7 @@ module AWS
       end
 
 
-      # Registers the activity type
+      # Registers the activity type.
       def register
         @activity_type_options.each do |activity_type_options|
           begin
@@ -289,7 +289,7 @@ module AWS
         end
       end
 
-      # Adds an Activity implementation to this ActivityWorker.
+      # Adds an activity implementation to this `ActivityWorker`.
       #
       # @param [Activity] class_or_instance
       #   The {Activity} class or instance to add.
@@ -314,10 +314,10 @@ module AWS
       end
 
 
-      # Starts the Activity that was added to the ActivityWorker
+      # Starts the activity that was added to the `ActivityWorker`.
       #
       # @param [true, false] should_register
-      #   Set to false if the Activity should not register itself (it is already registered).
+      #   Set to `false` if the activity should not register itself (it is already registered).
       #
       def start(should_register = true)
         register if should_register
@@ -327,17 +327,18 @@ module AWS
         end
       end
 
-      # Starts the Activity that was added to the ActivityWorker and, optionally, sets the ActivityTaskPoller.
+      # Starts the activity that was added to the `ActivityWorker` and, optionally, sets the {ActivityTaskPoller}.
       #
       # @param [true, false] should_register
-      #   Set to `false` if the Activity should not register itself (it is already registered).
+      #   Set to `false` if the activity should not register itself (it is already registered).
       #
       # @param [ActivityTaskPoller] poller
-      #   The {ActivityTaskPoller} to use. If this is not set, a default ActivityTaskPoller will be created.
+      #   The {ActivityTaskPoller} to use. If this is not set, a default {ActivityTaskPoller} will be created.
       #
       def run_once(should_register = true, poller = nil)
         register if should_register
         poller = ActivityTaskPoller.new(@service, @domain, @task_list, @activity_definition_map, @executor, @options) if poller.nil?
+        Kernel.exit if @shutting_down
         poller.poll_and_process_single_task(@options.use_forking)
       end
     end

data/lib/aws/decider/workflow_client.rb

@@ -16,13 +16,54 @@
 module AWS
   module Flow
 
+    # Contains data about an Amazon SWF domain.
+    #
+    # @!attribute name
+    #   The domain name.
+    #
     class MinimalDomain
       attr_accessor :name
+
+      # Creates a new `MinimalDomain` instance.
+      #
+      # @param domain
+      #   The [AWS::SimpleWorkflow::Domain](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/Domain.html)
+      #   that this instance will refer to.
+      #
       def initialize(domain); @domain = domain; end
     end
 
+    # Contains data about a workflow execution. This class represents a minimal set of data needed by the AWS Flow
+    # Framework for Ruby, based on the
+    # [AWS::SimpleWorkflow::WorkflowExecution](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/WorkflowExecution.html)
+    # class.
+    #
+    # @!attribute domain
+    #   The domain that the workflow is running in. See {MinimalWorkflowExecution#initialize} for details.
+    #
+    # @!attribute run_id
+    #   The unique run indentifier for this workflow. See {MinimalWorkflowExecution#initialize} for details.
+    #
+    # @!attribute workflow_id
+    #   The unique identifier for this workflow. See {MinimalWorkflowExecution#initialize} for details.
+    #
     class MinimalWorkflowExecution
       attr_accessor :workflow_id, :run_id, :domain
+
+      # Creates a new `MinimalWorkflowExecution` instance
+      #
+      # @param (Domain) domain
+      #   The Amazon SWF domain that the workflow is running in; an instance of
+      #   [AWS::SimpleWorkflow::Domain](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/Domain.html).
+      #
+      # @param (String) workflow_id
+      #   The unique workflow indentifier for this workflow; From
+      #   [AWS::SimpleWorkflow::WorkflowExecution#workflow_id](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/WorkflowExecution.html#workflow_id-instance_method).
+      #
+      # @param (String) run_id
+      #   The unique run indentifier for this workflow. From
+      #   [AWS::SimpleWorkflow::WorkflowExecution#run_id](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/WorkflowExecution.html#run_id-instance_method).
+      #
       def initialize(domain, workflow_id, run_id)
         @domain = domain
         @workflow_id = workflow_id
@@ -30,11 +71,11 @@ module AWS
       end
     end
 
-    # A future provided by a [WorkflowExecution](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/WorkflowExecution.html).
+    # A future provided by a
+    # [AWS::SimpleWorkflow::WorkflowExecution](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/WorkflowExecution.html).
     #
     # @!attribute _workflow_execution
-    #   A MinimalWorkflowExecution
-    #   instance that this future belongs to.
+    #   A {MinimalWorkflowExecution} instance that this future belongs to.
     #
     # @!attribute return_value
     #   The return value of the future.
@@ -43,28 +84,34 @@ module AWS
       attr_accessor :_workflow_execution, :return_value
 
 
-      # Creates a new workflow future
+      # Creates a new workflow future.
       #
       # @param workflow_execution
+      #   The {MinimalWorkflowExecution} to assign to this future.
       #
       def initialize(workflow_execution)
         @_workflow_execution = workflow_execution.dup
         @return_value = Future.new
       end
 
-      # determines whether the object is a flow future. The contract is that
-      # flow futures must have a #get method.
+      # Determines whether the object is a flow future. The contract is that flow futures must have a `get` method.
+      #
+      # @return
+      #   Always returns `true` for a {WorkflowFuture} object.
       def is_flow_future?
         true
       end
 
+      # @api private
       def method_missing(method_name, *args, &block)
         @return_value.send(method_name, *args, &block)
       end
 
-
-      # Gets the current value of the workflow execution
-      # @return
+      # Gets the current value of the workflow execution.
+      #
+      # @return {MinimalWorkflowExecution}
+      #   The workflow execution that this future belongs to.
+      #
       def workflow_execution
         @_workflow_execution
       end
@@ -73,16 +120,16 @@ module AWS
 
 
 
-    # @!visibility private
+    # @api private
     class NoInput
       def empty?; return true; end
     end
 
 
-    # A client for a workflow execution.
+    # Represents a client for a workflow execution.
     #
     # @!attribute domain
-    #   The SWF domain used for this workflow.
+    #   The Amazon SWF domain used for this workflow.
     #
     # @!attribute [Hash, WorkflowOptions] options
     #   Workflow options for this client.
@@ -90,14 +137,14 @@ module AWS
     class WorkflowClient < GenericClient
       attr_accessor :domain, :options
 
-      # Creates a new {WorkflowClient}
+      # Creates a new {WorkflowClient}.
       #
       # @param service
-      #   The SWF [Client](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/Client.html) to use for
+      #   The Amazon SWF [Client](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/Client.html) to use for
       #   creating this {WorkflowClient}.
       #
       # @param domain
-      #   The SWF [Domain](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/Domain.html) in which to
+      #   The Amazon SWF [Domain](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/Domain.html) in which to
       #   start the workflow execution.
       #
       # @param workflow_class
@@ -115,10 +162,10 @@ module AWS
       end
 
 
-      # @!visibility private
+      # @api private
       def self.default_option_class; WorkflowOptions; end
 
-      # Gets the events for this workflow client
+      # Gets the events for this workflow client.
       #
       def events
         @execution.events if @execution
@@ -136,7 +183,7 @@ module AWS
       # Begins executing this workflow.
       #
       # @param input
-      #   Input to provide to the
+      #   Input to provide to the workflow.
       #
       # @param [Hash, StartWorkflowOptions] block
       #   A hash of {StartWorkflowOptions} to use for this workflow execution.
@@ -171,8 +218,8 @@ module AWS
       end
 
 
-        # Called by {#signal_workflow_execution}
-        # @!visibility private
+        # Called by {#signal_workflow_execution}.
+        # @api private
         def signal_external_workflow(signal_name, workflow_execution, &block)
         options = Utilities::interpret_block_for_options(SignalWorkflowOptions, block)
         options.signal_name ||= signal_name
@@ -183,8 +230,8 @@ module AWS
         @service.signal_workflow_execution(options.get_full_options)
       end
 
-        # Called by {#signal_workflow_execution}
-        # @!visibility private
+        # Called by {#signal_workflow_execution}.
+        # @api private
       def signal_internal_workflow(signal_name, workflow_execution, &block)
         get_decision_context
         options = Utilities::interpret_block_for_options(SignalWorkflowOptions, block)
@@ -215,8 +262,8 @@ module AWS
       end
 
 
-      # Called by {#start_execution}
-      # @!visibility private
+      # Called by {#start_execution}.
+      # @api private
       def start_internal_workflow(input = NoInput.new, &block)
         get_decision_context
         options = Utilities::interpret_block_for_options(StartWorkflowOptions, block)
@@ -288,8 +335,8 @@ module AWS
       end
 
 
-      # Called by {#start_execution}
-      # @!visibility private
+      # Called by {#start_execution}.
+      # @api private
       def start_external_workflow(input = NoInput.new, &block)
         options = Utilities::interpret_block_for_options(StartWorkflowOptions, block)
         options = Utilities::merge_all_options(@options, options)
@@ -350,19 +397,19 @@ module AWS
     end
 
 
-    # Instances of WorkflowFactory are generated by {#workflow_factory}.
+    # Represents a workflow factory. Instances of `WorkflowFactory` are generated by {#workflow_factory}.
     class WorkflowFactory
 
 
-      # Creates a new WorkflowFactory with the provided parameters. The construction parameters will be used for any
+      # Creates a new `WorkflowFactory` with the provided parameters. The construction parameters will be used for any
       # workflow clients generated by this workflow factory.
       #
       # @param service
       #   The service to use for workflow clients generated by this workflow factory
       #
       # @param domain
-      #   The SWF [Domain](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/Domain.html) to use for
-      #   workflow clients generated by this workflow factory
+      #   The Amazon SWF [Domain](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/SimpleWorkflow/Domain.html) to use for
+      #   workflow clients generated by this workflow factory.
       #
       # @param block
       #   A block of {StartWorkflowOptions} to use for clients generated by this workflow factory.
@@ -382,7 +429,7 @@ module AWS
       # Get a {WorkflowClient} with the parameters used in the construction of this {WorkflowFactory}.
       #
       # @return [WorkflowClient]
-      #   A workflow client, created with the parameters used when creating the {WorkflowFactory}.
+      #   A workflow client created with the parameters used when creating the {WorkflowFactory}.
       #
       def get_client
         WorkflowClient.new(@service, @domain, @workflow_class, @options)

data/lib/aws/decider/workflow_clock.rb

@@ -44,7 +44,7 @@ module AWS
       # Get the current time.
       #
       # @return [Time]
-      #   A `Time` object initialized to the the current time in milliseconds for a replay. This is the same time that
+      #   A `Time` object initialized to the current time in milliseconds for a replay. This is the same time that
       #   is provided by the `:replay_current_time_millis` attribute.
       #
       def current_time

data/lib/aws/decider/workflow_definition.rb

@@ -16,10 +16,10 @@
 module AWS
   module Flow
 
-    # Every workflow implementation needs to be a subclass of this class.
+    # Represents a workflow definition. Every workflow implementation needs to be a subclass of this class.
     #
-    # Usually there should be no need to instantiate the class manually, as instead, the @execute method is called to
-    # start the workflow (you can think of ths as having factory class methods).
+    # Usually there should be no need to instantiate the class manually. Instead, the @execute method is called to
+    # start the workflow. You can think of this class as having factory class methods.
     class WorkflowDefinition
 
       attr_reader :decision_helper
@@ -44,9 +44,9 @@ module AWS
               method_output.set(@instance.send(@workflow_method))
             else
               ruby_input = @converter.load input
-              # Have to have *ruby_input in order to be able to handle sending
+              # Have to have `ruby_input` in order to be able to handle sending
               # arbitrary arguments correctly, as otherwise it will seem as if
-              # @workflow_method will always have an arity of 1
+              # @workflow_method will always have an arity of 1.
               method_output.set(@instance.send(@workflow_method, *ruby_input))
             end
           end

data/lib/aws/decider/workflow_definition_factory.rb

@@ -41,7 +41,7 @@ module AWS
 
       def delete_workflow_definition(definition)
         FlowFiber.unset(FlowFiber.current, :decision_context)
-        # Indicating to GC that these values are no longer needed
+        # Indicates to GC that these values are no longer needed.
         FlowFiber.local_variables.each_pair do |key, value|
           value = nil
           FlowFiber.local_variables.delete(key)

data/lib/aws/decider/workflow_enabled.rb

@@ -17,7 +17,7 @@ module AWS
   module Flow
     #  This method is for internal use only and may be changed or removed
     #   without prior notice.  Use {#workflow_client} instead.
-    # @!visibility private
+    # @api private
     def workflow_factory(client, domain, &options)
       WorkflowFactory.new(client, domain,  options)
     end

data/lib/aws/flow/async_backtrace.rb

@@ -13,21 +13,21 @@
 # permissions and limitations under the License.
 ##
 
-# This file contains AsyncBacktrace, which takes care of decorating and properly filtering backtraces
+# This file contains AsyncBacktrace, which takes care of decorating and properly filtering backtraces.
 
 module AWS
   module Flow
     module Core
-      # @!visibility private
+      # @api private
       class AsyncBacktrace
 
-        # @!visibility private
+        # @api private
         def initialize(parent, backtrace)
           @backtrace = AsyncBacktrace.filter(backtrace)
           @parent = parent
         end
 
-        # @!visibility private
+        # @api private
         def backtrace
           if @parent
             AsyncBacktrace.merge(@backtrace, @parent.backtrace)
@@ -36,10 +36,10 @@ module AWS
           end
         end
 
-        # @!visibility private
+        # @api private
         class << self
 
-          # @!visibility private
+          # @api private
           def create(parent, frames_to_skip)
 
             unless @disable_async_backtrace
@@ -48,21 +48,22 @@ module AWS
             end
           end
 
-          # @!visibility private
+          # @api private
           def create_from_exception(parent, exception)
             unless @disable_async_backtrace
               AsyncBacktrace.new(parent, exception.backtrace);
             end
           end
 
-          # Remove all framework related frames after application frames. Keep framework frames before application
+          # Removes all framework-related frames after application frames. Keep framework frames before application
           # frames.
           #
           # @todo
           #   The correct implementation should not have framework frames before application frames as it is expected to
-          #   call Kernel.caller with the correct number.  But in cases when due to changes this number is not correct
+          #   call Kernel.caller with the correct number. In cases when this number is not correct,
           #   the frames are kept to not create confusion.
           #
+          # @api private
           def filter(backtrace)
             if @disable_filtering
               backtrace
@@ -71,7 +72,7 @@ module AWS
             end
           end
 
-          # @!visibility private
+          # @api private
           def merge(*backtraces)
             result = []
             backtraces.each do | b |
@@ -83,27 +84,27 @@ module AWS
             result
           end
 
-          # @!visibility private
+          # @api private
           def disable_filtering
             @disable_filtering = true
           end
 
-          # @!visibility private
+          # @api private
           def enable_filtering
             @disable_filtering = false
           end
 
-          # @!visibility private
+          # @api private
           def disable
             @disable_async_backtrace = true
           end
 
-          # @!visibility private
+          # @api private
           def enable
             @disable_async_backtrace = false
           end
 
-          # @!visibility private
+          # @api private
           def caller(skip)
             random_var = Kernel.caller 0
             this_stuff =  1.upto(6).map { |x| Kernel.caller(x) }
@@ -113,11 +114,11 @@ module AWS
 
           private
 
-          # @!visibility private
+          # @api private
           def do_filter(backtrace)
             return nil unless backtrace
-            # keep asynchrony frames at the top of the backtrace only
-            # then cut all frames starting from asynchrony frame
+            # Keep asynchrony frames at the top of the backtrace only
+            # then cut all frames starting from asynchrony frame.
             skip_asynchrony_frames = false
             @backtrace = backtrace.take_while do |frame|
               if ! $RUBY_FLOW_FILES.select {|file| Regexp.new(file) =~ frame}.empty?