retry_block 1.0.2 → 1.1.0

data/README.rdoc

@@ -0,0 +1,183 @@
+== README: retry_block
+
+<i>Take control of unstable or indeterminate code with retry_block.</i>
+
+The retry_block method allows you to easily retry a block of code a given
+number of times or until successful.  You may specify a failure callback to
+be called each time the block of code fails.
+
+=== A Quick Example
+
+Sometimes examples are more useful than words:
+
+  require 'retry_block'
+  
+  fail_callback = lambda do |attempt, exception|
+    puts "attempt ##{attempt} failed.  Sleeping 1 second"
+  end
+ 
+  retry_block(:fail_callback => fail_callback, :sleep => 1) do |attempt|
+    raise "Never see this exception" if attempt <= 5
+    puts "Success!"
+  end
+
+In the above code, an exception is raised for the first 5 tries of the
+block of code given to retry_block.  Upon each failure the fail_callback
+lambda is called, printing out a message warning the user that the block
+failed.  Also upon each failure retry_block sleeps for one second.  On the
+last attempt the block succeeds and exits.  Here is the output from running
+the above code:
+
+  attempt #1 failed.  Sleeping 1 second
+  attempt #2 failed.  Sleeping 1 second
+  attempt #3 failed.  Sleeping 1 second
+  attempt #4 failed.  Sleeping 1 second
+  attempt #5 failed.  Sleeping 1 second
+  Success!
+
+=== Maximum Attempts
+
+Notice that by default retry_block will retry a block of code until it
+succeed.  If you want to apply a maximum amount of times to retry, pass
+that number to the <tt>:attempts</tt> option.  Here is an example where a
+block of code is run 3 times and finally fails:
+
+  require 'retry_block'
+  
+  retry_block(:attempts => 3) do
+    puts "trying"
+    raise RuntimeError, "I Failed!"
+  end
+
+Here is the output of the above code:
+
+  trying
+  trying
+  trying
+  I Failed! (RuntimeError)
+
+Notice that if the block of code fails the maximum number of times,
+retry_block will raise the exception to the calling code.
+
+=== Catching Specific Exceptions
+
+It is possible to tell retry_block which exceptions to catch.  Pass either
+an exception or a list of exceptions to the <tt>:catch</tt> option.  By
+default retry_block watches for <tt>Exception</tt>.  If the block of code
+raises an exception that is not watched by retry_block, the exception will
+be raised to the calling code.  Note that the :fail_callback callback will
+NOT be called when an unexpected exception occurs.  Here is an example to
+demonstrate:
+
+  require 'retry_block'
+
+  class UnexpectedError < Exception; end
+  
+  # Run forever until success or an unexpected exception occurs.
+  retry_block(:catch => [RuntimeError, ArgumentError]) do |attempts|
+    puts "retrying"
+    raise UnexpectedError if attempts == 10
+    raise RuntimeError if (attempts % 2) == 0
+    raise ArgumentError if (attempts % 2) == 1
+  end
+
+The output of the above code is:
+
+  retrying
+  retrying
+  retrying
+  retrying
+  retrying
+  retrying
+  retrying
+  retrying
+  retrying
+  retrying
+  UnexpectedError (UnexpectedError)
+
+Notice that in the code above, retry_block gracefully handles RuntimeError
+and ArgumentError because these have been passed to the <tt>:catch</tt>
+option.  But when <tt>UnexpectedError</tt> occurs, the exception is raised
+to the calling code.
+
+=== Sleeping Between Attempts
+
+Finally, retry_block has a <tt>:sleep</tt> option.  Use this when you
+require that there is a pause between retries of the block of code.  This
+is often handy, for instance, when relying on external events (network IO,
+user IO, etc.)
+
+  require 'retry_block'
+  
+  callback = lambda do puts "sleeping 1 second" end
+  
+  retry_block(:attempts => 3, :sleep => 1, :fail_callback => callback) do |attempts|
+    raise unless attempts == 3
+    puts "finished"
+  end
+
+The output of the above code is:
+
+  sleeping 1 second
+  sleeping 1 second
+  finished
+
+In the above code, we see that we ask retry_block to retry a total of 3
+times.  The first two tries fail, resulting in sleeping 1 second each.  The
+last attempt is successful.
+
+=== Block Failure Callback
+
+It is possible to provide a callback Proc or lambda to the
+<tt>:fail_callback</tt> option.  Anytime that an exception occurs in your
+code that is handled by the <tt>:catch</tt> option (which is all exceptions
+by default), the callback provided will be called.  Your callback can
+optionally be called with the current attempt number and the exception
+caught.  Here is an example:
+
+  require 'retry_block'
+  
+  callback = lambda do |attempt, exception|
+    puts "Failure ##{attempt} with message: #{exception.message}"
+  end
+ 
+  retry_block(:fail_callback => callback) do |attempt|
+    raise "Foo" if attempt == 1
+    raise "Bar" if attempt == 2
+    raise "Baz" if attempt == 3
+    puts "Finished"
+  end
+
+The output of the above code is:
+
+  Failure #1 with message: Foo
+  Failure #1 with message: Bar
+  Failure #1 with message: Baz
+  Finished
+
+This can be useful if, for instance, you would like to sleep for
+exponentially longer periods of time after each attempt:
+
+  require 'retry_block'
+ 
+  callback = lambda do |attempt|
+    # Sleep longer and longer, maxing out at 16
+    sleep_time = [16, 2**(attempt-1)].min
+    puts "Failed again!  Sleeping #{sleep_time} seconds ..."
+    sleep sleep_time
+  end
+
+  retry_block(:fail_callback => callback) do |attempt|
+    raise if attempt <= 6
+    puts "Finished"
+  end
+
+The output of the above code is:
+
+  Failed again!  Sleeping 1 seconds ...
+  Failed again!  Sleeping 2 seconds ...
+  Failed again!  Sleeping 4 seconds ...
+  Failed again!  Sleeping 8 seconds ...
+  Failed again!  Sleeping 16 seconds ...
+  Failed again!  Sleeping 16 seconds ...
+  Finished

data/lib/retry_block/version.rb

@@ -1,3 +1,3 @@
 module RetryBlock
-  VERSION = "1.0.2"
+  VERSION = "1.1.0"
 end

data/lib/retry_block.rb

@@ -26,8 +26,10 @@ module Kernel
         opts[:fail_callback].call *callback_opts
       end
       
+      attempts += 1
+
       # If we've maxed out our attempts, raise the exception to the calling code
-      raise if (not opts[:attempts].nil?) and (attempts += 1) > opts[:attempts]
+      raise if (not opts[:attempts].nil?) and attempts > opts[:attempts]
 
       # Sleep before the next retry if the option was given
       sleep opts[:sleep] if opts[:sleep].is_a? Numeric and opts[:sleep] > 0

data/test/test_retry_block.rb

@@ -168,6 +168,37 @@ class TestRetryBlock < Test::Unit::TestCase
     assert_equal 100, @run_count
     assert_equal 99, @fail_count
   end
+
+  def test_attempts_passed_to_fail_callback
+    test_counter = 0
+    test_callback = lambda do |attempt, exception|
+      test_counter += 1
+      assert_equal test_counter, attempt
+    end
+    retry_block(:attempts => 3, :fail_callback => test_callback) do
+      @run_count += 1
+      raise TestException unless @run_count == 3
+    end
+    assert_equal 3, @run_count
+  end
+
+  def test_attempts_passed_to_block
+    retry_block(:attempts => 3) do |attempts|
+      @run_count += 1
+      assert_equal @run_count, attempts
+      raise TestException unless @run_count == 3
+    end
+    assert_equal 3, @run_count
+  end
+
+  def test_attempts_incremented_when_run_forever
+    retry_block() do |attempts|
+      @run_count += 1
+      assert_equal @run_count, attempts
+      raise TestException unless @run_count == 10
+    end
+    assert_equal 10, @run_count
+  end
 end
 
 class TestException < Exception

metadata

@@ -5,9 +5,9 @@ version: !ruby/object:Gem::Version
   prerelease: 
   segments: 
   - 1
+  - 1
   - 0
-  - 2
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors: 
 - Alfred J. Fazio
@@ -30,6 +30,7 @@ extra_rdoc_files: []
 files: 
 - .gitignore
 - Gemfile
+- README.rdoc
 - Rakefile
 - lib/retry_block.rb
 - lib/retry_block/version.rb