SystemTimer 1.0 → 1.1

data/ChangeLog

@@ -1,3 +1,16 @@
+=== 1.1.0 / 2008-11-05
+
+* New implementation supporting concurrent timers, i.e. :
+
+    (1..10).each do
+      Thread.new do
+        SystemTimer.timeout_after(5) do
+          sleep 60
+          puts "hi there!" 
+        end
+      end
+    end
+
 === 1.0.0 / 2008-02-27
 
 * Initial Release

data/README

@@ -5,6 +5,11 @@ 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.
 
+More background on:
+
+* http://ph7spot.com/articles/system_timer 
+* http://davidvollbracht.com/2008/6/2/30-days-of-teach-day-1-systemtimer
+
 == Usage
 
   require 'systemtimer'
@@ -58,6 +63,8 @@ in particular MySQL.
 This implementation is not intended to be drop-in replacement to
 timeout.rb, just a way to wrap sensitive call to system resources.   
 
+You can find more details on SystemTimer and how to use it 
+at http://ph7spot.com/articles/system_timer 
 
 == License
 

data/ext/system_timer/system_timer_native.c

@@ -1,7 +1,14 @@
+/*
+ * SystemTimer native implementation relying on ITIMER_REAL
+ * 
+ * Copyright 2008 David Vollbracht & Philippe Hanrigou
+ */
+ 
 #include "ruby.h"
 #include "rubysig.h"
 #include <signal.h>
 #include <errno.h>
+#include <stdarg.h>
 
 #define DISPLAY_ERRNO 	 		 1
 #define DO_NOT_DISPLAY_ERRNO 0
@@ -11,103 +18,151 @@ sigset_t original_mask;
 sigset_t sigalarm_mask;
 struct sigaction original_signal_handler;
 struct itimerval original_timer_interval;
+static int debug_enabled = 0;
 
 static void clear_pending_sigalrm_for_ruby_threads();
-static void log_debug(char*);
-static void log_error(char*, int);
 static void install_ruby_sigalrm_handler(VALUE);
 static void restore_original_ruby_sigalrm_handler(VALUE);
 static void restore_original_sigalrm_mask_when_blocked();
 static void restore_original_timer_interval();
+static void set_itimerval_with_minimum_1s_interval(struct itimerval *, int);
 static void set_itimerval(struct itimerval *, int);
+static void restore_sigalrm_mask(sigset_t *previous_mask);
+static void log_debug(char*, ...);
+static void log_error(char*, int);
 
-static int debug_enabled = 0;
 
-static VALUE install_timer(VALUE self, VALUE seconds)
+static VALUE install_first_timer_and_save_original_configuration(VALUE self, VALUE seconds)
 {
-  struct itimerval timer_interval;
-
-	/*
-	 * Block SIG_ALRM for safe processing of SIG_ALRM configuration and save mask.
-	 */
-	if (0 != sigprocmask(SIG_BLOCK, &sigalarm_mask, &original_mask)) {
-		log_error("install_timer: Could not block SIG_ALRM", DISPLAY_ERRNO);
-		return Qnil;
-	}
-	clear_pending_sigalrm_for_ruby_threads();
-	log_debug("install_timer: Succesfully blocked SIG_ALRM at O.S. level");
+    struct itimerval timer_interval;
+
+    if (debug_enabled) {
+        log_debug("[install_first_timer] %d s\n", NUM2INT(seconds));
+    }
+
+    /*
+     * Block SIG_ALRM for safe processing of SIG_ALRM configuration and save mask.
+     */
+    if (0 != sigprocmask(SIG_BLOCK, &sigalarm_mask, &original_mask)) {
+        log_error("[install_first_timer] Could not block SIG_ALRM\n", DISPLAY_ERRNO);
+        return Qnil;
+    }
+    clear_pending_sigalrm_for_ruby_threads();
+    log_debug("[install_first_timer] Successfully blocked SIG_ALRM at O.S. level\n");
 	
-  /*
-   * Save previous signal handler.
-   */
-	original_signal_handler.sa_handler = NULL;
-  if (0 != sigaction(SIGALRM, NULL, &original_signal_handler)) {
-		log_error("install_timer: Could not save existing handler for SIG_ALRM", DISPLAY_ERRNO);
-		restore_original_sigalrm_mask_when_blocked();
-		return Qnil;
-  }
-	log_debug("install_timer: Succesfully saved existing SIG_ALRM handler");
-
-	/*
-	 * Install Ruby Level SIG_ALRM handler
-	 */
-	install_ruby_sigalrm_handler(self);
-
-  /*
-   * Set new real time interval timer and save the original if any.
-   */	
-	set_itimerval(&original_timer_interval, 0);
-  set_itimerval(&timer_interval, NUM2INT(seconds));
-  if (0 != setitimer(ITIMER_REAL, &timer_interval, &original_timer_interval)) {
-		log_error("install_timer: Could not install our own timer, timeout will not work", DISPLAY_ERRNO);
-		restore_original_ruby_sigalrm_handler(self);
-		restore_original_sigalrm_mask_when_blocked();
-	  return Qnil;
-  }
-	log_debug("install_timer: Successfully installed timer");
-
-  /*
-   * Unblock SIG_ALRM
-   */
-	if (0 != sigprocmask(SIG_UNBLOCK, &sigalarm_mask, NULL)) {
-		log_error("install_timer: Could not unblock SIG_ALRM, timeout will not work", DISPLAY_ERRNO);
-		restore_original_timer_interval();
-		restore_original_ruby_sigalrm_handler(self);
-		restore_original_sigalrm_mask_when_blocked();		
-	}
-	log_debug("install_timer: Succesfully unblocked SIG_ALRM.");
-
-	return Qnil;
-}
-
-static VALUE cleanup_timer(VALUE self, VALUE seconds)
+   /*
+    * Save previous signal handler.
+    */
+    log_debug("[install_first_timer] Saving original system handler\n");
+    original_signal_handler.sa_handler = NULL;
+    if (0 != sigaction(SIGALRM, NULL, &original_signal_handler)) {
+        log_error("[install_first_timer] Could not save existing handler for SIG_ALRM\n", DISPLAY_ERRNO);
+        restore_original_sigalrm_mask_when_blocked();
+        return Qnil;
+    }
+    log_debug("[install_first_timer] Successfully saved existing SIG_ALRM handler\n");
+    
+	 /*
+	  * Install Ruby Level SIG_ALRM handler
+	  */
+    install_ruby_sigalrm_handler(self);
+
+    /*
+     * Save original real time interval timer and aet new real time interval timer.     
+     */	
+    set_itimerval(&original_timer_interval, 0);
+    set_itimerval_with_minimum_1s_interval(&timer_interval, seconds);
+    if (0 != setitimer(ITIMER_REAL, &timer_interval, &original_timer_interval)) {
+        log_error("[install_first_timer] Could not install our own timer, timeout will not work", DISPLAY_ERRNO);
+        restore_original_ruby_sigalrm_handler(self);
+        restore_original_sigalrm_mask_when_blocked();
+        return Qnil;
+    }
+    log_debug("[install_first_timer] Successfully installed timer (%ds)\n", timer_interval.it_value.tv_sec);
+
+    /*
+     * Unblock SIG_ALRM
+     */
+    if (0 != sigprocmask(SIG_UNBLOCK, &sigalarm_mask, NULL)) {
+        log_error("[install_first_timer] Could not unblock SIG_ALRM, timeout will not work", DISPLAY_ERRNO);
+        restore_original_timer_interval();
+        restore_original_ruby_sigalrm_handler(self);
+        restore_original_sigalrm_mask_when_blocked();		
+    }
+    log_debug("[install_first_timer] Successfully unblocked SIG_ALRM.\n");
+
+    return Qnil;
+}
+
+static VALUE install_next_timer(VALUE self, VALUE seconds)
 {
-	/*
-	 * Block SIG_ALRM for safe processing of SIG_ALRM configuration.
-	 */
-	if (0 != sigprocmask(SIG_BLOCK, &sigalarm_mask, NULL)) {
-		log_error("cleanup_timer: Could not block SIG_ALRM", errno);
-	}
-	clear_pending_sigalrm_for_ruby_threads();
-	log_debug("cleanup_timer: Blocked SIG_ALRM");
-
-	/*
-	 * Install Ruby Level SIG_ALRM handler
-	 */
-	restore_original_ruby_sigalrm_handler(self);
+    struct itimerval timer_interval;
+    sigset_t previous_sigalarm_mask;
+
+    if (debug_enabled) {
+        log_debug("[install_next_timer] %ds\n", NUM2INT(seconds));
+    }
+
+    /*
+     * Block SIG_ALRM for safe processing of SIG_ALRM configuration and save mask.
+     */
+    if (0 != sigprocmask(SIG_BLOCK, &sigalarm_mask, &previous_sigalarm_mask)) {
+        log_error("[install_next_timer] Could not block SIG_ALRM\n", DISPLAY_ERRNO);
+        return Qnil;
+    }
+    clear_pending_sigalrm_for_ruby_threads();
+    log_debug("[install_next_timer] Successfully blocked SIG_ALRM at O.S. level\n");
 	
+    /*
+     * Set new real time interval timer.
+     */	
+    set_itimerval_with_minimum_1s_interval(&timer_interval, seconds);
+    if (0 != setitimer(ITIMER_REAL, &timer_interval, NULL)) {
+        log_error("[install_next_timer] Could not install our own timer, timeout will not work", DISPLAY_ERRNO);
+        restore_sigalrm_mask(&previous_sigalarm_mask);
+        return Qnil;
+    }
+    log_debug("[install_next_timer] Successfully installed timer (%ds)\n", timer_interval.it_value.tv_sec);
+
+    /*
+     * Unblock SIG_ALRM
+     */
+    if (0 != sigprocmask(SIG_UNBLOCK, &sigalarm_mask, NULL)) {
+        log_error("[install_next_timer] Could not unblock SIG_ALRM, timeout will not work", DISPLAY_ERRNO);
+        restore_sigalrm_mask(&previous_sigalarm_mask);
+    }
+    log_debug("[install_next_timer] Successfully unblocked SIG_ALRM.\n");
+
+    return Qnil;
+}
+
+static VALUE restore_original_configuration(VALUE self)
+{
+   /*
+    * Block SIG_ALRM for safe processing of SIG_ALRM configuration.
+    */
+    if (0 != sigprocmask(SIG_BLOCK, &sigalarm_mask, NULL)) {
+        log_error("restore_original_configuration: Could not block SIG_ALRM", errno);
+    }
+    clear_pending_sigalrm_for_ruby_threads();
+    log_debug("[restore_original_configuration] Blocked SIG_ALRM\n");
+
+   /*
+    * Install Ruby Level SIG_ALRM handler
+    */
+    restore_original_ruby_sigalrm_handler(self);
 	
-	if (original_signal_handler.sa_handler == NULL) {
-		log_error("cleanup_timer: Previous SIG_ALRM handler not initialized!", DO_NOT_DISPLAY_ERRNO);
-	} else if (0 == sigaction(SIGALRM, &original_signal_handler, NULL)) {
-		log_debug("cleanup_timer: Succesfully restored previous handler for SIG_ALRM");
-  } else {
-		log_error("cleanup_timer: Could not restore previous handler for SIG_ALRM", DISPLAY_ERRNO);
-	}
-	original_signal_handler.sa_handler = NULL;
+    if (original_signal_handler.sa_handler == NULL) {
+        log_error("[restore_original_configuration] Previous SIG_ALRM handler not initialized!", DO_NOT_DISPLAY_ERRNO);
+    } else if (0 == sigaction(SIGALRM, &original_signal_handler, NULL)) {
+        log_debug("[restore_original_configuration] Successfully restored previous handler for SIG_ALRM\n");
+    } else {
+        log_error("[restore_original_configuration] Could not restore previous handler for SIG_ALRM", DISPLAY_ERRNO);
+    }
+    original_signal_handler.sa_handler = NULL;
 	
-	restore_original_timer_interval();	
-	restore_original_sigalrm_mask_when_blocked();	
+    restore_original_timer_interval();
+    restore_original_sigalrm_mask_when_blocked();	
 }
 
 /*
@@ -119,61 +174,70 @@ static VALUE cleanup_timer(VALUE self, VALUE seconds)
  *
  */
 static void restore_original_timer_interval() {
-  if (0 != setitimer (ITIMER_REAL, &original_timer_interval, NULL)) {
-		log_error("install_timer: Could not restore original timer", DISPLAY_ERRNO);
-  }
-	log_debug("install_timer: Successfully restored timer");	
+    if (0 != setitimer(ITIMER_REAL, &original_timer_interval, NULL)) {
+        log_error("[restore_original_configuration] Could not restore original timer", DISPLAY_ERRNO);
+    }
+    log_debug("[restore_original_configuration] Successfully restored original timer\n");
+}
+
+static void restore_sigalrm_mask(sigset_t *previous_mask) 
+{
+    if (!sigismember(previous_mask, SIGALRM)) {
+        sigprocmask(SIG_UNBLOCK, &sigalarm_mask, NULL);
+        log_debug("[restore_sigalrm_mask] Unblocked SIG_ALRM\n");
+    } else {
+        log_debug("[restore_sigalrm_mask] No Need to unblock SIG_ALRM\n");
+    }	
 }
 
 static void restore_original_sigalrm_mask_when_blocked() 
 {
-	if (!sigismember(&original_mask, SIGALRM)) {
-		sigprocmask(SIG_UNBLOCK, &sigalarm_mask, NULL);
-		log_debug("cleanup_timer: Unblocked SIG_ALRM");
-	} else {
-		log_debug("cleanup_timer: No Need to unblock SIG_ALRM");
-	}	
+  restore_sigalrm_mask(&original_mask);
 }
 
 static void install_ruby_sigalrm_handler(VALUE self) {
-  rb_thread_critical = 1;
-	rb_funcall(self, rb_intern("install_ruby_sigalrm_handler"), 0);
-	rb_thread_critical = 0;
+    rb_thread_critical = 1;
+    rb_funcall(self, rb_intern("install_ruby_sigalrm_handler"), 0);
+    rb_thread_critical = 0;
 }
 
 static void restore_original_ruby_sigalrm_handler(VALUE self) {
-  rb_thread_critical = 1;
-	rb_funcall(self, rb_intern("restore_original_ruby_sigalrm_handler"), 0);
-  rb_thread_critical = 0;
+    rb_thread_critical = 1;
+    rb_funcall(self, rb_intern("restore_original_ruby_sigalrm_handler"), 0);
+    rb_thread_critical = 0;
 }
 
 
 static VALUE debug_enabled_p(VALUE self) {
-	return debug_enabled ? Qtrue : Qfalse;
+    return debug_enabled ? Qtrue : Qfalse;
 }
 
 static VALUE enable_debug(VALUE self) {
-	debug_enabled = 1;
-	return Qnil;
+    debug_enabled = 1;
+    return Qnil;
 }
 
 static VALUE disable_debug(VALUE self) {
-	debug_enabled = 0;
-	return Qnil;	
+    debug_enabled = 0;
+    return Qnil;	
 }
 
-static void log_debug(char* message) 
+static void log_debug(char* message, ...) 
 {
-	if (0 != debug_enabled) {
-		printf("%s\n", message);
-	}
-	return;
+    va_list argp;
+    
+	  if (0 != debug_enabled) {
+	      va_start(argp, message);
+        vfprintf(stdout, message, argp);
+        va_end(argp);
+    }
+	  return;
 }
 
 static void log_error(char* message, int display_errno)
 {
-	fprintf(stderr, "%s: %s\n", message, display_errno ? strerror(errno) : "");
-	return;
+    fprintf(stderr, "%s: %s\n", message, display_errno ? strerror(errno) : "");
+    return;
 }
 
 /*
@@ -186,32 +250,45 @@ static void log_error(char* message, int display_errno)
  */
 static void clear_pending_sigalrm_for_ruby_threads()
 {
-	CHECK_INTS;
-	log_debug("Succesfully triggered all pending signals at Green Thread level");
+    CHECK_INTS;
+    log_debug("[native] Successfully triggered all pending signals at Green Thread level\n");
 }
 
 static void init_sigalarm_mask() 
 {
-	sigemptyset(&sigalarm_mask);
-	sigaddset(&sigalarm_mask, SIGALRM);
-	return;
+    sigemptyset(&sigalarm_mask);
+    sigaddset(&sigalarm_mask, SIGALRM);
+    return;
+}
+
+static void set_itimerval_with_minimum_1s_interval(struct itimerval *value, 
+                                                   int seconds) {
+
+    int sanitized_second_interval;
+                                                     
+    sanitized_second_interval = NUM2INT(seconds);
+    if (sanitized_second_interval <= 0 ) {
+        sanitized_second_interval = 1;
+    }
+    set_itimerval(value, sanitized_second_interval);
 }
 
 static void set_itimerval(struct itimerval *value, int seconds) {
-	value->it_interval.tv_usec = 0;
-  value->it_interval.tv_sec = 0;
-	value->it_value.tv_usec = 0;
-  value->it_value.tv_sec = seconds; // (long int) 
-	return;
+    value->it_interval.tv_usec = 0;
+    value->it_interval.tv_sec = 0;
+    value->it_value.tv_usec = 0;
+    value->it_value.tv_sec = seconds; // (long int) 
+    return;
 }
 
 void Init_system_timer_native() 
 {
-	init_sigalarm_mask();
-  rb_cSystemTimer = rb_define_module("SystemTimer");
-	rb_define_singleton_method(rb_cSystemTimer, "install_timer", 	install_timer, 1);
-	rb_define_singleton_method(rb_cSystemTimer, "cleanup_timer", 	cleanup_timer, 0);
-	rb_define_singleton_method(rb_cSystemTimer, "debug_enabled?", debug_enabled_p, 0);
-	rb_define_singleton_method(rb_cSystemTimer, "enable_debug", 	enable_debug, 0);
-	rb_define_singleton_method(rb_cSystemTimer, "disable_debug",	disable_debug, 0);
+    init_sigalarm_mask();
+    rb_cSystemTimer = rb_define_module("SystemTimer");
+    rb_define_singleton_method(rb_cSystemTimer, "install_first_timer_and_save_original_configuration", 	install_first_timer_and_save_original_configuration, 1);
+    rb_define_singleton_method(rb_cSystemTimer, "install_next_timer", 	install_next_timer, 1);
+    rb_define_singleton_method(rb_cSystemTimer, "restore_original_configuration", restore_original_configuration, 0);
+    rb_define_singleton_method(rb_cSystemTimer, "debug_enabled?", debug_enabled_p, 0);
+    rb_define_singleton_method(rb_cSystemTimer, "enable_debug", 	enable_debug, 0);
+    rb_define_singleton_method(rb_cSystemTimer, "disable_debug",	disable_debug, 0);
 }

data/lib/system_timer.rb

@@ -1,11 +1,21 @@
+# Copyright 2008 David Vollbracht & Philippe Hanrigou
+
 require 'rubygems'
 require 'timeout'
+require 'forwardable'
+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,54 +27,79 @@ 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
 
-   # Backward compatibility with timeout.rb
-   alias timeout timeout_after 
+  Thread.exclusive do    # Avoid race conditions for mutex and pool creation
+    @timer_pool = ConcurrentTimerPool.new
+    @mutex = Mutex.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)
+      new_timer = nil                                      # just for scope
+      @mutex.synchronize do
+        new_timer = timer_pool.add_timer seconds
+        timer_interval = timer_pool.next_trigger_interval_in_seconds
+        debug "==== Install Timer ==== at #{Time.now.to_i}, 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
+      @mutex.synchronize do
+        debug "==== Cleanup Timer ==== at #{Time.now.to_i}, #{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 
    
    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
+       @mutex.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