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(Json.load_file(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| ... } ⇒ 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:

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.



107
108
109
110
111
 
# File '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.

Returns:

  • (Array<Symbol>) 


115
116
117
 
# File 'lib/aws-sdk-core/client_waiters.rb', line 115

def waiter_names
  self.class.waiters.waiter_names
end