Permalink
Browse files

Improved README

  • Loading branch information...
1 parent ccd57fc commit dd47661dd28b945460d6de17b10ac7c19fde61ad @raul committed Oct 8, 2011
Showing with 46 additions and 19 deletions.
  1. +46 −19 README.md
View
65 README.md
@@ -1,44 +1,71 @@
# retry_upto: retry with steroids
+If you need to use `retry` in ruby, you probably want to retry some code only a **maximum number of times**,
+and sometimes **wait a bit** between the attempts to avoid external resources hiccups or usage limits.
+
+Therefore **Your Important Code** ends surrounded by counters, conditions and calls to `sleep`.
+
+This gem deals elegantly with this common scenario:
+
+ 5.times.retry do
+ # Your Important Code
+ end
+
+Keep reading to see all the options available.
+
## Usage
-Basic usage
+### Basic usage
+
+Retries up to 5 times catching any exception, doesn't wait between attempts:
-- retries up to 5 times catching any exception, doesn't wait between attempts:
+ retry_upto(5)
- retry_upto(5) do ... end
+### Waiting time between attempts
-Waiting time between attempts
+Retries up to 5 times, waits 2 seconds between attempts:
-- retries up to 5 times, waits 2 seconds between attempts:
+ retry_upto(5, :interval => 2)
- retry_upto(5, :interval => 2) do ... end
+### Varying waiting time between attempts
-Varying waiting time between attempts
+Retries up to 5 times, waits 1 second after the first attempt and increases
+the time between the following attempts (2, 4, 8, ...):
-- retries up to 5 times, waits 1 second after the first attempt and increases
- the time between the following attempts (2, 4, 8, ...):
+ retry_upto(5, :interval => 1, :growth => 2)
- retry_upto(5, :interval => 1, :growth => 2) do ... end
+Retries up to 5 times, waits 1 second after the first attempt and decreases
+the time between the following attempts (0.5, 0.25, 0.125, ...):
-- retries up to 5 times, waits 1 second after the first attempt and decreases
- the time between the following attempts (0.5, 0.25, 0.125, ...):
+ retry_upto(5, :interval => 1, :growth => 0.5)
- retry_upto(5, :interval => 1, :growth => 0.5) do ... end
+Retries up to 5 times, waits 1 second after the first attempt and increases
+randomly the time between the following attempts:
-- retries up to 5 times, waits 1 second after the first attempt and increases
- randomly the time between the following attempts:
+ retry_upto(5, :interval => 1, :growth => lambda{ |x| x + rand(3) } )
- retry_upto(5, :interval => 1, :growth => lambda{ |x| x + rand(3) } ) do ... end
+### Retrying only when certain Exceptions get raised
-Retrying only when certain Exceptions get raised
+Retries up to 5 times only after a ZeroDivisionError, raising any other Exception:
-- retries up to 5 times only after a ZeroDivisionError, raising any other Exception:
+ retry_upto(5, :rescue => ZeroDivisionError)
- retry_upto(5, :rescue => ZeroDivisionError) do ... end
+Retries up to 5 times only after a ZeroDivisionError or a NameError, raising any other Exception:
+
+ retry_upto(5, :rescue => [ZeroDivisionError, NameError])
All the options described above can be combined together.
+### More sugar!
+
+In ruby 1.9, the `Enumerator` class gets enhanced to use `retry_upto` this way:
+
+ 5.times.retry
+
+And yes, this accepts the same options:
+
+ 5.times.retry(:interval => 10)
+
## License
See the LICENSE file included in the distribution.

0 comments on commit dd47661

Please sign in to comment.