wait 0.2.2 → 0.3.2

data/lib/wait.rb

@@ -1,62 +1,59 @@
-require "timeout"
-require "logger"
+require File.expand_path("../initialize", __FILE__)
 
 class Wait
+  DEFAULT = {
+    :timeout  => 15,
+    :logger   => BaseLogger,
+    :attempts => 5,
+    :counter  => BaseCounter,
+    :delay    => 1,
+    :delayer  => RegularDelayer,
+    :tester   => TruthyTester,
+    :rescuer  => PassiveRescuer
+  }
+
   # Creates a new Wait instance.
   #
   # == Options
   #
   # [:attempts]
-  #   Number of times to attempt the block. Default is +5+.
+  #   Number of times to attempt the block (passed to +counter+). Default is
+  #   +5+.
+  # [:counter]
+  #   Strategy used to count attempts. Default is Wait::BaseCounter.
   # [:timeout]
   #   Seconds until the block times out. Default is +15+.
+  # [:delay]
+  #   Seconds to delay in between attempts (passed to +delayer+). Default is
+  #   +1+.
   # [:delayer]
-  #   Delay strategy to use to sleep in between attempts. Default is
-  #   +Wait::RegularDelayer.new+.
+  #   Strategy used to delay in between attempts. Default is
+  #   Wait::RegularDelayer.
   # [:rescue]
-  #   One or an array of exceptions to rescue. Default is +nil+.
+  #   One or an array of exceptions to rescue (passed to +rescuer+). Default
+  #   is +nil+.
+  # [:rescuer]
+  #   Strategy used to handle exceptions. Default is Wait::PassiveRescuer.
   # [:tester]
-  #   Strategy to use to test the result. Default is +Wait::TruthyTester+.
+  #   Strategy used to test the result. Default is Wait::TruthyTester.
   # [:logger]
-  #   Ruby logger to use. Default is +Wait#logger+.
+  #   Ruby logger used. Default is Wait::BaseLogger.
   #
   def initialize(options = {})
-    @attempts   = options[:attempts] || 5
-    @timeout    = options[:timeout]  || 15
-    @delayer    = options[:delayer]  || RegularDelayer.new
-    @exceptions = Array(options[:rescue])
-    @tester     = options[:tester]   || TruthyTester
-    @logger     = options[:logger]   || logger
-
-    @counter = AttemptCounter.new(@attempts)
-
-    validate_strategies
+    @timeout    = options[:timeout]            || DEFAULT[:timeout]
+    debug       = options[:debug]
+    @logger     = (options[:logger]            || (debug ? DebugLogger : DEFAULT[:logger])).new
+    attempts    = options[:attempts]           || DEFAULT[:attempts]
+    @counter    = (options[:counter]           || DEFAULT[:counter]).new(@logger, attempts)
+    delay       = options[:delay]              || DEFAULT[:delay]
+    @delayer    = (options[:delayer]           || DEFAULT[:delayer]).new(@logger, delay)
+    @tester     = (options[:tester]            || DEFAULT[:tester]).new(@logger)
+    exceptions  = Array(options[:rescue])
+    @rescuer    = (options[:rescuer]           || DEFAULT[:rescuer]).new(@logger, @tester.exceptions, exceptions)
   end
 
-  # Validates all of the assigned strategy objects.
-  def validate_strategies
-    unless @delayer.respond_to?(:sleep)
-      raise(ArgumentError, "delay strategy does not respond to sleep message: #{@delayer.inspect}")
-    end
-
-    unless @tester.respond_to?(:new)
-      raise(ArgumentError, "tester strategy does not respond to new message: #{@tester.inspect}")
-    end
-
-    unless @tester.new.respond_to?(:valid?)
-      raise(ArgumentError, "tester strategy does not respond to valid? message: #{@tester.inspect}")
-    end
-  end
-
-  # Returns a new (or existing) logger instance.
-  def logger
-    if @logger.nil?
-      @logger = Logger.new(STDOUT)
-      @logger.level = Logger::WARN
-    end
-
-    @logger
-  end
+  # Raised when a block times out.
+  class TimeoutError < Timeout::Error; end
 
   # == Description
   #
@@ -64,7 +61,7 @@ class Wait
   # result. Useful for blocking script execution until:
   # * an HTTP request was successful
   # * a port has opened
-  # * an external process has started
+  # * a process has started
   # * etc.
   #
   # == Examples
@@ -72,8 +69,11 @@ class Wait
   #   wait = Wait.new
   #   # => #<Wait>
   #   wait.until { Time.now.sec.even? }
-  #   # Rescued exception while waiting: Wait::TruthyTester::ResultNotTruthy: false
-  #   # Attempt 1/5 failed, delaying for 1s
+  #   # [Tester] result: false
+  #   # [Rescuer] rescued: Wait::TruthyTester::ResultNotTruthy: false
+  #   # [Counter] attempt 1/5 failed
+  #   # [Delayer] delaying for 1s
+  #   # [Tester] result: true
   #   # => true
   #
   # If you wish to handle an exception by attempting the block again, pass one
@@ -88,10 +88,14 @@ class Wait
   #     when 3 then "foo"
   #     end
   #   end
-  #   # Rescued exception while waiting: Wait::TruthyTester::ResultNotTruthy: nil
-  #   # Attempt 1/5 failed, delaying for 1s
-  #   # Rescued exception while waiting: RuntimeError: RuntimeError
-  #   # Attempt 2/5 failed, delaying for 2s
+  #   # [Tester] result: nil
+  #   # [Rescuer] rescued: Wait::TruthyTester::ResultNotTruthy: nil
+  #   # [Counter] attempt 1/5 failed
+  #   # [Delayer] delaying for 1s
+  #   # [Rescuer] rescued: RuntimeError: RuntimeError
+  #   # [Counter] attempt 2/5 failed
+  #   # [Delayer] delaying for 1s
+  #   # [Tester] result: "foo"
   #   # => "foo"
   #
   # == Returns
@@ -105,111 +109,25 @@ class Wait
   def until(&block)
     # Reset the attempt counter.
     @counter.reset
-
     begin
+      # Increment the attempt counter.
       @counter.increment
-
-      result = Timeout.timeout(@timeout, Wait::TimeoutError) do
-        # Execute the block and pass the attempt count to it.
+      # Wrap the given block in a timeout.
+      result = Timeout.timeout(@timeout, TimeoutError) do
+        # Execute the block and pass the attempt count (an +Integer+) to it.
         yield(@counter.attempt)
       end
-
-      tester = @tester.new(result)
-      tester.raise_unless_valid
-    rescue Wait::TimeoutError, *(@tester.exceptions + @exceptions) => exception
-      logger.debug "Rescued exception while waiting: #{exception.class.name}: #{exception.message}"
-      logger.debug exception.backtrace.join("\n")
-
-      # If this was the last attempt, raise the exception from the last
-      # attempt.
-      if @counter.last_attempt?
-        raise(exception)
-      else
-        logger.debug "Attempt #{@counter} failed, delaying for #{@delayer}"
-        @delayer.sleep
-        retry
-      end
-    end
-  end
-
-  # Raised when a block doesn't return a result (+nil+ or +false+).
-  class NoResultError < StandardError; end
-
-  # Raised when a block times out.
-  class TimeoutError < Timeout::Error; end
-
-  class RegularDelayer
-    def initialize(initial_delay = 1)
-      @delay = initial_delay
-    end
-
-    def sleep
-      Kernel.sleep(@delay)
-    end
-
-    def to_s
-      "#{@delay}s"
-    end
-  end # RegularDelayer
-
-  class ExponentialDelayer < RegularDelayer
-    def sleep
-      super
-      increment
-    end
-
-    def increment
-      @delay *= 2
-    end
-  end # ExponentialDelayer
-
-  class AttemptCounter
-    attr_reader :attempt
-
-    def initialize(total)
-      # Prevent accidentally causing an infinite loop.
-      unless total.is_a?(Fixnum) and total > 0
-        raise(ArgumentError, "invalid number of attempts: #{total.inspect}")
-      end
-
-      @total = total
-      reset
-    end
-
-    def reset
-      @attempt = 0
-    end
-
-    def increment
-      @attempt += 1
-    end
-
-    def last_attempt?
-      @attempt == @total
-    end
-
-    def to_s
-      [@attempt, @total].join("/")
-    end
-  end # AttemptCounter
-
-  class TruthyTester
-    class ResultNotTruthy < RuntimeError; end
-
-    def self.exceptions
-      [ResultNotTruthy]
-    end
-
-    def initialize(result = nil)
-      @result = result
-    end
-
-    def raise_unless_valid
-      valid? ? @result : raise(ResultNotTruthy, @result.inspect)
-    end
-
-    def valid?
-      not (@result.nil? or @result == false)
+      # Raise an exception unless the result is valid.
+      @tester.raise_unless_valid(result)
+    rescue *@rescuer.exceptions => exception
+      # Raise the exception unless it can be ignored.
+      @rescuer.raise_unless_ignore(exception)
+      # Raise the exception if this was the last attempt.
+      @counter.raise_if_last_attempt(exception)
+      # Sleep before the next attempt.
+      @delayer.sleep
+      # Try the block again.
+      retry
     end
   end
 end #Wait

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wait
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-21 00:00:00.000000000 Z
+date: 2013-01-06 00:00:00.000000000 Z
 dependencies: []
 description: 
 email: todd@paperlesspost.com