Using Waiters - AWS SDK for Ruby

Using Waiters

Waiters are utility methods that poll for a particular state to occur on a client. Waiters can fail after a number of attempts at a polling interval defined for the service client. For an example of how a waiter is used, see Creating an Amazon DynamoDB Table.

Invoking a Waiter

To invoke a waiter, call #wait_until on a service client. In the following example, a waiter waits until the instance i-12345678 is running before continuing.

ec2 = begin ec2.wait_until(:instance_running, instance_ids:['i-12345678']) puts "instance running" rescue Aws::Waiters::Errors::WaiterFailed => error puts "failed waiting for instance running: #{error.message}" end

The first parameter is the waiter name, which is specific to the service client and indicates which operation is being waited for. The second parameter is a hash of parameters that are passed to the client method called by the waiter, which varies according to the waiter name.

For a list of operations that can be waited for and the client methods called for each operation, see the #waiter_names and #wait_until field documentation for the client you are using.

Wait Failures

Waiters can fail with any of the following exceptions.


A failure state was encountered while waiting.


The specified waiter name is not defined for the client being used.


The number of attempts exceeded the waiter’s max_attempts value.


An unexpected error occurred while waiting.


One of the wait states was exceeded or another failure occurred while waiting.

All of these errors—except NoSuchWaiterError—are based on WaiterFailed. To catch errors in a waiter, use WaiterFailed, as shown in the following example.

rescue Aws::Waiters::Errors::WaiterFailed => error puts "failed waiting for instance running: #{error.message}" end

Configuring a Waiter

Each waiter has a default polling interval and a maximum number of attempts it will make before returning control to your program. To set these values, use the max_attempts and delay: parameters in your #wait_until call. The following example waits for up to 25 seconds, polling every five seconds.

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

To disable wait failures, set the value of either of these parameters to nil.

Extending a Waiter

To modify the behavior of waiters, you can register callbacks that are triggered before each polling attempt and before waiting.

The following example implements an exponential backoff in a waiter by doubling the amount of time to wait on every attempt.

ec2 = ec2.wait_until(:instance_running, instance_ids:['i-12345678']) do |w| w.interval = 0 # disable normal sleep w.before_wait do |n, resp| sleep(n ** 2) end end

The following example disables the maximum number of attempts, and instead waits for one hour (3600 seconds) before failing.

started_at = client.wait_until(...) do |w| # Disable max attempts w.max_attempts = nil # Poll for one hour, instead of a number of attempts w.before_wait do |attempts, response| throw :failure if - started_at > 3600 end end