aws-flow 2.0.1 → 2.0.2

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,15 +1,15 @@
1
1
  ---
2
2
  !binary "U0hBMQ==":
3
3
  metadata.gz: !binary |-
4
- MmYyYmFhNGY4YzQ4OTE2ZjUyYjY5ZjgwZWY5Y2U5MjZhMTQ4MTE1Yw==
4
+ OTZjNzcwMDhjZjc5MzZlNjZjOTlmZDgxYjQzMmNlZmVkOWE1YTFhZA==
5
5
  data.tar.gz: !binary |-
6
- ZThmYzg3OTUxYjJkY2IyNzg4NzI4MjllZGQ5ZjRmMDljNWYxNDZjMg==
6
+ NzNhZDZlZmI5Y2JiMGU1OTY2NjEwNGIzZDEwZTJjNDAyYTVhMmVkNQ==
7
7
  SHA512:
8
8
  metadata.gz: !binary |-
9
- NjNkODJiYzMzNDdlNjBlOTJiMzM5NGFlYmYwNTFlOWY3ZTAwOTI1NWM4OWI0
10
- ZDYwMGNkMDgwMGFjOWY3MzZmOGUwMGIxZjU1YzE0MTU3YzUyMWE5Njc2MjIw
11
- MmY5Mzk1MTZhNWRkZDM3M2Q2MzE0NGMxMjRkZTI1NmNhNjAxODY=
9
+ N2U0N2RjOWIzYWExM2JmMzI2ZDc2NjgyNzNmNjA0OThlZjcyNGM2YTQwNDEy
10
+ NTg5ZTVlZTU3MmYwMjU5NzA3NzgyNzUwOWE2ZGMwNmU1YzE1MWE1Njk3MjBh
11
+ ODBjM2I5NjMyNWM5MGExYWE2NjdiMGM5MjA5NTQ2YTY1OGZiZTQ=
12
12
  data.tar.gz: !binary |-
13
- M2E1YmRiZmI2NjZlZWIzMjRjODE3Mzg1ZTU0ZmUwMmVkNjJmODZlMmEyNWNm
14
- MDJiNTdmZTZlNzcyYTBmOGI0YmEzMzc2Njk4ZTc3YTBjOTFmNDg3NmJmOGVl
15
- MTE0NzZhZDAxMjAwYmY5OWQ5NDlhNmQyYWNhNDY2Y2I5ZWM0ZTU=
13
+ ODFiYmQyY2NmNTA0MTg0OGIzOGI0Y2Q5ZTUyZmVjNWE1ZTBhMDI5MzQ1OThl
14
+ NDNjNDhhN2U2ODNjYWU1ZGQ1MTM2NDkyNDJjNDlhYmEzYTcwNzFlOWQzOGQ0
15
+ ZDg5NTMzYmI2OWE4NmExMTEzZjZjMzA4ZTVhZTBmM2MxZjk4MmE=
@@ -13,5 +13,5 @@ Gem::Specification.new do |s|
13
13
  s.files = `git ls-files`.split("\n").reject {|file| file =~ /aws-flow-core/}
14
14
  s.require_paths << "lib/aws/"
15
15
  s.required_ruby_version = ">= 1.9.1"
16
- s.add_dependency "aws-sdk", "~> 1", ">= 1.39.0"
16
+ s.add_dependency "aws-sdk-v1", "~> 1", ">= 1.39.0"
17
17
  end
@@ -16,7 +16,7 @@
16
16
  require 'aws/flow'
17
17
  include AWS::Flow::Core
18
18
 
19
- require 'aws-sdk'
19
+ require 'aws-sdk-v1'
20
20
  require 'securerandom'
21
21
 
22
22
  # Setting the user-agent as ruby-flow for all calls to the service
@@ -313,9 +313,14 @@ module AWS
313
313
  end
314
314
 
315
315
  # Represents an activity client.
316
+ # @api private
316
317
  class ActivityClient
318
+ # TODO -- Is this class used anywhere? It might be helpful to remove it,
319
+ # if it is not. Most of its functionality seems to be implemented in the
320
+ # GenericClient and GenericActivityClient classes.
317
321
 
318
322
  # Gets the data converter for the activity client.
323
+ # @api private
319
324
  def data_converter
320
325
  @generic_client.data_converter
321
326
  end
@@ -325,6 +330,7 @@ module AWS
325
330
  # @param other
326
331
  # The data converter to set.
327
332
  #
333
+ # @api private
328
334
  def data_converter=(other)
329
335
  @generic_client.data_converter = other
330
336
  end
@@ -337,6 +343,7 @@ module AWS
337
343
  # @param [ExponentialRetryOptions] block
338
344
  # A hash of {ExponentialRetryOptions} to use.
339
345
  #
346
+ # @api private
340
347
  def exponential_retry(method_name, &block)
341
348
  @generic_client.retry(method_name, lambda {|first, time_of_failure, attempts| 1}, block)
342
349
  end
@@ -16,13 +16,18 @@
16
16
  module AWS
17
17
  module Flow
18
18
 
19
+ # internal AsyncRetryingExecutor class
20
+ # @api private
19
21
  class AsyncRetryingExecutor
22
+ # @api private
20
23
  def initialize(retrying_policy, clock, execution_id, return_on_start = false)
21
24
  @retrying_policy = retrying_policy
22
25
  @clock = clock
23
26
  @return_on_start = return_on_start
24
27
  @execution_id = execution_id
25
28
  end
29
+
30
+ # @api private
26
31
  def execute(command, options = nil)
27
32
  return schedule_with_retry(command, nil, Hash.new { |hash, key| hash[key] = 1 }, @clock.current_time, nil) if @return_on_start
28
33
  output = Utilities::AddressableFuture.new
@@ -44,6 +49,7 @@ module AWS
44
49
  output
45
50
  end
46
51
 
52
+ # @api private
47
53
  def schedule_with_retry(command, failure, attempts, first_attempt_time, time_of_recorded_failure)
48
54
  delay = -1
49
55
  if attempts.values.reduce(0, :+) > 1
@@ -60,6 +66,7 @@ module AWS
60
66
  end
61
67
  end
62
68
 
69
+ # @api private
63
70
  def invoke(command, attempts, first_attempt_time)
64
71
  failure_to_retry = nil
65
72
  should_retry = Future.new
@@ -86,7 +93,6 @@ module AWS
86
93
  return output if @return_on_start
87
94
  output.get
88
95
  end
89
-
90
96
  end
91
97
 
92
98
  # Represents a policy for retrying failed tasks.
@@ -95,10 +101,10 @@ module AWS
95
101
  # Creates a new `RetryPolicy` instance.
96
102
  #
97
103
  # @param retry_function
98
- # The method to be called for each retry attempt.
104
+ # The method that will be called for each retry attempt.
99
105
  #
100
106
  # @param options
101
- # A set of {RetryOptions} to modify the retry behavior.
107
+ # A set of {RetryOptions} used to modify the retry behavior.
102
108
  #
103
109
  def initialize(retry_function, options)
104
110
  @retry_function = retry_function
@@ -115,7 +121,8 @@ module AWS
115
121
  # The failure to test.
116
122
  #
117
123
  # @return [true, false]
118
- # Returns `true` if the task can be retried for this failure.
124
+ # Returns `true` if the task can be retried for this failure; `false`
125
+ # otherwise.
119
126
  #
120
127
  def isRetryable(failure)
121
128
  if failure.respond_to? :cause
@@ -126,23 +133,31 @@ module AWS
126
133
 
127
134
  return true if @exceptions_to_exclude.empty? && @exceptions_to_include.empty?
128
135
  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)
129
- # In short, default to false
130
- # the second part of the statement does an intersection of the 2 arrays to see if any of the ancestors of
131
- # failure exists in @exceptions_to_include
136
+ # In short, default to false.
137
+ # The second part of the statement does an intersection of the 2 arrays
138
+ # to see if any of the ancestors of failure exists in
139
+ # @exceptions_to_include
132
140
  return (!@exceptions_to_exclude.include?(failure_class) && !(@exceptions_to_include & failure_class.ancestors).empty?)
133
141
 
134
142
  #return (!@exceptions_to_exclude.include?(failure) && @exceptions_to_include.include?(failure))
135
143
  end
136
144
 
137
- # Schedules a new retry attempt.
145
+ # Schedules a new retry attempt with an initial delay.
138
146
  #
139
147
  # @param first_attempt
148
+ # The time to delay before the first retry attempt is made.
140
149
  #
141
150
  # @param time_of_recorded_failure
142
151
  #
143
152
  # @param attempts
153
+ # The number of retry attempts to make before the task is considered to
154
+ # be failed.
144
155
  #
145
156
  # @param failure
157
+ # The type of failure to retry. If not specified, then all types of
158
+ # failures will be retried.
159
+ #
160
+ # @param execution_id
146
161
  #
147
162
  def next_retry_delay_seconds(first_attempt, time_of_recorded_failure, attempts, failure = nil, execution_id)
148
163
  if attempts.values.reduce(0, :+) < 2
@@ -335,7 +335,7 @@ module AWS
335
335
  # The entry points (methods) that starts the workflow.
336
336
  #
337
337
  # @param block
338
- # A block of {WorflowRegistrationOptions} for the workflow.
338
+ # A block of {WorkflowRegistrationOptions} for the workflow.
339
339
  #
340
340
  def workflow(*workflow_names, &block)
341
341
  workflow_names.each do |workflow_name|
@@ -45,6 +45,7 @@ module AWS
45
45
  #
46
46
  def initialize(reason = "Something went wrong in Flow",
47
47
  details = "But this indicates that it got corrupted getting out")
48
+ super(reason)
48
49
  @reason = reason
49
50
  @details = details
50
51
  details = details.message if details.is_a? Exception
@@ -18,51 +18,77 @@ module AWS
18
18
 
19
19
  # Constants used by the AWS Flow Framework for Ruby.
20
20
  #
21
- # @!attribute exponential_retry_maximum_retry_interval_seconds
22
- # The maximum exponential retry interval in seconds.
21
+ # @!attribute [r] default_data_converter
22
+ # The DataConverter used to interpret results from Amazon SWF.
23
23
  #
24
- # Use the value `-1` (the default) to set *no maximum*.
24
+ # @return [Object] {YAMLDataConverter}
25
25
  #
26
- # @!attribute exponential_retry_retry_expiration_seconds
27
- # The maximum time that can pass, in seconds, before the exponential retry
28
- # attempt is considered to be a failure.
26
+ # @!attribute [r] exponential_retry_backoff_coefficient
27
+ # The coefficient used to determine how much to back off the interval
28
+ # timing for an exponential retry scenario.
29
29
  #
30
- # Use the value -1 (the default) to set *no maximum*.
30
+ # @return [Float] `2.0` (each retry takes twice as long as the previous
31
+ # attempt)
31
32
  #
32
- # @!attribute exponential_retry_backoff_coefficient
33
+ # @!attribute [r] exponential_retry_exceptions_to_exclude
34
+ # A list of the exception types to exclude from initiating retry attempts.
33
35
  #
34
- # The coefficient used to determine how much to back off the interval
35
- # timing for an exponential retry scenario. The default value, `2.0`,
36
- # causes each retry attempt to wait twice as long as the previous attempt.
36
+ # @return [Array<Object>] an empty list. No exceptions are excluded.
37
37
  #
38
- # @!attribute exponential_retry_maximum_attempts
39
- # The maximum number of attempts to make for an exponential retry of a
40
- # failed task. The default value is `Float::INFINITY`, which indicates
41
- # that there should be *no* limit to the number of retry attempts.
38
+ # @!attribute [r] exponential_retry_exceptions_to_include
39
+ # A list of the exception types to include for initiating retry attempts.
42
40
  #
43
- # @!attribute exponential_retry_function
41
+ # @return [Array<Class>] `Exception` (all exceptions are included)
42
+ #
43
+ # @!attribute [r] exponential_retry_function
44
44
  # The default exponential retry function.
45
45
  #
46
- # @!attribute default_data_converter
47
- # The DataConverter used to interpret results from Amazon SWF. By
48
- # default, this is {YAMLDataConverter}.
46
+ # @return A *lambda* that takes four parameters: an initial time, a time
47
+ # of failure, a number of attempts, and a set of
48
+ # {ExponentialRetryOptions}.
49
49
  #
50
- # @!attribute exponential_retry_exceptions_to_include
51
- # A list of the exception types to include for initiating retry attempts.
52
- # By default, all exceptions are included (the default value is
53
- # `Exception`, which is the base class for all exceptions.)
50
+ # @!attribute [r] exponential_retry_initial_retry_interval
51
+ # The initial retry interval.
54
52
  #
55
- # @!attribute exponential_retry_exceptions_to_exclude
56
- # A list of the exception types to exclude from initiating retry attempts.
57
- # By default, no exceptions are excluded; this is an empty list.
53
+ # @return [Fixnum] `2`
54
+ #
55
+ # @!attribute [r] exponential_retry_maximum_attempts
56
+ # The maximum number of attempts to make for an exponential retry of a
57
+ # failed task.
58
58
  #
59
- # @!attribute jitter_function
59
+ # @return [Float] `Float::INFINITY` (there is no limit to the number of
60
+ # retry attempts)
61
+ #
62
+ # @!attribute [r] exponential_retry_maximum_retry_interval_seconds
63
+ # The maximum interval that can pass, in seconds, before a retry occurs.
64
+ #
65
+ # @return [Fixnum] `-1` (no maximum)
66
+ #
67
+ # @!attribute [r] exponential_retry_retry_expiration_seconds
68
+ # The maximum time that can pass, in seconds, before an exponential retry
69
+ # attempt is considered to be a failure.
70
+ #
71
+ # @return [Fixnum] `-1` (no expiration for a retry attempt)
72
+ #
73
+ # @!attribute [r] jitter_function
60
74
  # The function that is used to determine how long to wait for the next
61
- # retry attempt when *should_jitter* is set to `true`.
75
+ # retry attempt when *should_jitter* is set to `true`.
76
+ #
77
+ # @return a *lambda* that takes a random number seed and a maximum value
78
+ # (must be > 0).
79
+ #
80
+ # @!attribute [r] should_jitter
81
+ # Indicates whether there should be any randomness built in to the timing
82
+ # of the retry attempt.
83
+ #
84
+ # @return [Boolean] `true`
85
+ #
86
+ # @!attribute [r] use_worker_task_list
87
+ # Used with activity and workflow options. Indicates that the activity
88
+ # and/or workflow should use the same task list that the associated
89
+ # worker is polling on.
62
90
  #
63
- # @!attribute should_jitter
64
- # Indicates whether there should be any randomness built in to the timing of
65
- # the retry attempt. The default value is `true`.
91
+ # @return [String] "USE_WORKER_TASK_LIST"
66
92
  #
67
93
  class FlowConstants
68
94
 
@@ -16,7 +16,8 @@
16
16
  module AWS
17
17
  module Flow
18
18
 
19
- # A generic activity client.
19
+ # A generic activity client. This class is not usually used directly; it
20
+ # serves as the base class for both activity and workflow client classes.
20
21
  class GenericClient
21
22
 
22
23
  # The option map for the client.
@@ -27,11 +28,14 @@ module AWS
27
28
  @option_map = {}
28
29
  end
29
30
 
30
-
31
- # Sets a map of options for this client.
31
+ # Creates a new client that is a copy of this client instance, modified by
32
+ # a hash of passed-in options.
32
33
  #
33
34
  # @param opts
34
- # The options to set.
35
+ # The options to set on the new client. Any options that are not set
36
+ # here are copied from the original client.
37
+ #
38
+ # @return [GenericClient] A new client instance.
35
39
  #
36
40
  def with_opts(opts = {})
37
41
  modified_instance = self.dup
@@ -41,6 +45,16 @@ module AWS
41
45
  modified_instance
42
46
  end
43
47
 
48
+ # Reconfigures an activity client with a block of passed-in options.
49
+ #
50
+ # @note This functionality is limited to activity clients only.
51
+ #
52
+ # @param method_names
53
+ # The activity methods to modify with the options passed in.
54
+ #
55
+ # @param block
56
+ # A block of {ActivityOptions} to use to reconfigure the client.
57
+ #
44
58
  def reconfigure(*method_names, &block)
45
59
  options = Utilities::interpret_block_for_options(self.class.default_option_class, block)
46
60
  method_names.each { |method_name| @option_map[method_name.to_sym] = options }
@@ -51,17 +65,18 @@ module AWS
51
65
  raise "You cannot use this function outside of a workflow definition" if Utilities::is_external
52
66
  end
53
67
 
54
-
55
- # Starts an asynchronous execution of a task. This method returns immediately; it does not wait for the task to
56
- # complete.
68
+ # Starts an asynchronous execution of a task. This method returns
69
+ # immediately; it does not wait for the task to complete.
57
70
  #
58
- # @note Trying to use {#send_async} outside of a workflow will fail with an exception.
71
+ # @note Trying to use {#send_async} outside of a workflow will fail with
72
+ # an exception.
59
73
  #
60
74
  # @param task The task to execute.
61
75
  #
62
76
  # @param args A number of arguments used to start the task execution.
63
77
  #
64
- # @param block A code block with additional options to start the task execution.
78
+ # @param block
79
+ # A code block with additional options to start the task execution.
65
80
  #
66
81
  # @example The following two calls are equivalent.
67
82
  # foo.send_async :bar # plus args and block if appropriate
@@ -75,7 +90,8 @@ module AWS
75
90
  # If there is no block, just make a block for immediate return.
76
91
  if block.nil?
77
92
  modified_options = Proc.new{ {:return_on_start => true } }
78
- # If there is a block, and it doesn't take any arguments, it will evaluate to a hash. Add an option to the hash.
93
+ # If there is a block, and it doesn't take any arguments, it will
94
+ # evaluate to a hash. Add an option to the hash.
79
95
  elsif block.arity == 0
80
96
  modified_options = Proc.new do
81
97
  result = block.call
@@ -99,16 +115,25 @@ module AWS
99
115
  self.send(task, *args, &modified_options)
100
116
  end
101
117
 
102
-
103
118
  # Retries the given method using an exponential fallback function.
119
+ #
120
+ # @param method_name
121
+ # The method to retry.
122
+ #
123
+ # @param args
124
+ # Arguments (parameters) that are passed to the method specified in
125
+ # *method_name*.
126
+ #
127
+ # @param block
128
+ # A block of {RetryOptions} used to specify retry behavior.
129
+ #
104
130
  def exponential_retry(method_name, *args, &block)
105
131
  future = self._retry(method_name, FlowConstants.exponential_retry_function, block, args)
106
132
  Utilities::drill_on_future(future)
107
133
  end
108
134
 
109
-
110
-
111
135
  # Used by {#retry}
136
+ #
112
137
  # @api private
113
138
  def _retry_with_options(lambda_to_execute, retry_function, retry_options, args = NoInput.new)
114
139
  retry_policy = RetryPolicy.new(retry_function, retry_options)
@@ -137,7 +162,6 @@ module AWS
137
162
  return output.get
138
163
  end
139
164
 
140
-
141
165
  # Retries the given method using an optional retry function and block of {RetryOptions}.
142
166
  #
143
167
  # @param (see #retry)
@@ -149,20 +173,22 @@ module AWS
149
173
  _retry_with_options(lambda { self.send(method_name, *args) }, retry_function, retry_options)
150
174
  end
151
175
 
152
-
153
- # Retries the given method using an optional retry function and block of {RetryOptions}.
176
+ # Retries the given method using an optional retry function and block of
177
+ # {RetryOptions}.
154
178
  #
155
179
  # @param method_name
156
- # The activity to retry.
180
+ # The method to retry.
157
181
  #
158
182
  # @param retry_function
159
- # The retry function to use.
183
+ # The function to use in order to determine if a retry should be
184
+ # attempted.
160
185
  #
161
186
  # @param args
162
- # Arguments to send to the method named in the `method_name` parameter.
187
+ # Arguments to send to the method provided in the *method_name*
188
+ # parameter.
163
189
  #
164
190
  # @param block
165
- # The {RetryOptions} to set.
191
+ # A block of {RetryOptions} used to specify retry behavior.
166
192
  #
167
193
  def retry(method_name, retry_function, *args, &block)
168
194
  if retry_function.is_a? Fixnum
@@ -173,8 +199,10 @@ module AWS
173
199
  Utilities::drill_on_future(future)
174
200
  end
175
201
 
176
-
177
- # @return The decision context for this client.
202
+ # Returns the decision context for this client.
203
+ #
204
+ # @return The decision context.
205
+ #
178
206
  def decision_context
179
207
  FlowFiber.current[:decision_context]
180
208
  end
@@ -58,7 +58,7 @@ module AWS
58
58
  # class, and returns the result.
59
59
  #
60
60
  # @return [Hash]
61
- # The merged set of options, defined as a hash.
61
+ # The merged set of options, returned as a hash.
62
62
  #
63
63
  # @param [Options] options
64
64
  # An {Options}-derived class containing a set of options to use if this
@@ -116,8 +116,10 @@ module AWS
116
116
  class WorkerDefaults < Defaults
117
117
 
118
118
  # Whether to use Ruby's `fork` for launching new workers. The default is
119
- # `true`. On Windows, you should override this default value and set
120
- # `use_forking` to `false`.
119
+ # `true`.
120
+ #
121
+ # On Windows, you should override this default value and set `use_forking`
122
+ # to `false`. See {WorkerOptions} for more information.
121
123
  #
122
124
  # @return [Boolean]
123
125
  # Returns `true`.
@@ -139,9 +141,13 @@ module AWS
139
141
  # Whether to use Ruby's `fork` for launching new workers. The default is
140
142
  # `true`.
141
143
  #
142
- # On Windows, this should be set to `false` unless you are running Ruby
143
- # under Cygwin. For more information, see [Important
144
- # Notes](http://docs.aws.amazon.com/amazonswf/latest/awsrbflowguide/important-notes.html#forking-windows-note)
144
+ # On Windows, `use_forking` should generally be set to `false`:
145
+ #
146
+ # AWS::Flow::ActivityWorker.new(
147
+ # @domain.client, @domain, ACTIVITY_TASKLIST, klass) { { use_forking: false } }
148
+ #
149
+ # For more information, see
150
+ # [Important Notes](http://docs.aws.amazon.com/amazonswf/latest/awsrbflowguide/welcome.html#forking-windows-note)
145
151
  # in the *AWS Flow Framework for Ruby Developer Guide*.
146
152
  #
147
153
  class WorkerOptions < Options
@@ -195,23 +201,40 @@ module AWS
195
201
 
196
202
  # The default maximum number of attempts to make before the task is
197
203
  # marked as failed.
204
+ #
205
+ # @see FlowConstants.exponential_retry_maximum_attempts
198
206
  def maximum_attempts; FlowConstants.exponential_retry_maximum_attempts; end
199
207
 
200
208
  # The default retry function to use.
209
+ #
210
+ # @see FlowConstants.exponential_retry_function
201
211
  def retry_function; FlowConstants.exponential_retry_function; end
202
212
 
203
213
  # The exceptions that will initiate a retry attempt. The default is to
204
214
  # use *all* exceptions.
215
+ #
216
+ # @see FlowConstants.exponential_retry_exceptions_to_include
205
217
  def exceptions_to_include; FlowConstants.exponential_retry_exceptions_to_include; end
206
218
 
207
219
  # The exceptions that will *not* initiate a retry attempt. The default is
208
220
  # an empty list; no exceptions are excluded.
221
+ #
222
+ # @see FlowConstants.exponential_retry_exceptions_to_exclude
209
223
  def exceptions_to_exclude; FlowConstants.exponential_retry_exceptions_to_exclude; end
210
224
 
225
+ # Sets the backoff coefficient to use for retry attempts.
226
+ #
227
+ # @see FlowConstants.exponential_retry_backoff_coefficient
211
228
  def backoff_coefficient; FlowConstants.exponential_retry_backoff_coefficient; end
212
229
 
230
+ # @desc (see FlowConstants#should_jitter)
231
+ # @return the value of {FlowConstants#should_jitter}
213
232
  def should_jitter; FlowConstants.should_jitter; end
233
+
234
+ # @see FlowConstants.jitter_function
214
235
  def jitter_function; FlowConstants.jitter_function; end
236
+
237
+ # @see FlowConstants.exponential_retry_initial_retry_interval
215
238
  def initial_retry_interval; FlowConstants.exponential_retry_initial_retry_interval; end
216
239
  end
217
240
 
@@ -263,14 +286,15 @@ module AWS
263
286
  # The retry function to use.
264
287
  #
265
288
  # @param [true, false] use_defaults
266
- # If set to `true`, the default options specified will be used as the runtime options.
289
+ # If set to `true`, the default options specified will be used as the
290
+ # runtime options.
267
291
  #
268
292
  def initialize(hash={}, use_defaults=false)
269
293
  super(hash, use_defaults)
270
294
  end
271
295
 
272
- # Tests whether this activity can be retried based on the `:exceptions_to_retry` and
273
- # `:exceptions_to_exclude` options.
296
+ # Tests whether this activity can be retried based on the
297
+ # `exceptions_to_retry` and `exceptions_to_exclude` options.
274
298
  #
275
299
  # @param [Object] failure
276
300
  # The failure type to test.
@@ -351,10 +375,12 @@ module AWS
351
375
  # The supported child policies are:
352
376
  #
353
377
  # * `TERMINATE`: the child executions will be terminated.
378
+ #
354
379
  # * `REQUEST_CANCEL`: a request to cancel will be attempted for each child
355
- # execution by recording a `WorkflowExecutionCancelRequested` event in its
356
- # history. It is up to the decider to take appropriate actions when it
357
- # receives an execution history with this event.
380
+ # execution by recording a `WorkflowExecutionCancelRequested` event in its
381
+ # history. It is up to the decider to take appropriate actions when it
382
+ # receives an execution history with this event.
383
+ #
358
384
  # * `ABANDON`: no action will be taken. The child executions will continue
359
385
  # to run.
360
386
  #
@@ -460,7 +486,7 @@ module AWS
460
486
  class WorkflowRegistrationOptions < WorkflowOptions
461
487
  class << self
462
488
  def registration_options
463
- [
489
+ [
464
490
  :default_task_start_to_close_timeout,
465
491
  :default_execution_start_to_close_timeout,
466
492
  :default_task_list,
@@ -710,6 +736,7 @@ module AWS
710
736
  @_exponential_retry = retry_options
711
737
  end
712
738
 
739
+ # Return the full set of options for the Activity.
713
740
  def get_full_options
714
741
  result = {}
715
742
  usable_properties = self.class.held_properties
@@ -725,6 +752,14 @@ module AWS
725
752
  # This class is used to capture the options passed during activity declaration.
726
753
  class ActivityRegistrationOptions < ActivityOptions
727
754
  class << self
755
+ # Default registration options. These can be set only during Activity
756
+ # registration.
757
+ #
758
+ # * `default_task_heartbeat_timeout`
759
+ # * `default_task_schedule_to_close_timeout`
760
+ # * `default_task_schedule_to_start_timeout`
761
+ # * `default_task_start_to_close_timeout`
762
+ #
728
763
  def registration_options
729
764
  [
730
765
  :default_task_heartbeat_timeout,
@@ -747,6 +782,7 @@ module AWS
747
782
 
748
783
  default_classes << ActivityRegistrationDefaults.new
749
784
 
785
+ # Return the options for this Activity that are set during registration.
750
786
  def get_registration_options
751
787
  get_options(self.class.registration_options)
752
788
  end
@@ -763,7 +799,8 @@ module AWS
763
799
  # options in this class.
764
800
  #
765
801
  # @param [true, false] use_defaults
766
- # Set to `true` to use the default runtime options for the activity.
802
+ # Set to `true` to use the default runtime options for the activity. The
803
+ # default is `false`.
767
804
  #
768
805
  def initialize(default_options = {}, use_defaults=false)
769
806
  super(default_options, use_defaults)
@@ -20,7 +20,6 @@ module AWS
20
20
 
21
21
  class WorkflowTaskPoller
22
22
 
23
-
24
23
  # Creates a new `WorkflowTaskPoller`.
25
24
  #
26
25
  # @param service
@@ -47,8 +46,6 @@ module AWS
47
46
  @logger ||= Utilities::LogFactory.make_logger(self)
48
47
  end
49
48
 
50
-
51
-
52
49
  # @api private
53
50
  # Retrieves any decision tasks that are ready.
54
51
  def get_decision_task
@@ -176,21 +173,7 @@ module AWS
176
173
  # @note Retry behavior for this method is currently *not implemented*. For
177
174
  # now, it simply wraps {#respond_activity_task_failed}.
178
175
  #
179
- # @param task_token
180
- # *Required*. The task token from the {ActivityDefinition} object to
181
- # retry. The task token is generated by the service and should be
182
- # treated as an opaque value.
183
- #
184
- # @param reason
185
- # *Required*. Description of the error that may assist in diagnostics.
186
- # Although this value is *required*, you can set it to an empty string
187
- # if you don't need this information.
188
- #
189
- # @param details
190
- # *Required*. Detailed information about the failure. Although this
191
- # value is *required*, you can set it to an empty string if you don't
192
- # need this information.
193
- #
176
+ # @api private
194
177
  def respond_activity_task_failed_with_retry(task_token, reason, details)
195
178
  #TODO Set up this variable
196
179
  if @failure_retrier.nil?
@@ -205,14 +188,7 @@ module AWS
205
188
  # @note Retry behavior for this method is currently *not implemented*. For
206
189
  # now, it simply wraps {#respond_activity_task_canceled}.
207
190
  #
208
- # @param task_token
209
- # *Required*. The task token from the {ActivityDefinition} object to
210
- # retry.
211
- #
212
- # @param message
213
- # *Required*. A message that provides detail about why the activity task
214
- # is cancelled.
215
- #
191
+ # @api private
216
192
  def respond_activity_task_canceled_with_retry(task_token, message)
217
193
  if @failure_retrier.nil?
218
194
  respond_activity_task_canceled(task_token, message)
@@ -270,10 +246,11 @@ module AWS
270
246
  # We are using the 'build' method to create a new ConnectionPool here to
271
247
  # make sure that connection pools are not shared among forked processes.
272
248
  # The default behavior of the ConnectionPool class is to cache a pool
273
- # for a set of options created by the 'new' method and always use the
249
+ # for a set of options created by the 'new' method and always use the
274
250
  # same pool for the same set of options. This is undesirable when
275
251
  # multiple processes want to use different connection pools with same
276
252
  # options as is the case here.
253
+ #
277
254
  # Since we can't change the pool of an already existing NetHttpHandler,
278
255
  # we also create a new NetHttpHandler in order to use the new pool.
279
256
 
@@ -350,19 +327,22 @@ module AWS
350
327
  end
351
328
  end
352
329
 
353
- # @api private
354
330
  # @note This class is currently not implemented.
331
+ # @api private
355
332
  class SuspendableSemaphore
356
333
 
357
334
  # @note This method is not implemented.
335
+ # @api private
358
336
  def initialize
359
337
  end
360
338
 
361
339
  # @note This method is not implemented.
340
+ # @api private
362
341
  def acquire
363
342
  end
364
343
 
365
344
  # @note This method is not implemented.
345
+ # @api private
366
346
  def release
367
347
  end
368
348
  end
@@ -16,7 +16,7 @@
16
16
  module AWS
17
17
  module Flow
18
18
  def self.version
19
- "2.0.1"
19
+ "2.0.2"
20
20
  end
21
21
  end
22
22
  end
@@ -1,58 +1,54 @@
1
1
  module AWS
2
2
  module Flow
3
+ # The Runner is a command-line utility that can spawn workflow and activity workers according to a specification
4
+ # that you provide in a [JSON](http://json.org/) configuration file. It is available beginning with version 1.3.0 of
5
+ # the AWS Flow Framework for Ruby.
6
+ #
7
+ # ## Invoking the Runner
8
+ #
9
+ # It is invoked like so:
10
+ #
11
+ # aws-flow-ruby -f runspec.json
12
+ #
13
+ # Where **runspec.json** represents a local JSON file that specifies how to run your activities and workflows.
14
+ #
15
+ # ## The Runner Specification File
16
+ #
17
+ # The runner is configured by passing it a JSON-formatted configuration file. Here is a minimal example, providing
18
+ # only the required fields:
19
+ #
20
+ # {
21
+ # "domain": { "name": "ExampleDomain" },
22
+ # "workflow_workers": [
23
+ # {
24
+ # "task_list": "example_workflow_tasklist"
25
+ # }
26
+ # ],
27
+ # "activity_workers": [
28
+ # {
29
+ # "task_list": "example_activity_tasklist"
30
+ # }
31
+ # ],
32
+ # }
33
+ #
34
+ # ## For More Information
35
+ #
36
+ # For a complete description of the runner's specification, with examples of both configuring and using the runner,
37
+ # see [The Runner](http://docs.aws.amazon.com/amazonswf/latest/awsrbflowguide/the-runner.html) in the *AWS Flow
38
+ # Framework for Ruby Developer Guide*.
39
+ #
3
40
  module Runner
4
41
 
5
- # import the necessary gems to run Ruby Flow code
42
+ # Import the necessary gems to run Ruby Flow code.
6
43
  require 'aws/decider'
7
44
  include AWS::Flow
8
45
  require 'json'
9
46
  require 'optparse'
10
47
  require 'socket'
11
48
 
12
-
13
- ##
14
- ## Helper to start workflow and activity workers according to a predefined
15
- ## JSON file format that decribes where to find the required elements
16
- ##
17
-
18
- # Example of the format:
19
- # {
20
- # "domain":
21
- # {
22
- # "name": <name_of_the_domain>,
23
- # "retention_in_days": <days>
24
- # }
25
- # "activity_workers": [
26
- #
27
- # {
28
- # "task_list": <name_of_the_task_list>,
29
- # "activity_classes": [ <name_of_class_containing_the_activities_to_be_worked_on> ],
30
- # "number_of_workers": <number_of_activity_workers_to_spawn>,
31
- # "number_of_forks_per_worker": <number_of_forked_workers>
32
- # }
33
- # //, ... can add more
34
- # ],
35
- # "workflow_workers": [
36
- # {
37
- # "task_list": <name_of_the_task_list>,
38
- # "workflow_classes": [ <name_of_class_containing_the_workflows_to_be_worked_on> ],
39
- # "number_of_workers": <number_of_workflow_workers_to_spawn>
40
- # }
41
- # //, ... can add more
42
- # ],
43
- # // Configure which files are 'require'd in order to load the classes
44
- # "workflow_paths": [
45
- # "lib/workflow.rb"
46
- # ],
47
- # "activity_paths": [
48
- # "lib/activity.rb"
49
- # ],
50
- # // This is used by the opsworks recipe
51
- # "user_agent_prefix" : "ruby-flow-opsworks"
52
- # }
53
-
54
-
55
- # registers the domain if it is not
49
+ # Registers the domain if it is not already registered.
50
+ #
51
+ # @api private
56
52
  def self.setup_domain(json_config)
57
53
 
58
54
  swf = create_service_client(json_config)
@@ -72,18 +68,27 @@ module AWS
72
68
  return AWS::SimpleWorkflow::Domain.new( domain['name'] )
73
69
  end
74
70
 
71
+ # @api private
75
72
  def self.set_process_name(name)
76
73
  $0 = name
77
74
  end
78
75
 
79
- # searches the object space for all subclasses of clazz
76
+ # Searches the object space for all subclasses of `clazz`.
77
+ #
78
+ # @api private
80
79
  def self.all_subclasses(clazz)
81
80
  ObjectSpace.each_object(Class).select { |klass| klass.is_a? clazz }
82
81
  end
83
82
 
84
- # used to extract and validate the 'activity_classes'
85
- # and 'workflow_classes' fields from the config, or autodiscover
86
- # subclasses in the ObjectSpace
83
+ # Gets the classes to run.
84
+ #
85
+ # This method extracts and validates the 'activity_classes' and
86
+ # 'workflow_classes' fields from the runner specification file, or by
87
+ # autodiscovery of subclasses of [AWS::Flow::Activities]] and
88
+ # [AWS::Flow::Workflows] in the object space.
89
+ #
90
+ #
91
+ # @api private
87
92
  def self.get_classes(json_fragment, what)
88
93
  classes = json_fragment[what[:config_key]]
89
94
  if classes.nil? || classes.empty? then
@@ -99,12 +104,18 @@ module AWS
99
104
  classes
100
105
  end
101
106
 
102
- # used to add implementations to workers; see get_classes
107
+ # Used to add implementations to workers; see [get_classes] for more
108
+ # information.
109
+ #
110
+ # @api private
103
111
  def self.add_implementations(worker, json_fragment, what)
104
112
  classes = get_classes(json_fragment, what)
105
113
  classes.each { |c| worker.add_implementation(c) }
106
114
  end
107
115
 
116
+ # Spawns the workers.
117
+ #
118
+ # @api private
108
119
  def self.spawn_and_start_workers(json_fragment, process_name, worker)
109
120
  workers = []
110
121
  num_of_workers = json_fragment['number_of_workers'] || FlowConstants::NUM_OF_WORKERS_DEFAULT
@@ -117,9 +128,10 @@ module AWS
117
128
  workers
118
129
  end
119
130
 
120
- # used to support host-specific task lists
121
- # when the string "|hostname|" is found in the task list
122
- # it is replaced by the host name
131
+ # Used to support host-specific task lists. When the string "|hostname|"
132
+ # is found in the task list it is replaced by the actual host name.
133
+ #
134
+ # @api private
123
135
  def self.expand_task_list(value)
124
136
  raise ArgumentError.new unless value
125
137
  ret = value
@@ -127,23 +139,30 @@ module AWS
127
139
  ret
128
140
  end
129
141
 
142
+ # @api private
130
143
  def self.is_empty_field?(json_fragment, field_name)
131
144
  field = json_fragment[field_name]
132
145
  field.nil? || field.empty?
133
146
  end
134
147
 
135
- # This is used to issue the necessary "require" commands to
136
- # load the code needed to run a module
148
+ # Runs the necessary "require" commands to load the code needed to run a
149
+ # module.
137
150
  #
138
- # config_path: the path where the config file is, to be able to
151
+ # config_path: the path where the config file is, to be able to
139
152
  # resolve relative references
153
+ #
140
154
  # json_config: the content of the config
155
+ #
141
156
  # what: what should loaded. This is a hash expected to contain two keys:
157
+ #
142
158
  # - :default_file : the file to load unless a specific list is provided
159
+ #
143
160
  # - :config_key : the key of the config element which can contain a
144
- # specific list of files to load
161
+ # specific list of files to load
162
+ #
163
+ # @api private
145
164
  def self.load_files(config_path, json_config, what)
146
- if is_empty_field?(json_config, what[:config_key]) then
165
+ if is_empty_field?(json_config, what[:config_key]) then
147
166
  file = File.join(File.dirname(config_path), what[:default_file])
148
167
  require file if File.exists? file
149
168
  else
@@ -151,6 +170,14 @@ module AWS
151
170
  end
152
171
  end
153
172
 
173
+ # Starts the activity workers.
174
+ #
175
+ # The activities run by the workers consist of each class that extends
176
+ # [AWS::Flow::Activities] in the paths provided in the `activity_paths`
177
+ # section of [the runner specification file][], or that are loaded from
178
+ # `require` statements in the `workflows.rb` file.
179
+ #
180
+ # @api private
154
181
  def self.start_activity_workers(swf, domain = nil, config_path, json_config)
155
182
  workers = []
156
183
  # load all classes for the activities
@@ -178,6 +205,14 @@ module AWS
178
205
  return workers
179
206
  end
180
207
 
208
+ # Starts the workflow workers.
209
+ #
210
+ # The workflows run by the workers consist of each class that extends
211
+ # [AWS::Flow::Workflows] in the paths provided in the `workflow_paths`
212
+ # section of [the runner specification file][], or that are loaded from
213
+ # `require` statements in the `workflows.rb` file.
214
+ #
215
+ # @api private
181
216
  def self.start_workflow_workers(swf, domain = nil, config_path, json_config)
182
217
  workers = []
183
218
  # load all the classes for the workflows
@@ -202,23 +237,23 @@ module AWS
202
237
  return workers
203
238
  end
204
239
 
240
+ # @api private
205
241
  def self.create_service_client(json_config)
206
242
  # set the UserAgent prefix for all clients
207
243
  if json_config['user_agent_prefix'] then
208
244
  AWS.config(user_agent_prefix: json_config['user_agent_prefix'])
209
245
  end
210
-
246
+
211
247
  swf = AWS::SimpleWorkflow.new
212
248
  end
213
249
 
250
+ # Starts the workers and returns an array of process IDs (pids) for the
251
+ # worker processes.
214
252
  #
215
- # this will start all the workers and return an array of pids for the worker
216
- # processes
217
- #
253
+ # @api private
218
254
  def self.start_workers(domain = nil, config_path, json_config)
219
-
220
255
  workers = []
221
-
256
+
222
257
  swf = create_service_client(json_config)
223
258
 
224
259
  workers << start_activity_workers(swf, domain, config_path, json_config)
@@ -226,17 +261,20 @@ module AWS
226
261
 
227
262
  # needed to avoid returning nested arrays based on the calls above
228
263
  workers.flatten!
229
-
230
264
  end
231
265
 
232
- # setup forwarding of signals to child processes, to facilitate and support
233
- # orderly shutdown
266
+ # Sets up forwarding of signals to child processes to facilitate and
267
+ # support orderly shutdown.
268
+ #
269
+ # @api private
234
270
  def self.setup_signal_handling(workers)
235
271
  Signal.trap("INT") { workers.each { |w| Process.kill("INT", w) } }
236
272
  end
237
273
 
274
+ # Waits until all the child workers are finished.
275
+ #
238
276
  # TODO: use a logger
239
- # this will wait until all the child workers have died
277
+ # @api private
240
278
  def self.wait_for_child_processes(workers)
241
279
  until workers.empty?
242
280
  puts "waiting on workers " + workers.to_s + " to complete"
@@ -245,23 +283,32 @@ module AWS
245
283
  end
246
284
  end
247
285
 
248
- # this is used to extend the load path so that the 'require'
249
- # of workflow and activity implementation files can succeed
250
- # before adding the implementation classes to the workers
286
+ # Extends the load path so that the 'require' of workflow and activity
287
+ # implementation files can succeed before adding the implementation
288
+ # classes to the workers.
289
+ #
290
+ # @api private
251
291
  def self.add_dir_to_load_path(path)
252
292
  raise ArgumentError.new("Invalid directory path: \"" + path.to_s + "\"") if not FileTest.directory? path
253
293
  $LOAD_PATH.unshift path.to_s
254
294
  end
255
295
 
256
296
  #
257
- # loads the configuration from a JSON file
297
+ # Loads the runner specification from a JSON file (passed in with the
298
+ # `--file` parameter when run from the shell).
258
299
  #
300
+ # @api private
259
301
  def self.load_config_json(path)
260
302
  raise ArgumentError.new("Invalid file path: \"" + path.to_s + "\"") if not File.file? path
261
303
  config = JSON.parse(File.open(path) { |f| f.read })
262
304
  end
263
305
 
264
-
306
+ # Interprets the command-line paramters pased in from the shell.
307
+ #
308
+ # The parameter `--file` (short: `-f`) is *required*, and must provide the
309
+ # path to the runner configuration file.
310
+ #
311
+ # @api private
265
312
  def self.parse_command_line(argv = ARGV)
266
313
  options = {}
267
314
  optparse = OptionParser.new do |opts|
@@ -272,12 +319,16 @@ module AWS
272
319
 
273
320
  optparse.parse!(argv)
274
321
 
275
- # file parameter is not optional
322
+ # The `--file` parameter is not optional.
276
323
  raise OptionParser::MissingArgument.new("file") if options[:file].nil?
277
324
 
278
325
  return options
279
326
  end
280
327
 
328
+ #
329
+ # Invoked from the shell.
330
+ #
331
+ # @api private
281
332
  def self.main
282
333
  options = parse_command_line
283
334
  config_path = options[:file]
@@ -287,12 +338,10 @@ module AWS
287
338
  workers = start_workers(domain, config_path, config)
288
339
  setup_signal_handling(workers)
289
340
 
290
- # hang there until killed: this process is used to relay signals to children
291
- # to support and facilitate an orderly shutdown
341
+ # Hang there until killed: this process is used to relay signals to
342
+ # children to support and facilitate an orderly shutdown.
292
343
  wait_for_child_processes(workers)
293
-
294
344
  end
295
-
296
345
  end
297
346
  end
298
347
  end
@@ -14,7 +14,7 @@
14
14
  ##
15
15
 
16
16
  require 'yaml'
17
- require 'aws-sdk'
17
+ require 'aws-sdk-v1'
18
18
  require 'logger'
19
19
  require_relative 'setup'
20
20
 
metadata CHANGED
@@ -1,17 +1,17 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: aws-flow
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.0.1
4
+ version: 2.0.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Michael Steger, Paritosh Mohan, Jacques Thomas
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2014-08-22 00:00:00.000000000 Z
11
+ date: 2014-09-30 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
- name: aws-sdk
14
+ name: aws-sdk-v1
15
15
  requirement: !ruby/object:Gem::Requirement
16
16
  requirements:
17
17
  - - ~>
@@ -133,4 +133,3 @@ signing_key:
133
133
  specification_version: 4
134
134
  summary: AWS Flow Framework for Ruby
135
135
  test_files: []
136
- has_rdoc: