You are viewing documentation for version 2 of the AWS SDK for Ruby. Version 3 documentation can be found here.

Module: Aws::ClientWaiters

Included in:: Client

Defined in:: aws-sdk-core/lib/aws-sdk-core/client_waiters.rb

Instance Method Summary collapse

#wait_until(waiter_name, params = {}) {|waiter| ... } ⇒ Boolean
Waiters polls an API operation until a resource enters a desired state.
#waiter_names ⇒ Array<Symbol>
Returns the list of supported waiters.

Instance Method Details

#wait_until(waiter_name, params = {}) {|waiter| ... } ⇒ `Boolean`

Waiters polls an API operation until a resource enters a desired state.

Basic Usage

Waiters will poll until they are succesful, they fail by entering a terminal state, or until a maximum number of attempts are made.

# polls in a loop, sleeping between attempts client.waiter_until(waiter_name, params)

Configuration

You can configure the maximum number of polling attempts, and the delay (in seconds) between each polling attempt. You configure waiters by passing a block to #wait_until:

# poll for ~25 seconds
client.wait_until(...) do |w|
  w.max_attempts = 5
  w.delay = 5
end

Callbacks

You can be notified before each polling attempt and before each delay. If you throw :success or :failure from these callbacks, it will terminate the waiter.

started_at = Time.now
client.wait_until(...) do |w|

  # disable max attempts
  w.max_attempts = nil

  # poll for 1 hour, instead of a number of attempts
  w.before_wait do |attempts, response|
    throw :failure if Time.now - started_at > 3600
  end

end

Handling Errors

When a waiter is successful, it returns true. When a waiter fails, it raises an error. All errors raised extend from Waiters::Errors::WaiterFailed.

begin
  client.wait_until(...)
rescue Aws::Waiters::Errors::WaiterFailed
  # resource did not enter the desired state in time
end

Parameters:

waiter_name (Symbol) —
The name of the waiter. See #waiter_names for a full list of supported waiters.
params (Hash) (defaults to: {}) —
Additional request parameters. See the #waiter_names for a list of supported waiters and what request they call. The called request determines the list of accepted parameters.

Yield Parameters:

waiter (Waiters::Waiter) —
Yields a Waiter object that can be configured prior to waiting.

Returns:

(Boolean) —
Returns true if the waiter was successful.

Raises:

(Errors::FailureStateError) —
Raised when the waiter terminates because the waiter has entered a state that it will not transition out of, preventing success.
(Errors::TooManyAttemptsError) —
Raised when the configured maximum number of attempts have been made, and the waiter is not yet successful.
(Errors::UnexpectedError) —
Raised when an error is encounted while polling for a resource that is not expected.
(Errors::NoSuchWaiterError) —
Raised when you request to wait for an unknown state.

# File 'aws-sdk-core/lib/aws-sdk-core/client_waiters.rb', line 107

def wait_until(waiter_name, params = {}, &block)
  waiter = self.class.waiters.waiter(waiter_name)
  yield(waiter) if block_given?
  waiter.wait(client:self, params:params)
end

#waiter_names ⇒ `Array<Symbol>`

Returns the list of supported waiters.