fire_poll 1.0.1 → 1.2.0

data/.gitignore

@@ -3,3 +3,5 @@ pkg/*
 .bundle
 doc
 .yardoc
+Gemfile.lock
+tags

data/README.md

@@ -2,8 +2,10 @@ Description
 ===========
 `FirePoll.poll` is a method for knowing when something is ready. When your block yields true, execution continues. When your block yields false, poll keeps trying until it gives up and raises an error.
 
-Examples
---------
+`FirePoll.patiently` extends this idea to letting your assertion(s) achieve success after a few tries, if necessary.
+
+Examples: poll
+--------------
 I'm writing a system test for a web application. My test simulates uploading a large file, which isn't instantaneous. I need to know when the file has finished uploading so I can start making assertions.
     def wait_for_file(filename)
       FirePoll.poll do
@@ -33,6 +35,24 @@ I just fired up a fake web service to respond to my client application. I want t
       end
     end
 
+Example: patiently
+------------------
+I'm writing tests for my web app which uses a bunch of crazy Ajax to fetch data from a service and populate a table... one row at a time.
+In real life it takes just a moment to complete, but sometimes one or two of the rows hangs for a second before continuing.
+
+    it "loads the tasks asynchronously and fills the table" do
+      go_to_task_list_page
+
+      patiently do
+        read_task_table_row(1).should == [ "Ride bike", "Done" ]
+        read_task_table_row(2).should == [ "Write code", "Done" ]
+        read_task_table_row(3).should == [ "Go to The Meanwhile", "Todo" ]
+      end
+    end
+
+This test clearly shows what you're interested in, without getting tripped up by delayed Ajax results, but without adding unneeded synchronization or sleep code.
+
+
 Usage
 -----
 Pass a block to `FirePoll.poll`. Return `true` when your need is met. Return `false` when it isn't. `poll` will raise an exception after too many failed attempts.
@@ -43,23 +63,29 @@ The `poll` method takes two optional parameters: a specific message to raise on
     FirePoll.poll("waited for too long!", 7) { ... } # raises an error after seven seconds with a specific error message
     FirePoll.poll(nil, 88) { ... } # raises an error after eighty-eight seconds with the generic error message
 
-The `FirePoll` module may be mixed into your class; this makes it a little faster to type the method name.
-    class TestHelper
-      include FirePoll
-      def helper_method
-        poll do
-          ...
-        end
-      end
+`FirePoll.patiently` is similar, but instead focuses on error-free execution of arbitrary code or tests.  If the passed block runs without raising an error, execution proceeds normally.  If an error is raised, the block is rerun after a brief delay, until the block can be run without exceptions.  If exceptions continue to raise, `patiently` gives up after a bit (default 5 seconds) by re-raising the most recent exception raised by the block.
+
+The `FirePoll` module may be mixed into your class via `include` for nicer reading.
+    FirePoll.poll { ... } # returns immedialtely if no errors, or as soon as errors stop
+    FirePoll.poll(10) { ... } # increase patience to 10 seconds
+    FirePoll.poll(20, 3) { ... } # increase patience to 20 seconds, and delay for 3 seconds before retry
+
+RSpec
+-----
+We tend to include the FirePoll module up-front for all our specs:
+
+    RSpec.configure do |config|
+      config.include FirePoll
+      ...
     end
 
 Implementation
 --------------
-`FirePoll.poll`'s implementation isn't partcilarly accurate with respect to time. The method will run your block (number of seconds * 10) times. It sleeps for a tenth of a second between attempts. Since it doesn't keep track of time, if your timing needs require accuracy, you'll need to look elsewhere.
+UPDATE v1.2.0 - `poll` and `patiently` are both wall-clock sensitive now, meaning they will not poll longer than their allotted time.  This means if your blocks spend significant time determining truth or success, these methods no longer suffer from the multiplicative effects of up-front loop-count calculation.
 
 Motivation
 ----------
-We frequently need to wait for something to happen - usually in tests. And we usually don't have any strict time requirements - as long as something happens in _about_ [x] seconds, we're happy. `FirePoll.poll` meets our need nicely.
+We frequently need to wait for something to happen - usually in tests. And we usually don't have any strict time requirements - as long as something happens in _about_ [x] seconds, we're happy. `poll` and `patiently` are cover a lot of ground quickly and cleanly.
 
 On a related note, `Timer::Timeout` is known to be [busted](http://ph7spot.com/musings/system-timer) and [unreliable](http://blog.headius.com/2008/02/rubys-threadraise-threadkill-timeoutrb.html). `FirePoll.poll` doesn't employ any threads or timers, so we don't worry about whether it will work or not.
 
@@ -73,5 +99,5 @@ Authors
 * Matt Fletcher (fletcher@atomicobject.com)
 * David Crosby (crosby@atomicobject.com)
 * Micah Alles (alles@atomicobject.com)
-* © 2011 [Atomic Object](http://www.atomicobject.com/)
+* © 2012 [Atomic Object](http://www.atomicobject.com/)
 * More Atomic Object [open source](http://www.atomicobject.com/pages/Software+Commons) projects

data/lib/fire_poll.rb

@@ -3,20 +3,60 @@ module FirePoll
   # @param [String] msg a custom message raised when polling fails
   # @param [Numeric] seconds number of seconds to poll
   # @yield a block that determines whether polling should continue
-  # @yieldreturn false if polling should continue
-  # @yieldreturn true if polling is complete
+  # @yield return false if polling should continue
+  # @yield return true if polling is complete
   # @raise [RuntimeError] when polling fails
   # @return the return value of the passed block
   # @since 1.0.0
-  def poll(msg=nil, seconds=2.0) 
-    (seconds * 10).to_i.times do 
+  def poll(msg=nil, seconds=nil) 
+    seconds ||= 2.0                 # 5 seconds overall patience
+    give_up_at = Time.now + seconds # pick a time to stop being patient
+    delay = 0.1                     # wait a tenth of a second before re-attempting
+    failure = nil                   # record the most recent failure
+
+    while Time.now < give_up_at do
       result = yield
       return result if result
-      sleep 0.1
+      sleep delay
     end
     msg ||= "polling failed after #{seconds} seconds" 
     raise msg
   end
 
   module_function :poll
+
+  #
+  # Runs a block of code and returns the value.
+  # IF ANYTHING raises in the block due to test failure or error,
+  # the exception will be held, a small delay, then re-try the block.
+  # This patience endures for 5 seconds by default, before the most
+  # recent reason for failure gets re-raised.
+  #
+  # @param [Numeric] seconds Wall-clock number of seconds to be patient, default is 5 seconds
+  # @param [Numeric] delay Seconds to hesitate after encountering a failure, default is 0.1 seconds 
+  # @yield a block that will be run, and if it raises an error, re-run until success, or patience runs out
+  # @raise [Exception] the most recent Exception that caused the loop to retry before giving up.
+  # @return the value of the passed block
+  # @since 1.2.0
+  #
+  def patiently(seconds=nil, delay=nil)
+    seconds ||= 5                   # 5 seconds overall patience
+    give_up_at = Time.now + seconds # pick a time to stop being patient
+    delay ||= 0.1                   # wait a tenth of a second before re-attempting
+    failure = nil                   # record the most recent failure
+
+    while Time.now < give_up_at do
+      begin
+        return yield
+      rescue Exception => e
+        failure = e
+        sleep delay              # avoid spinning like crazy
+      end
+    end
+    
+    if failure
+      raise failure # if we never got satisfaction, tell the world
+    end
+  end
+  module_function :patiently
 end

data/lib/fire_poll/version.rb

@@ -1,3 +1,3 @@
 module FirePoll
-  VERSION = "1.0.1"
+  VERSION = "1.2.0"
 end

data/test/test_fire_poll.rb

@@ -59,14 +59,22 @@ class FirePollTest < Test::Unit::TestCase
     result = FirePoll.poll { "this is the result of the block" }
     assert_equal "this is the result of the block", result
   end
-end
 
-class TestFirePollMixin < Test::Unit::TestCase
-  include FirePoll
-  
-  def test_can_be_mixed_in
-    assert_nothing_raised do
-      poll { true }
+  def test_should_pay_attention_to_actual_time_elapsed_when_deciding_whether_to_continue_polling
+    start = Time.now
+    call_count = 0
+    begin
+      # If something inside the block consumes significant time, don't get caught in a repeater 
+      FirePoll.poll("woops", 0.5) do 
+        call_count += 1
+        sleep 0.35 # more than half
+        false
+      end
+      raise "Didn't expect #poll to return! call_count=#{call_count}"
+    rescue => e
+      assert_equal "woops", e.message
+      assert_equal 2, call_count, "Delaying should have cut the iterations down to 2"
     end
   end
 end
+

data/test/test_fire_poll_mixin.rb

@@ -0,0 +1,19 @@
+require "test/unit"
+require "fire_poll"
+
+class TestFirePollMixin < Test::Unit::TestCase
+  include FirePoll
+  
+  def test_poll_can_be_mixed_in
+    assert_nothing_raised do
+      poll { true }
+    end
+  end
+
+  def test_patiently_can_be_mixed_in
+    assert_nothing_raised do
+      a = patiently { true }
+      assert_equal a, true
+    end
+  end
+end

data/test/test_patiently.rb

@@ -0,0 +1,89 @@
+require "test/unit"
+require "fire_poll"
+
+class PatientlyTest < Test::Unit::TestCase
+  def test_should_run_block_and_return_value
+    result = FirePoll.patiently do "hi there" end
+    assert_equal "hi there", result
+  end
+
+  def test_should_not_invoke_the_block_more_than_once_if_success
+    call_count = 0
+    result = FirePoll.patiently do 
+      call_count += 1
+      "hi again" 
+    end
+    assert_equal "hi again", result
+  end
+
+  def test_should_invoke_multiple_times_until_exceptions_cease
+    call_count = 0
+    result = FirePoll.patiently do 
+      call_count += 1
+      raise "minor fail" if call_count < 3
+      "ok done" 
+    end
+    assert_equal result, "ok done"
+    assert_equal 3, call_count
+  end
+
+  def test_should_invoke_multiple_times_then_raise_last_exception_if_errors_never_cease
+    call_count = 0
+    begin
+      FirePoll.patiently(0.5) do 
+        call_count += 1
+        raise "persistent fail"
+      end
+      raise "Didn't expect patiently to return! call_count: #{call_count}"
+    rescue => e
+      assert_equal "persistent fail", e.message
+    end
+  end
+
+  def test_should_delay_slightly_before_reinvocation
+    ticks = []
+    begin
+      FirePoll.patiently(0.5) do 
+        ticks << Time.now
+        raise "more persistent fail"
+      end
+      raise "Didn't expect patiently to return!"
+    rescue 
+      ticks.each_cons(2).with_index do |times,i|
+        before,after = times
+        assert ((after-before) > 0.005), "time between reinvocations should be bigger than 50 ms (checking gap #{i})"
+      end
+    end
+  end
+
+  def test_should_default_to_5_seconds_max_patience_if_no_timeout_specified
+    start = Time.now
+    begin
+      FirePoll.patiently do 
+        raise "big fail"
+      end
+      raise "Didn't expect patiently to return!"
+    rescue 
+      span = Time.now-start
+      diff = (5 - span).abs
+      assert diff < 0.05, "Expected about 5 seconds to pass before giving up, got #{span} (diff of #{diff})"
+    end
+  end
+
+  def test_should_pay_attention_to_actual_time_elapsed_when_deciding_patience_is_up
+    start = Time.now
+    call_count = 0
+    begin
+      # If something inside the block consumes significant time, don't get caught in a repeater 
+      FirePoll.patiently(0.5) do 
+        call_count += 1
+        sleep 0.35 # more than half
+        raise "sleepy fail"
+      end
+      raise "Didn't expect patiently to return! call_count=#{call_count}"
+    rescue 
+      assert_equal 2, call_count, "Delaying should have cut the iterations down to 2"
+    end
+  end
+
+end

metadata

@@ -1,75 +1,71 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: fire_poll
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 1.2.0
   prerelease: 
-  version: 1.0.1
 platform: ruby
-authors: 
+authors:
 - Matt Fletcher
 - David Crosby
 - Micah Alles
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-12-16 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-03-22 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &2156420820 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
+  version_requirements: *2156420820
+- !ruby/object:Gem::Dependency
   name: rake
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  requirement: &2156419160 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 0.8.0
   type: :development
   prerelease: false
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
+  version_requirements: *2156419160
+- !ruby/object:Gem::Dependency
   name: yard
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  requirement: &2156416240 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
         version: 0.6.4
   type: :development
   prerelease: false
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
+  version_requirements: *2156416240
+- !ruby/object:Gem::Dependency
   name: bluecloth
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  requirement: &2156414060 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
         version: 2.0.11
   type: :development
   prerelease: false
-  version_requirements: *id004
+  version_requirements: *2156414060
 description: Simple, brute-force method for knowing when something is ready
-email: 
+email:
 - fletcher@atomicobject.com
 - crosby@atomicobject.com
 - alles@atomicobject.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - .yardopts
 - Gemfile
@@ -80,38 +76,39 @@ files:
 - lib/fire_poll.rb
 - lib/fire_poll/version.rb
 - test/test_fire_poll.rb
-homepage: ""
+- test/test_fire_poll_mixin.rb
+- test/test_patiently.rb
+homepage: ''
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 1299515667354431829
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+      hash: -2132279313955691794
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 1299515667354431829
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
+      hash: -2132279313955691794
 requirements: []
-
 rubyforge_project: fire_poll
 rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Simple, brute-force method for knowing when something is ready
-test_files: 
+test_files:
 - test/test_fire_poll.rb
+- test/test_fire_poll_mixin.rb
+- test/test_patiently.rb