system_timer 1.0 → 1.2.4

data/lib/system_timer.rb

@@ -1,11 +1,26 @@
-require 'rubygems'
+# Copyright 2008 David Vollbracht & Philippe Hanrigou
+
+if defined?(RUBY_ENGINE) and RUBY_ENGINE == "rbx"
+  require File.dirname(__FILE__) + '/system_timer_stub'
+else
+
+require 'thread'
 require 'timeout'
+require 'forwardable'
+require 'monitor'
+require File.dirname(__FILE__) + '/system_timer/thread_timer'
+require File.dirname(__FILE__) + '/system_timer/concurrent_timer_pool'
 
-# Timer based on underlying SIGALRM system timers, is a
+# Timer based on underlying +ITIMER_REAL+ system timer. It is a
 # solution to Ruby processes which hang beyond the time limit when accessing
 # external resources. This is useful when timeout.rb, which relies on green
 # threads, does not work consistently.
 #
+# For more information and background check out:
+#
+# * http://ph7spot.com/articles/system_timer
+# * http://davidvollbracht.com/2008/6/2/30-days-of-teach-day-1-systemtimer
+#
 # == Usage
 #
 #   require 'systemtimer'
@@ -17,56 +32,84 @@ require 'timeout'
 #
 #   end
 #
-module SystemTimer 
- class << self
-   
-   # Executes the method's block. If the block execution terminates before 
-   # +seconds+ seconds has passed, it returns true. If not, it terminates 
-   # the execution and raises a +Timeout::Error+.
-   def timeout_after(seconds)
-     install_timer(seconds)
-     return yield
-   ensure
-     cleanup_timer
-   end
+module SystemTimer
+
+  Thread.exclusive do    # Avoid race conditions for monitor and pool creation
+    @timer_pool = ConcurrentTimerPool.new
+    @monitor = Monitor.new
+  end
+
+  class << self
+    attr_reader :timer_pool
+
+    # Executes the method's block. If the block execution terminates before
+    # +seconds+ seconds has passed, it returns true. If not, it terminates
+    # the execution and raises a +Timeout::Error+.
+    def timeout_after(seconds, exception_class = nil)
+      new_timer = nil                                      # just for scope
+      @monitor.synchronize do
+        new_timer = timer_pool.add_timer seconds, exception_class
+        timer_interval = timer_pool.next_trigger_interval_in_seconds
+        debug "==== Install Timer ==== at #{Time.now.to_f}, next interval: #{timer_interval}"
+        if timer_pool.first_timer?
+          install_first_timer_and_save_original_configuration timer_interval
+        else
+          install_next_timer timer_interval
+        end
+      end
+      return yield
+    ensure
+      @monitor.synchronize do
+        debug "==== Cleanup Timer ==== at #{Time.now.to_f}, #{new_timer} "
+        timer_pool.cancel new_timer
+        timer_pool.log_registered_timers if debug_enabled?
+        next_interval = timer_pool.next_trigger_interval_in_seconds
+        debug "Cleanup Timer : next interval #{next_interval.inspect} "
+        if next_interval
+          install_next_timer next_interval
+        else
+          restore_original_configuration
+        end
+      end
+    end
+
+    # Backward compatibility with timeout.rb
+    alias timeout timeout_after
 
-   # Backward compatibility with timeout.rb
-   alias timeout timeout_after 
-   
    protected
-   
-   def install_ruby_sigalrm_handler                 #:nodoc:
-     timed_thread = Thread.current  # Ruby signals are always delivered to main thread by default.
+
+   def install_ruby_sigalrm_handler            #:nodoc:
      @original_ruby_sigalrm_handler = trap('SIGALRM') do
-        log_timeout_received(timed_thread) if SystemTimer.debug_enabled?
-        timed_thread.raise Timeout::Error.new("time's up!")
-      end
+       @monitor.synchronize do
+          # Triggers timers one at a time to ensure more deterministic results
+          timer_pool.trigger_next_expired_timer
+       end
+     end
    end
-  
-   def restore_original_ruby_sigalrm_handler        #:nodoc:
+
+   def restore_original_ruby_sigalrm_handler   #:nodoc:
      trap('SIGALRM', original_ruby_sigalrm_handler || 'DEFAULT')
    ensure
      reset_original_ruby_sigalrm_handler
    end
-   
-   def original_ruby_sigalrm_handler               #:nodoc:
+
+   def original_ruby_sigalrm_handler           #:nodoc:
      @original_ruby_sigalrm_handler
    end
- 
-   def reset_original_ruby_sigalrm_handler         #:nodoc:
+
+   def reset_original_ruby_sigalrm_handler     #:nodoc:
      @original_ruby_sigalrm_handler = nil
    end
 
-   def log_timeout_received(timed_thread)          #:nodoc:
-     puts <<-EOS
-       install_ruby_sigalrm_handler: Got Timeout in #{Thread.current}
-           Main thread  : #{Thread.main}
-           Timed_thread : #{timed_thread}
-           All Threads  : #{Thread.list.inspect}
-     EOS
+   def debug(message)    #:nodoc
+     puts message if debug_enabled?
    end
+
  end
 
 end
 
-require 'system_timer_native'
+require 'system_timer_native'
+
+
+end # stub guard

data/lib/system_timer/concurrent_timer_pool.rb

@@ -0,0 +1,89 @@
+# Copyright 2008 David Vollbracht & Philippe Hanrigou
+
+module SystemTimer
+  
+  class ConcurrentTimerPool
+    
+    def registered_timers
+      @timers ||= []
+    end
+        
+    def register_timer(trigger_time, thread, exception_class=nil)
+      new_timer = ThreadTimer.new(trigger_time, thread, exception_class)
+      registered_timers << new_timer
+      new_timer
+    end
+
+    def add_timer(interval_in_seconds, exception_class=nil)
+      new_timer = register_timer(Time.now.to_f + interval_in_seconds, Thread.current, exception_class)
+      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_f)].max unless timer.nil?
+    end
+    
+    def next_expired_timer(now_in_seconds_since_epoch)
+      candidate_timer = next_timer
+      if SystemTimer.debug_enabled?
+        puts "Candidate timer at #{now_in_seconds_since_epoch} : " +
+             candidate_timer.inspect
+      end
+      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)
+      puts "Next expired timer : #{timer.inspect}" if SystemTimer.debug_enabled?
+      return if timer.nil?
+
+      cancel timer
+      log_timeout_received(timer) if SystemTimer.debug_enabled?
+      timer.thread.raise timer.exception_class.new("time's up!")
+    end
+
+    def trigger_next_expired_timer
+      puts "Trigger next expired timer" if SystemTimer.debug_enabled?
+      trigger_next_expired_timer_at Time.now.to_f
+    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.map {|t| t.to_s}.join("\n                               ")}
+      EOS
+    end
+    
+  end
+  
+end

data/lib/system_timer/thread_timer.rb

@@ -0,0 +1,22 @@
+# 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, :exception_class
+    
+    def initialize(trigger_time, thread, exception_class = nil)
+      @trigger_time = trigger_time
+      @thread = thread
+	  @exception_class = exception_class || Timeout::Error
+    end
+    
+    def to_s
+      "<ThreadTimer :time => #{trigger_time}, :thread => #{thread}, :exception_class => #{exception_class}>"
+    end
+    
+  end
+end

data/lib/system_timer_stub.rb

@@ -1,4 +1,5 @@
-require 'rubygems'
+# Copyright 2008 David Vollbracht & Philippe Hanrigou
+
 require 'timeout'
 
 module SystemTimer 
@@ -9,6 +10,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,291 @@
+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_f + 15, :the_current_thread, nil)
+    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_f + 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_f, 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_f - 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
+
+    original_stdout = $stdout
+    begin
+      stdout = StringIO.new
+      $stdout = stdout
+
+      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
+    ensure
+      $stdout = original_stdout
+    end
+  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
+
+    original_stdout = $stdout
+    begin
+      stdout = StringIO.new
+      $stdout = stdout
+         
+      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
+    ensure
+      $stdout = original_stdout
+    end
+  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_f)
+    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