SystemTimer 1.0 → 1.1

data/lib/system_timer/concurrent_timer_pool.rb

@@ -0,0 +1,83 @@
+# Copyright 2008 David Vollbracht & Philippe Hanrigou
+
+module SystemTimer
+  
+  class ConcurrentTimerPool
+    
+    def registered_timers
+      @timers ||= []
+    end
+        
+    def register_timer(trigger_time, thread)
+      new_timer = ThreadTimer.new(trigger_time, thread)
+      registered_timers << new_timer
+      new_timer
+    end
+
+    def add_timer(interval_in_seconds)
+      new_timer = register_timer(Time.now.to_i + interval_in_seconds, Thread.current)
+      log_registered_timers if SystemTimer.debug_enabled?
+      new_timer
+    end
+    
+    def cancel(registered_timer)
+      registered_timers.delete registered_timer
+    end
+    
+    def first_timer?
+      registered_timers.size == 1
+    end
+    
+    def next_timer
+      registered_timers.sort {|x,y| x.trigger_time <=> y.trigger_time}.first
+    end
+
+    def next_trigger_time
+      timer = next_timer
+      timer.trigger_time unless timer.nil?
+    end
+
+    def next_trigger_interval_in_seconds
+      timer = next_timer
+      [0, (timer.trigger_time - Time.now.to_i)].max unless timer.nil?
+    end
+    
+    def next_expired_timer(now_in_seconds_since_epoch)
+      candidate_timer = next_timer
+      return nil if candidate_timer.nil? || 
+                    candidate_timer.trigger_time > now_in_seconds_since_epoch
+      candidate_timer
+    end
+
+    def trigger_next_expired_timer_at(now_in_seconds_since_epoch)
+      timer = next_expired_timer(now_in_seconds_since_epoch)
+      return if timer.nil?
+
+      cancel timer
+      log_timeout_received(timer) if SystemTimer.debug_enabled?
+      timer.thread.raise Timeout::Error.new("time's up!")
+    end
+
+    def trigger_next_expired_timer
+      trigger_next_expired_timer_at Time.now.to_i
+    end
+    
+    def log_timeout_received(thread_timer)          #:nodoc:
+      puts <<-EOS
+        ==== Triger Timer ==== #{thread_timer}
+            Main thread  : #{Thread.main}
+            Timed_thread : #{thread_timer.thread}
+            All Threads  : #{Thread.list.inspect}
+      EOS
+      log_registered_timers
+    end
+
+    def log_registered_timers          #:nodoc:
+      puts <<-EOS
+            Registered Timers: #{registered_timers.collect do |t| t.to_s end} 
+      EOS
+    end
+    
+  end
+  
+end

data/lib/system_timer/thread_timer.rb

@@ -0,0 +1,21 @@
+# Copyright 2008 David Vollbracht & Philippe Hanrigou
+
+module SystemTimer
+
+  # Timer saving associated thread. This is needed because we trigger timers 
+  # from a Ruby signal handler and Ruby signals are always delivered to 
+  # main thread.
+  class ThreadTimer
+    attr_reader :trigger_time, :thread
+    
+    def initialize(trigger_time, thread)
+      @trigger_time = trigger_time
+      @thread = thread
+    end
+    
+    def to_s
+      "<ThreadTimer :time => #{trigger_time}, :thread => #{thread}>"
+    end
+    
+  end
+end

data/lib/system_timer_stub.rb

@@ -1,3 +1,5 @@
+# Copyright 2008 David Vollbracht & Philippe Hanrigou
+
 require 'rubygems'
 require 'timeout'
 
@@ -9,6 +11,9 @@ module SystemTimer
        yield
      end
    end
+
+   # Backward compatibility with timeout.rb
+   alias timeout timeout_after 
    
  end
  

data/test/all_tests.rb

@@ -1 +1,3 @@
-Dir["#{File.dirname __FILE__}/*_test.rb"].each { |test_case| require test_case }
+Dir["#{File.dirname __FILE__}/**/*_test.rb"].each do |test_case| 
+  require test_case
+end

data/test/system_timer/concurrent_timer_pool_unit_test.rb

@@ -0,0 +1,274 @@
+require File.dirname(__FILE__) + '/../test_helper'
+
+unit_tests do
+  
+  test "registered_timers is empty when there is no registered timers" do
+    assert_equal [], SystemTimer::ConcurrentTimerPool.new.registered_timers
+  end
+
+  test "a new timer is added to the registered timer list when you register a timer" do
+    pool = SystemTimer::ConcurrentTimerPool.new
+    pool.register_timer :a_trigger_time, :a_thread 
+    assert_equal [[:a_trigger_time, :a_thread]], 
+                 pool.registered_timers.collect {|t| [t.trigger_time, t.thread] }
+  end
+
+  test "register_timer returns the timer that was just added to the pool" do
+    pool = SystemTimer::ConcurrentTimerPool.new
+    timer = pool.register_timer :a_trigger_time, :a_thread 
+    assert_equal [:a_trigger_time, :a_thread], [timer.trigger_time, timer.thread]
+  end
+
+  test "add_timer is a shortcut method to register a timer given its interval" do
+    pool = SystemTimer::ConcurrentTimerPool.new
+    Thread.stubs(:current).returns(:the_current_thread)
+    now = Time.now
+    Time.stubs(:now).returns(now)
+    
+    pool.expects(:register_timer).with(now.to_i + 15, :the_current_thread)
+    pool.add_timer 15
+  end
+
+  test "cancel removes a timer from the registered timer list" do
+    pool = SystemTimer::ConcurrentTimerPool.new
+    registered_timer = pool.register_timer :a_trigger_time, :a_thread
+    pool.cancel registered_timer
+    assert_equal [], pool.registered_timers
+  end
+
+  test "cancel does not complain when timer is cancelled " +
+       "(useful for ensure blocks)" do
+         
+    pool = SystemTimer::ConcurrentTimerPool.new
+    a_timer = pool.add_timer 123
+    another_timer = pool.add_timer 456
+    pool.cancel(another_timer)
+    pool.cancel(another_timer)
+    assert_equal [a_timer], pool.registered_timers
+  end
+  
+  test "first_timer? returns false when there is no timer" do
+    assert_equal false, SystemTimer::ConcurrentTimerPool.new.first_timer?
+  end
+
+  test "first_timer? returns true when there is a single timer" do
+    pool = SystemTimer::ConcurrentTimerPool.new
+    pool.add_timer 7
+    assert_equal true, pool.first_timer?
+  end
+
+  test "first_timer? returns false when there is more than one timer" do
+    pool = SystemTimer::ConcurrentTimerPool.new
+    pool.add_timer 7
+    pool.add_timer 3
+    assert_equal false, pool.first_timer?
+  end
+
+  test "first_timer? returns false when there is a single timer left" do
+    pool = SystemTimer::ConcurrentTimerPool.new
+    first_timer = pool.add_timer 7
+    pool.add_timer 3
+    pool.cancel first_timer
+    assert_equal true, pool.first_timer?
+  end
+  
+  test "next expired timer return nil when there is no registered timer" do
+    assert_nil SystemTimer::ConcurrentTimerPool.new.next_expired_timer(24)
+  end
+
+  test "next_timer returns nil when there is no registered timer" do
+    assert_nil SystemTimer::ConcurrentTimerPool.new.next_timer
+  end
+
+  test "next_timer returns the registered timer when " +
+       "there is only one registered timer" do
+         
+    pool = SystemTimer::ConcurrentTimerPool.new
+    the_timer = pool.register_timer 24, stub_everything
+    assert_equal the_timer, pool.next_timer
+  end
+
+  test "next_timer returns the trigger time of the first timer to" +
+       "expire when there is more than one registered timer" do
+         
+    pool = SystemTimer::ConcurrentTimerPool.new
+    late_timer = pool.register_timer 64, stub_everything
+    early_timer = pool.register_timer 24, stub_everything
+    assert_equal early_timer, pool.next_timer
+  end
+
+  test "next_trigger_time returns nil when next_timer is nil" do
+    pool = SystemTimer::ConcurrentTimerPool.new
+    pool.expects(:next_timer).returns(nil)
+    assert_nil pool.next_trigger_time
+  end
+
+  test "next_trigger_time returns trigger time of next timer when " +
+       "next timer is not nil" do
+         
+    pool = SystemTimer::ConcurrentTimerPool.new
+    the_timer = SystemTimer::ThreadTimer.new 24, stub_everything
+    pool.expects(:next_timer).returns(the_timer)
+    assert_equal 24, pool.next_trigger_time
+  end
+
+  test "next_trigger_interval_in_seconds returns nil when next_timer is nil" do
+    pool = SystemTimer::ConcurrentTimerPool.new
+    pool.expects(:next_timer).returns(nil)
+    assert_nil pool.next_trigger_interval_in_seconds
+  end
+
+  test "next_trigger_interval_in_seconds returns the interval between now and " +
+       "next_timer timer time when next timer is in the future" do
+    pool = SystemTimer::ConcurrentTimerPool.new
+    now = Time.now
+    Time.stubs(:now).returns(now)
+    next_timer = SystemTimer::ThreadTimer.new((now.to_i + 7), stub_everything)
+    pool.expects(:next_timer).returns(next_timer)
+    assert_equal 7, pool.next_trigger_interval_in_seconds
+  end
+
+  test "next_trigger_interval_in_seconds returns 0 when next timer is now" do
+    pool = SystemTimer::ConcurrentTimerPool.new
+    now = Time.now
+    Time.stubs(:now).returns(now)
+    next_timer = SystemTimer::ThreadTimer.new now.to_i, stub_everything
+    pool.expects(:next_timer).returns(next_timer)
+    assert_equal 0, pool.next_trigger_interval_in_seconds
+  end
+
+  test "next_trigger_interval_in_seconds returns 0 when next timer is in the past" do
+    pool = SystemTimer::ConcurrentTimerPool.new
+    now = Time.now
+    Time.stubs(:now).returns(now)
+    next_timer = SystemTimer::ThreadTimer.new((now.to_i - 3), stub_everything)
+    pool.expects(:next_timer).returns(next_timer)
+    assert_equal 0, pool.next_trigger_interval_in_seconds
+  end
+
+  test "next_expired_timer returns the timer that was trigerred" +
+       "when a timer has expired" do
+         
+    pool = SystemTimer::ConcurrentTimerPool.new
+    the_timer = pool.register_timer 24, :a_thread
+    assert_equal the_timer, pool.next_expired_timer(24)
+  end  
+
+  test "next_expired_timer returns nil when no timer has expired yet" do
+    pool = SystemTimer::ConcurrentTimerPool.new
+    pool.register_timer 24, :a_thread
+    assert_nil pool.next_expired_timer(23)
+  end  
+
+  test "next_expired_timer returns the timer that first expired " +
+       "when there is more than one expired timer" do
+         
+    pool = SystemTimer::ConcurrentTimerPool.new
+    last_to_expire = pool.register_timer 64, :a_thread
+    first_to_expire = pool.register_timer 24, :a_thread
+    assert_equal first_to_expire, pool.next_expired_timer(100)
+  end  
+
+  test "trigger_next_expired_timer_at does not raise when there is no registered timer" do
+    SystemTimer::ConcurrentTimerPool.new.trigger_next_expired_timer_at 1234
+  end
+
+  test "trigger_next_expired_timer_at raises a TimeoutError in the context of " +
+       "its thread when there is a registered timer that has expired" do
+       
+    pool = SystemTimer::ConcurrentTimerPool.new
+    the_thread = mock('thread')
+    
+    Timeout::Error.expects(:new).with("time's up!").returns(:the_exception)
+    the_thread.expects(:raise).with(:the_exception)
+    pool.register_timer 24, the_thread 
+    pool.trigger_next_expired_timer_at 24
+  end
+
+  test "trigger_next_expired_timer_at does not raise when registered timer has not expired" do
+    pool = SystemTimer::ConcurrentTimerPool.new
+    pool.register_timer 24, stub_everything
+    pool.trigger_next_expired_timer_at(10)
+  end
+
+  test "trigger_next_expired_timer_at triggers the first registered timer that expired" do
+    pool = SystemTimer::ConcurrentTimerPool.new
+    first_to_expire = pool.register_timer 24, stub_everything
+    second_to_expire = pool.register_timer 64, stub_everything
+    pool.trigger_next_expired_timer_at(100)
+    assert_equal [second_to_expire], pool.registered_timers
+  end
+
+  test "trigger_next_expired_timer_at triggers the first registered timer that " +
+       "expired whatever the timer insertion order is" do
+         
+    pool = SystemTimer::ConcurrentTimerPool.new
+    second_to_expire = pool.register_timer 64, stub_everything
+    first_to_expire = pool.register_timer 24, stub_everything
+    pool.trigger_next_expired_timer_at(100)
+    assert_equal [second_to_expire], pool.registered_timers
+  end
+
+  test "trigger_next_expired_timer_at remove the expired timer from the pool" do       
+    pool = SystemTimer::ConcurrentTimerPool.new
+    pool.register_timer 24, stub_everything 
+    pool.trigger_next_expired_timer_at 24
+  end
+
+  test "trigger_next_expired_timer_at logs timeout a registered timer has expired" +
+       "and SystemTimer debug mode is enabled " do
+    pool = SystemTimer::ConcurrentTimerPool.new
+    the_timer = pool.register_timer 24, stub_everything
+    SystemTimer.stubs(:debug_enabled?).returns(true)
+
+    pool.expects(:log_timeout_received).with(the_timer)
+    pool.trigger_next_expired_timer_at 24
+  end
+
+  test "trigger_next_expired_timer_at does not logs timeoout when SystemTimer " +
+       "debug mode is disabled " do
+         
+    pool = SystemTimer::ConcurrentTimerPool.new
+    the_timer = pool.register_timer 24, stub_everything
+    SystemTimer.stubs(:debug_enabled?).returns(false)
+
+    pool.expects(:log_timeout_received).never
+    pool.trigger_next_expired_timer_at 24
+  end
+
+  test "trigger_next_expired_timer_at does not logs timeout no registered timer " +
+       "has expired and SystemTimer debug mode is enabled " do
+         
+    pool = SystemTimer::ConcurrentTimerPool.new
+    the_timer = pool.register_timer 24, stub_everything
+    SystemTimer.stubs(:debug_enabled?).returns(true)
+
+    pool.expects(:log_timeout_received).never
+    pool.trigger_next_expired_timer_at 23
+  end
+  
+  test "trigger_next_expired_timer is a shorcut method calling " +
+       "trigger_next_expired_timer_at with current epoch time" do
+    
+    now = Time.now
+    pool = SystemTimer::ConcurrentTimerPool.new
+    Time.stubs(:now).returns(now)
+    
+    pool.expects(:trigger_next_expired_timer_at).with(now.to_i)
+    pool.trigger_next_expired_timer
+  end
+  
+  test "log_timeout_received does not raise" do
+    original_stdout = $stdout
+    begin
+      stdout = StringIO.new
+      $stdout = stdout
+    
+      SystemTimer::ConcurrentTimerPool.new.log_timeout_received(SystemTimer::ThreadTimer.new(:a_time, :a_thread))
+      assert_match %r{==== Triger Timer ====}, stdout.string
+    ensure
+      $stdout = original_stdout
+    end
+  end
+    
+end

data/test/system_timer/thread_timer_test.rb

@@ -0,0 +1,20 @@
+require File.dirname(__FILE__) + '/../test_helper'
+
+unit_tests do
+  
+  test "trigger_time returns the time given in the constructor" do
+    timer = SystemTimer::ThreadTimer.new(:a_tigger_time, nil)
+    assert_equal :a_tigger_time, timer.trigger_time
+  end
+
+  test "thread returns the thread given in the constructor" do
+    timer = SystemTimer::ThreadTimer.new(nil, :a_thread)
+    assert_equal :a_thread, timer.thread
+  end
+
+  test "to_s retruns a human friendly description of the timer" do
+    assert_match /<ThreadTimer :time => 24, :thread => #<Thread(.*)>>/, 
+                 SystemTimer::ThreadTimer.new(24, Thread.current).to_s                 
+  end
+    
+end

data/test/system_timer_functional_test.rb

@@ -0,0 +1,260 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+functional_tests do
+  
+  DEFAULT_ERROR_MARGIN = 2
+
+  test "original_ruby_sigalrm_handler is nil after reset" do
+    SystemTimer.send(:install_ruby_sigalrm_handler)
+    SystemTimer.send(:reset_original_ruby_sigalrm_handler)
+    assert_nil SystemTimer.send(:original_ruby_sigalrm_handler)
+  end  
+  
+  test "original_ruby_sigalrm_handler is set to existing handler after " +
+       "install_ruby_sigalrm_handler when save_previous_handler is true" do
+    SystemTimer.expects(:trap).with('SIGALRM').returns(:an_existing_handler)
+    SystemTimer.send(:install_ruby_sigalrm_handler)
+    assert_equal :an_existing_handler, SystemTimer.send(:original_ruby_sigalrm_handler)
+  end
+  
+  test "restore_original_ruby_sigalrm_handler traps sigalrm using original_ruby_sigalrm_handler" do
+    SystemTimer.stubs(:original_ruby_sigalrm_handler).returns(:the_original_handler)
+    SystemTimer.expects(:trap).with('SIGALRM', :the_original_handler)
+    SystemTimer.send :restore_original_ruby_sigalrm_handler
+  end  
+  
+  test "restore_original_ruby_sigalrm_handler resets original_ruby_sigalrm_handler" do
+    SystemTimer.stubs(:trap)
+    SystemTimer.expects(:reset_original_ruby_sigalrm_handler)
+    SystemTimer.send :restore_original_ruby_sigalrm_handler
+  end  
+  
+  test "restore_original_ruby_sigalrm_handler reset SIGALRM handler to default when original_ruby_sigalrm_handler is nil" do
+    SystemTimer.stubs(:original_ruby_sigalrm_handler)
+    SystemTimer.expects(:trap).with('SIGALRM', 'DEFAULT')
+    SystemTimer.stubs(:reset_original_ruby_sigalrm_handler)
+    SystemTimer.send :restore_original_ruby_sigalrm_handler
+  end  
+  
+  test "restore_original_ruby_sigalrm_handler resets original_ruby_sigalrm_handler when trap raises" do
+    SystemTimer.stubs(:trap).returns(:the_original_handler)
+    SystemTimer.send(:install_ruby_sigalrm_handler)
+    SystemTimer.expects(:trap).raises("next time maybe...")
+    SystemTimer.expects(:reset_original_ruby_sigalrm_handler)
+  
+    SystemTimer.send(:restore_original_ruby_sigalrm_handler) rescue nil
+  end  
+  
+  test "timeout_after raises TimeoutError if block takes too long" do
+    assert_raises(Timeout::Error) do
+      SystemTimer.timeout_after(1) {sleep 5}
+    end
+  end
+  
+  test "timeout_after does not raises Timeout Error if block completes in time" do
+    SystemTimer.timeout_after(5) {sleep 1}
+  end
+  
+  test "timeout_after returns the value returned by the black" do
+    assert_equal :block_value, SystemTimer.timeout_after(1) {:block_value}
+  end
+  
+  test "timeout_after raises TimeoutError in thread that called timeout_after" do
+    raised_thread = nil
+    other_thread = Thread.new do 
+      begin
+        SystemTimer.timeout_after(1) {sleep 5}
+        flunk "Should have timed out"
+      rescue Timeout::Error
+        raised_thread = Thread.current
+      end
+    end
+    
+    other_thread.join 
+    assert_equal other_thread, raised_thread
+  end
+  
+  test "cancelling a timer that was installed restores previous ruby handler for SIG_ALRM" do    
+    begin
+      fake_original_ruby_handler = proc {}
+      initial_ruby_handler = trap "SIGALRM", fake_original_ruby_handler
+      SystemTimer.install_first_timer_and_save_original_configuration 3
+      SystemTimer.restore_original_configuration
+      assert_equal fake_original_ruby_handler, trap("SIGALRM", "IGNORE")    
+    ensure  # avoid interfering with test infrastructure
+      trap("SIGALRM", initial_ruby_handler) if initial_ruby_handler  
+    end
+  end
+   
+  test "debug_enabled returns true after enabling debug" do
+    begin
+      SystemTimer.disable_debug
+      SystemTimer.enable_debug
+      assert_equal true, SystemTimer.debug_enabled?
+    ensure
+      SystemTimer.disable_debug
+    end
+  end 
+  
+  test "debug_enabled returns false after disable debug" do
+    begin
+      SystemTimer.enable_debug
+      SystemTimer.disable_debug
+      assert_equal false, SystemTimer.debug_enabled?
+    ensure
+      SystemTimer.disable_debug
+    end 
+  end
+  
+  test "timeout offers an API fully compatible with timeout.rb" do
+    assert_raises(Timeout::Error) do
+      SystemTimer.timeout(1) {sleep 5}
+    end
+  end
+
+  # Disable this test as it is failing on Ubuntu. The problem is that
+  # for some reason M.R.I 1.8 is trapping the Ruby signals at the
+  # time the system SIGALRM is delivered, hence we do not timeout as
+  # quickly as we should. Needs further investigation. At least the
+  # SIGALRM ensures that the system will schedule M.R.I. native thread.
+  #
+  #  
+  # test "while exact timeouts cannot be guaranted the timeout should not exceed the provided timeout by 2 seconds" do
+  #   start = Time.now
+  #   begin
+  #     SystemTimer.timeout_after(2) do 
+  #       open "http://www.invalid.domain.comz"
+  #     end
+  #     raise "should never get there"
+  #   rescue SocketError => e
+  #   rescue Timeout::Error => e
+  #   end
+  #   elapsed = Time.now - start
+  #   assert elapsed < 4, "Got #{elapsed} s, expected 2, at most 4"
+  # end
+  
+  
+  test "timeout are enforced on system calls" do
+    assert_timeout_within(3) do
+      SystemTimer.timeout(3) do
+         sleep 30
+      end
+    end
+  end
+  
+  test "timeout work when spawning a different thread" do
+    assert_timeout_within(3) do
+      thread = Thread.new do
+        SystemTimer.timeout(3) do
+           sleep 60
+        end
+      end
+      thread.join
+    end
+  end
+  
+  test "can set multiple serial timers" do
+    10.times do
+      assert_timeout_within(3) do
+        SystemTimer.timeout(3) do
+           sleep 60
+        end
+      end
+    end
+  end
+  
+  test "timeout work when setting concurrent timers, the first one " +
+       "expiring before the second one" do
+         
+    first_thread = Thread.new do
+      assert_timeout_within(3) do
+        SystemTimer.timeout(3) do
+           sleep 60
+        end
+      end
+    end
+    second_thread = Thread.new do
+      assert_timeout_within(5) do
+        SystemTimer.timeout(5) do
+           sleep 60
+        end
+      end
+    end
+    first_thread.join
+    second_thread.join
+  end
+  
+  test "timeout work when setting concurrent timers, the second one " +
+       "expiring before the first one" do
+         
+    first_thread = Thread.new do
+      assert_timeout_within(10) do
+        SystemTimer.timeout(10) do
+           sleep 60
+        end
+      end
+    end
+    second_thread = Thread.new do
+      assert_timeout_within(3) do
+        SystemTimer.timeout(3) do
+           sleep 60
+        end
+      end
+    end
+    first_thread.join
+    second_thread.join
+  end
+  
+  test "timeout work when setting concurrent timers with the exact" +
+       "same timeout" do
+         
+    first_thread = Thread.new do
+      assert_timeout_within(2) do
+        SystemTimer.timeout(2) do
+           sleep 60
+        end
+      end
+    end
+    second_thread = Thread.new do
+      assert_timeout_within(2) do
+        SystemTimer.timeout(2) do
+           sleep 60
+        end
+      end
+    end
+    first_thread.join
+    second_thread.join
+  end
+
+  test "timeout works with random concurrent timers dynamics" do
+    all_threads = []
+    
+    10.times do
+      a_timeout = [1, (rand(10)).to_i].max
+      all_threads << Thread.new do
+        assert_timeout_within(a_timeout, 10) do
+          SystemTimer.timeout(a_timeout) do
+             sleep 180
+          end
+        end
+      end
+    end
+    
+    all_threads.each {|t| t.join}
+  end
+  
+  def assert_timeout_within(expected_timeout_in_seconds, 
+                            error_margin = DEFAULT_ERROR_MARGIN, 
+                            &block)                            
+    start = Time.now    
+    yield
+    flunk "Did not timeout as expected!"
+  rescue Timeout::Error    
+    elapsed = Time.now - start
+    assert elapsed >= expected_timeout_in_seconds, 
+           "Timed out too early, expected #{expected_timeout_in_seconds}, got #{elapsed} s"
+    assert elapsed < (expected_timeout_in_seconds + error_margin), 
+           "Timed out after #{elapsed} seconds, expected #{expected_timeout_in_seconds}"
+  end
+  
+end