Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Improved README

  • Loading branch information...
commit dd47661dd28b945460d6de17b10ac7c19fde61ad 1 parent ccd57fc
raul murciano authored October 08, 2011

Showing 1 changed file with 46 additions and 19 deletions. Show diff stats Hide diff stats

  1. 65  README.md
65  README.md
Source Rendered
... ...
@@ -1,44 +1,71 @@
1 1
 # retry_upto: retry with steroids
2 2
 
  3
+If you need to use `retry` in ruby, you probably want to retry some code only a **maximum number of times**,
  4
+and sometimes **wait a bit** between the attempts to avoid external resources hiccups or usage limits.
  5
+
  6
+Therefore **Your Important Code** ends surrounded by counters, conditions and calls to `sleep`.
  7
+
  8
+This gem deals elegantly with this common scenario:
  9
+
  10
+    5.times.retry do
  11
+      # Your Important Code
  12
+    end
  13
+
  14
+Keep reading to see all the options available.
  15
+
3 16
 ## Usage
4 17
 
5  
-Basic usage
  18
+### Basic usage
  19
+
  20
+Retries up to 5 times catching any exception, doesn't wait between attempts:
6 21
 
7  
-- retries up to 5 times catching any exception, doesn't wait between attempts:
  22
+    retry_upto(5)
8 23
 
9  
-    retry_upto(5) do ... end
  24
+### Waiting time between attempts
10 25
 
11  
-Waiting time between attempts
  26
+Retries up to 5 times, waits 2 seconds between attempts:
12 27
 
13  
-- retries up to 5 times, waits 2 seconds between attempts:
  28
+    retry_upto(5, :interval => 2)
14 29
 
15  
-   retry_upto(5, :interval => 2) do ... end
  30
+### Varying waiting time between attempts
16 31
 
17  
-Varying waiting time between attempts
  32
+Retries up to 5 times, waits 1 second after the first attempt and increases
  33
+the time between the following attempts (2, 4, 8, ...):
18 34
 
19  
-- retries up to 5 times, waits 1 second after the first attempt and increases
20  
-  the time between the following attempts (2, 4, 8, ...):
  35
+    retry_upto(5, :interval => 1, :growth => 2)
21 36
 
22  
-    retry_upto(5, :interval => 1, :growth => 2) do ... end
  37
+Retries up to 5 times, waits 1 second after the first attempt and decreases
  38
+the time between the following attempts (0.5, 0.25, 0.125, ...):
23 39
 
24  
-- retries up to 5 times, waits 1 second after the first attempt and decreases
25  
-  the time between the following attempts (0.5, 0.25, 0.125, ...):
  40
+    retry_upto(5, :interval => 1, :growth => 0.5)
26 41
 
27  
-    retry_upto(5, :interval => 1, :growth => 0.5) do ... end
  42
+Retries up to 5 times, waits 1 second after the first attempt and increases
  43
+randomly the time between the following attempts:
28 44
 
29  
-- retries up to 5 times, waits 1 second after the first attempt and increases
30  
-  randomly the time between the following attempts:
  45
+    retry_upto(5, :interval => 1, :growth => lambda{ |x| x + rand(3) } )
31 46
 
32  
-    retry_upto(5, :interval => 1, :growth => lambda{ |x| x + rand(3) } ) do ... end
  47
+### Retrying only when certain Exceptions get raised
33 48
 
34  
-Retrying only when certain Exceptions get raised
  49
+Retries up to 5 times only after a ZeroDivisionError, raising any other Exception:
35 50
 
36  
-- retries up to 5 times only after a ZeroDivisionError, raising any other Exception:
  51
+    retry_upto(5, :rescue => ZeroDivisionError)
37 52
 
38  
-    retry_upto(5, :rescue => ZeroDivisionError) do ... end
  53
+Retries up to 5 times only after a ZeroDivisionError or a NameError, raising any other Exception:
  54
+
  55
+    retry_upto(5, :rescue => [ZeroDivisionError, NameError])
39 56
 
40 57
 All the options described above can be combined together.
41 58
 
  59
+### More sugar!
  60
+
  61
+In ruby 1.9, the `Enumerator` class gets enhanced to use `retry_upto` this way:
  62
+
  63
+    5.times.retry
  64
+
  65
+And yes, this accepts the same options:
  66
+
  67
+    5.times.retry(:interval => 10)
  68
+
42 69
 ## License
43 70
 
44 71
 See the LICENSE file included in the distribution.

0 notes on commit dd47661

Please sign in to comment.
Something went wrong with that request. Please try again.