Module: Aws::ClientWaiters

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

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(subclass) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
# File 'lib/aws-sdk-core/client_waiters.rb', line 5

def self.included(subclass)
  class << subclass

    def set_waiters(waiters)
      @waiters =
        case waiters
        when Waiters::Provider then waiters
        when Hash then Waiters::Provider.new(waiters)
        when String, Pathname then Waiters::Provider.new(Aws.load_json(waiters))
        when nil then Waiters::NullProvider.new
        else raise ArgumentError, 'invalid waiters'
        end
    end

    def waiters
      @waiters
    end

  end
end

Instance Method Details

#wait_until(waiter_name, params = {}) {|waiter| ... } ⇒ Seahorse::Client::Response

Waits until a particular condition is satisfied. This works by polling a client request and checking for particular response data or errors. Waiters each have a default duration max attempts which are configurable. Additionally, you can register callbacks and stop waiters by throwing ‘:success` or `:failure`.

Examples:

Basic usage

client.wait_until(:waiter_name)

Configuring interval and maximum attempts

client.wait_until(:waiter_name) do |w|
  w.interval = 10    # number of seconds to sleep between attempts
  w.max_attempts = 6 # maximum number of polling attempts
end

Rescuing a failed wait

begin
  client.wait_until(:waiter_name)
rescue Aws::Waiters::Errors::WaiterFailed
  # gave up waiting
end

Waiting with progress callbacks

client.wait_until(:waiter_name) do |w|

  # yields just before polling for change
  w.before_attempt do |attempt|
    # attempts - number of previous attempts made
  end

  # yields before sleeping
  w.before_wait do |attempt, prev_response|
    # attempts - number of previous attempts made
    # prev_response - the last client response received
  end
end

Throw :success or :failure to terminate early

# wait for an hour, not for a number of requests
client.wait_until(:waiter_name) do |waiter|
  one_hour = Time.now + 3600
  waiter.max_attempts = nil
  waiter.before_attempt do |attempt|
    throw(:failure, 'waited to long') if Time.now > one_hour
  end
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:

Returns:

  • (Seahorse::Client::Response) —

    Returns the client response from the successful polling request. If ‘:success` is thrown from a callback, then the 2nd argument to `#throw` is returned.

Raises:

  • (Waiters::Errors::NoSuchWaiter) —

    Raised when the named waiter is not defined.

  • (Waiters::Errors::WaiterFailed) —

    Raised when one of the following conditions is met:

    • A failure condition is detected

    • The maximum number of attempts has been made without success

    • ‘:failure` is thrown from a callback



92
93
94
95
96
 
# File 'lib/aws-sdk-core/client_waiters.rb', line 92

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

#waiter_names ⇒ Array<Symbol>

Returns the list of supported waiters.

Returns:

  • (Array<Symbol>) 


100
101
102
 
# File 'lib/aws-sdk-core/client_waiters.rb', line 100

def waiter_names
  self.class.waiters.waiter_names
end