Retryable

Automatically retry a code block when an exception occurs.

require "retryable"
include Retryable

retryable(:tries => 3, :on => IOError) do
    read_flaky_sector
end

This calls read_flaky_sector and returns the result. If an IOError was raised, it tries the call again, and one more time (for 3 tries total) before giving up and letting the most recent exception propagate upward.

Install

• Bundler: gem "retryable", :git => "git://github.com/bronson/retryable.git"

You must include the module before using it. This allows unrelated libraries to set up their own defaults without any chance of conflicts.

class MyUtility
  include Retryable
  retryable_options :tries => 10
end

Options

Retryable uses these defaults:

• :tries => 2 # try the call once, then retry once
• :on => StandardError
• :sleep => 1
• :matching => /.*/
• :detect_nesting => false
• :logger => lambda { |task,retries,error| ... } # only logs if you specify a :task
• :task => nil

You can pass custom settings every time you call the retryable command, or call retryable_options to change the default settings:

retryable_options :tries => 5, :sleep => 20
retryable { catch_dog }

Sleeping

By default Retryable waits for one second between retries. You can change this, even providing your own exponential backoff scheme.

retryable(:sleep => 0) { }                    # no pause between retries
retryable(:sleep => 10) { }                   # sleep ten seconds between retries
retryable(:sleep => lambda { |n| 4**n }) { }  # sleep 1, 4, 16, etc. each try
retryable(:sleep => nil) { }                  # don't even call sleep

Disabling

If you set :tries to 0 then your block won't be called at all. You can use this to temporarialy disable all your retryable blocks:

retryable_options :tries => 0

Exceptions

Retryable retries any exception that inherits from StandardError. This catches most runtime errors (IOError, floating point) but lets most more catastrophic errors (missing method, nil reference) pass through without being retried.

Generally you only want to retry a few specific errors anyway:

:retryable(:on => [IOError, RangeError]) { ... }

You can certainly retry everything but, be warned, this is probably not what you want! Do you really want to retry method missing, out of memory, and a whole range of other errors that can't be fixed by trying again?

:retryable(:on => Exception) { ... }

More on Ruby exceptions:

• http://blog.nicksieger.com/articles/2006/09/06/rubys-exception-hierarchy
• http://www.zenspider.com/Languages/Ruby/QuickRef.html#34

You can also retry based on the exception message:

:retryable(:matching => /export/) { ... }

Block Parameters

Your block is called with two optional parameters: the number of tries until now, and the most recent exception.

retryable { |retries, exception|
  puts "try #{retries} failed: #{exception}" if retries > 0
  pick_up_soap
}

Logging

retryable offers a little logging assistance if you specify a task.

retryable(:task => 'pick up sticks') { raise IOError }

Prints:

pick up sticks
pick up sticks RETRY 1 because IOError

Use :logger to change the log message or destination:

retryable_options :logger => lambda { |task,retries,error|
    logger.error "retry #{task} #{retries}: #{error}" if retries > 0
}

Nesting

Accidentally nesting callbacks can be a real problem. What you thought was a 6 minute maximum delay could end up being 36 minutes or worse. Nesting detection is off by default but it's easy to turn on.

retryable(:detect_nesting => true) {
  retryable { thread_needle }   # thread_needle will never be called
}

When Retryable detects a nested call it throws a Retryable::NestedException. This is not a StandardError, so it's not retried by default, and the error will propagate out.

Examples

Open an URL, retry up to two more times when an OpenURI::HTTPError occurs.

require "retryable"
require "open-uri"

include Retryable

retryable(:tries => 3, :on => OpenURI::HTTPError) do
  xml = open("http://google.com/").read
end

Print the default settings:

ruby -r ./lib/retryable.rb -e "include Retryable; puts Retryable.retryable_options.inspect"

Alternatives

• NodeJS: https://github.com/tim-kos/node-retry

License

MIT or public domain, your choice.

History

The story until now...

• 2008 Cheah Chu Yeow wrote retryable as a monkeypatch to Kernel and wrote a blog post.
• 2009 Carlo Zottmann converted it to a gem and made it a separate method.
• 2010 Songkick converted it to a module and added :matching and :sleep.
• 2011 Scott Bronson rebased it back onto Chu's repo, added flexible sleep and nesting detection.