attempt 0.1.0

data/CHANGES

@@ -0,0 +1,2 @@
+== 0.1.0 - 9-Jun-2006
+* Initial commit

data/MANIFEST

@@ -0,0 +1,9 @@
+CHANGES
+MANIFEST
+README
+install.rb
+attempt.gemspec
+
+lib/attempt.rb
+
+test/tc_attempt.rb

data/README

@@ -0,0 +1,64 @@
+== Description
+   A thin wrapper for begin + rescue + sleep + retry.
+
+== Prerequisites
+   Ruby 1.8.0 or later.
+   
+== Installation
+=== Standard Installation
+   ruby test/tc_attempt.rb
+   ruby install.rb
+
+=== Gem Installation
+   ruby test/tc_attempt.rb
+   ruby attempt.gemspec
+   gem install attempt-x-y-z.gem # Where x-y-z is a version
+   
+== Synopsis
+   require 'attempt'
+   
+   # Attempt to ftp to some host, trying 3 times with 30 seconds between
+   # attempts before finally raising an error.
+   #
+   attempt(3, 30){
+      Net::FTP.open(host, user, passwd){ ... }
+   }
+   
+   # Or, do things the long way...
+   code = Attempt.new{ |a|
+      a.tries    = 3
+      a.interval = 30
+   }
+   
+   code.attempt{
+   	  Net::FTP.open(host, user, passwd){ ... }
+   }
+
+== Future Plans
+   Add the ability to set an absolute maximum number of seconds to prevent
+   nested sleep/retry from delaying attempts longer than expected.
+
+== Known Bugs
+   None that I'm aware of.  If you find any bugs, please log them on the
+   project page at http://www.rubyforge.org/projects/shards.
+
+== Notes From the Author
+   Use with caution.  Specifically, make sure you aren't inadvertantly
+   wrapping code that already performs sleep + retry.  Otherwise, you'll
+   end up with a series of nested retry's that could take much longer to
+   work than you expect. 
+
+== Warranty
+   This package is provided "as is" and without any express or
+   implied warranties, including, without limitation, the implied
+   warranties of merchantability and fitness for a particular purpose.
+
+== License
+   Ruby's
+
+== Copyright
+   (C) 2006, Daniel J. Berger
+   All Rights Reserved
+
+== Author
+   Daniel J. Berger

data/lib/attempt.rb

@@ -0,0 +1,99 @@
+require 'timeout'
+
+class Attempt
+   VERSION = '0.1.0'
+   
+   # Number of attempts to make before failing.  The default is 3.
+   attr_accessor :tries
+   
+   # Number of seconds to wait between attempts.  The default is 60.
+   attr_accessor :interval
+   
+   # A boolean value that determines whether errors that would have been
+   # raised should be sent to STDERR as warnings.  The default is true.
+   attr_accessor :warnings
+   
+   # If you provide an IO handle to this option then errors that would
+   # have been raised are sent to that handle.
+   attr_accessor :log
+   
+   # If set, this increments the interval with each failed attempt by that
+   # number of seconds.
+   attr_accessor :increment
+   
+   # If set, the code block is further wrapped in a timeout block.
+   attr_accessor :timeout
+   
+   # Determines which exception level to check when looking for errors to
+   # retry.  The default is 'Exception' (i.e. all errors).
+   attr_accessor :level
+   
+   # :call-seq:
+   #    Attempt.new{ |a| ... }
+   # 
+   # Creates and returns a new +Attempt+ object.  Use a block to set the
+   # accessors.
+   # 
+   def initialize           
+      @tries     = 3         # Reasonable default
+      @interval  = 60        # Reasonable default
+      @log       = nil       # Should be an IO handle, if provided
+      @increment = nil       # Should be an int, if provided
+      @timeout   = nil       # Wrap the code in a timeout block if provided
+      @level     = Exception # Level of exception to be caught
+      @warnings  = true      # Errors sent to STDERR as warnings if true
+      
+      yield self if block_given?
+   end
+   
+   def attempt
+      count = 1
+      begin
+         if @timeout
+            Timeout.timeout(@timeout){ yield }
+         else
+            yield
+         end
+      rescue @level => error
+         @tries -= 1
+         if @tries > 0
+            msg = "Error on attempt # #{count}: #{error}; retrying"
+            count += 1
+            warn msg if @warnings
+            @log.puts msg if @log
+            @interval += @increment if @increment
+            sleep @interval
+            retry
+         end
+         raise
+      end
+   end
+end
+
+module Kernel
+   # attempt(tries = 3, interval = 60, timeout = nil){ # some op }
+   # 
+   # Attempt to perform the operation in the provided block up to +tries+
+   # times, sleeping +interval+ between each try.  By default the number
+   # of tries defaults to 3, the interval defaults to 60 seconds, and there
+   # is no timeout specified.
+   # 
+   # If +timeout+ is provided then the operation is wrapped in a Timeout
+   # block as well.  This is handy for those rare occasions when an IO
+   # connection could hang indefinitely, for example.
+   # 
+   # If the operation still fails the (last) error is then re-raised.
+   #
+   # This is really just a wrapper for Attempt.new where the simple case is
+   # good enough i.e. you don't care about warnings, increments or logging,
+   # and you want a little added convenience.
+   # 
+   def attempt(tries = 3, interval = 60, timeout = nil, &block)
+      raise 'no block given' unless block_given?
+      Attempt.new{ |a|
+         a.tries    = tries
+         a.interval = interval
+         a.timeout  = timeout if timeout
+      }.attempt(&block)
+   end
+end

data/test/tc_attempt.rb

@@ -0,0 +1,42 @@
+###########################################################
+# tc_attempt.rb
+#
+# Test case for the attempt package.
+###########################################################
+Dir.chdir('..') if File.basename(Dir.pwd) == 'test'
+$LOAD_PATH.unshift(Dir.pwd + '/lib')
+
+require 'attempt'
+require 'test/unit'
+
+print "\n== You will see a warning or two when running these tests ==\n\n"
+
+class TC_Attempt < Test::Unit::TestCase
+   def setup
+      @tries    = 2
+      @interval = 0.1
+      @timeout  = 0.1
+   end
+   
+   def test_version
+      assert_equal('0.1.0', Attempt::VERSION)
+   end
+   
+   def test_attempt_basic
+      assert_nothing_raised{ attempt{ 2 + 2 } }
+      assert_nothing_raised{ attempt(@tries){ 2 + 2 } }
+      assert_nothing_raised{ attempt(@tries, @interval){ 2 + 2 } }
+      assert_nothing_raised{ attempt(@tries, @interval, @timeout){ 2 + 2 } }
+   end
+   
+   def test_attempt_expected_errors
+      assert_raises(Timeout::Error){ attempt(1, 1, @timeout){ sleep 5 } }
+      assert_raises(RuntimeError){ attempt(2,2){ raise } }
+   end
+   
+   def teardown
+      @tries    = nil
+      @interval = nil
+      @timeout  = nil
+   end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: attempt
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+date: 2006-06-09 00:00:00 -05:00
+summary: A thin wrapper for begin + rescue + sleep + retry
+require_paths: 
+- lib
+email: djberg96@gmail.com
+homepage: http://www.rubyforge.org/projects/shards
+rubyforge_project: 
+description: A thin wrapper for begin + rescue + sleep + retry
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+- Daniel J. Berger
+files: 
+- lib/attempt.rb
+- CHANGES
+- CVS
+- MANIFEST
+- README
+- test/CVS
+- test/tc_attempt.rb
+test_files: 
+- test/tc_attempt.rb
+rdoc_options: []
+
+extra_rdoc_files: 
+- README
+- CHANGES
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+