codders-SystemTimer 1.2.3.1

data/README

@@ -0,0 +1,205 @@
+Synopsis
+========
+
+System Timer, a timer based on underlying `SIGALRM` system timers, is a
+solution to Ruby processes which hang beyond the time limit when accessing
+external resources. This is useful when `timeout.rb`, which, on M.R.I 1.8,
+relies on green threads, does not work consistently.
+
+More background on:
+
+* [http://ph7spot.com/musings/system-timer](http://ph7spot.com/musings/system-timer)
+* [http://davidvollbracht.com/2008/6/2/30-days-of-teach-day-1-systemtimer](http://davidvollbracht.com/2008/6/2/30-days-of-teach-day-1-systemtimer)
+
+Usage
+=====
+
+    require 'system_timer'
+
+    SystemTimer.timeout_after(5) do
+
+      # Something that should be interrupted if it takes too much time...
+      # ... even if blocked on a system call!
+
+    end
+
+ Timeouts as Floats
+ ------------------
+
+  You can use a floating point number when specifying the timeout in
+  seconds but SystemTimer will not allow you to go below 200ms, e.g.
+
+    SystemTimer.timeout_after(0.5) do
+      # timeout after 500ms
+    end
+
+    SystemTimer.timeout_after(0.01) do
+      # timeout after (uncompressable) 200ms even if 10ms is requested
+    end
+
+  Note that SystemTimer is going through too many layers to be
+  able to reliably guarantee a sub-second timeout on all platforms,
+  so your mileage may vary when specifying timeouts under one second.
+
+ Custom Timeout Exceptions
+ -------------------------
+
+  You can also use a custom timeout exception to be raised on timeouts (to
+  avoid interference with other libraries using `Timeout::Error` -- e.g. `Net::HTTP`)
+
+    require 'system_timer'
+
+    begin
+
+      SystemTimer.timeout_after(5, MyCustomTimeoutException) do
+
+        # Something that should be interrupted if it takes too much time...
+        # ... even if blocked on a system call!
+
+      end
+
+    rescue MyCustomTimeoutException => e
+      # Recovering strategy
+    end
+
+
+Requirements
+============
+
+SystemTimer only works on UNIX platforms (Mac OS X, Linux, Solaris, BSD, ...).
+You can install the gem on Microsoft Windows, but you will only get
+a convenience shell wrapping a simple call to timeout.rb under the cover.
+
+Install
+=======
+
+    sudo gem install SystemTimer
+
+Authors
+=======
+
+* David Vollbracht  <http://davidvollbracht.com>
+* Philippe Hanrigou <http://ph7spot.com>
+
+Contributors
+============
+
+* Dmytro Shteflyuk <http://kpumuk.info/> :
+   - Changed from using Mutex to Monitor. Evidently Mutex causes thread
+     join errors when Ruby is compiled with -disable-pthreads
+     <https://github.com/kpumuk/system-micro-timer/commit/fe28f4dcf7d4126e53b7c642c5ec35fe8bc1e081>
+   - First tentative to support float timeouts
+     <https://github.com/kpumuk/system-micro-timer/commit/57fff73849aad7c94f8b9234352b7288d1314d21>
+
+* runix <http://github.com/runix> :
+   - Added support for custom timeout exception. Useful to avoid interference
+     with other libraries using `Timeout::Error` (e.g. `Net::HTTP`)
+     <https://github.com/runix/system-timer/commit/d33acb3acc53d5105c68b25c3a2126fa682f12c0>
+     <https://github.com/runix/system-timer/commit/d8ca3452e462ea909d8e11a6091e7c30dfa3a1a8>
+
+* Jesse Storimer <http://jstorimer.com>
+   - Explicit required_ruby_version = '~> 1.8.7' in gem spec.
+     <https://github.com/jstorimer/system-timer/commit/ec08b4d2173ffd635065a1680c8f8b4fbf6691fd>
+
+* James Tucker <http://blog.ra66i.org>
+   - Fix for RubyGems 1.6, which will not require "thread"
+     <https://github.com/raggi/system-timer/commit/f6dd9535e3f1141f319fe7919b8347dd0e40560c>
+     <https://github.com/raggi/system-timer/commit/b13ff12bc7392b1aa2fe7911e305a3e8f215efd2>
+
+Copyright
+=========
+
+Copyright:: (C) 2008-2010  David Vollbracht & Philippe Hanrigou
+
+Description
+===========
+
+While deploying Rails application in production our team discovered
+that some web service call would not timeout way beyond their defined
+limit, progressively freezing our Mongrel cluster until we restarted
+the servers. A closer analysis revealed that the native thread in charge of
+of the web service call was never scheduled, "stucked" on the service
+call. As it turn out the timeout library bundled with Ruby 1.8 (MRI)
+relies on green-threads to perform its magic... so the magic had no chance
+to happen in this scenario.
+
+Based on an original idea by Kurtis Seebaldt <http://kseebaldt.blogspot.com>,
+David Vollbracht and Philippe Hanrigou pair programmed an alternative
+implementation based on system timers (the +SIGALRM+ POSIX signal):
+This design guarantees proper timeout behavior even when crossing-boundaries and accessing
+system/external resources. Special care has been taken to interfere as little as
+possible with other processes that might also rely on +SIGALRM+,
+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
+=======
+
+(The Ruby License)
+
+Copyright:: (C) 2008-2010  David Vollbracht & Philippe Hanrigou
+
+SystemTimer is copyrighted free software by David Vollbracht and Philippe Hanrigou.
+You can redistribute it and/or modify it under either the terms of the GPL
+(see COPYING file), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+    a) place your modifications in the Public Domain or otherwise
+       make them Freely Available, such as by posting said
+       modifications to Usenet or an equivalent medium, or by allowing
+       the author to include your modifications in the software.
+
+    b) use the modified software only within your corporation or
+       organization.
+
+    c) rename any non-standard executables so the names do not conflict
+       with standard executables, which must also be provided.
+
+    d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+    a) distribute the executables and library files of the software,
+       together with instructions (in the manual page or equivalent)
+       on where to get the original distribution.
+
+    b) accompany the distribution with the machine-readable source of
+       the software.
+
+    c) give non-standard executables non-standard names, with
+       instructions on where to get the original software distribution.
+
+    d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under this terms.
+
+     They are gc.c(partly), utils.c(partly), regex.[ch], st.[ch] and some
+     files under the ./missing directory.  See each file for the copying
+     condition.
+
+  5. The scripts and library files supplied as input to or produced as
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them,
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.
+
+

data/ext/system_timer/extconf.rb

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+require 'mkmf'
+create_makefile("system_timer_native")

data/ext/system_timer/system_timer_native.c

@@ -0,0 +1,326 @@
+/*
+ * 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
+#define MICRO_SECONDS 1000000.0
+#define MINIMUM_TIMER_INTERVAL_IN_SECONDS 0.2
+#define RT_SIGNAL_ID 10
+
+VALUE rb_cSystemTimer;
+
+// Ignore most of this for Rubinius
+#ifndef RUBINIUS
+
+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 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 *, VALUE);
+static void set_itimerval(struct itimerval *, double);
+static void restore_sigalrm_mask(sigset_t *previous_mask);
+static void log_debug(char*, ...);
+static void log_error(char*, int);
+
+
+static VALUE install_first_timer_and_save_original_configuration(VALUE self, VALUE seconds)
+{
+    struct itimerval timer_interval;
+
+    if (debug_enabled) {
+        log_debug("[install_first_timer] %.2lfs\n", NUM2DBL(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.
+    */
+    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.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;
+    }
+    if (debug_enabled) {
+      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)
+{
+    struct itimerval timer_interval;
+    sigset_t previous_sigalarm_mask;
+
+    if (debug_enabled) {
+        log_debug("[install_next_timer] %.2lfs\n", NUM2DBL(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;
+    }
+    if (debug_enabled) {
+      log_debug("[install_next_timer] Successfully installed timer (%ds + %dus)\n", 
+                timer_interval.it_value.tv_sec, timer_interval.it_value.tv_usec);
+    }
+
+    /*
+     * 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("[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 the way it was originally set. **WARNING** Breaks original timer semantics
+ *
+ *   Not bothering to calculate how much time is left or if the timer already expired
+ *   based on when the original timer was set and how much time is passed, just resetting 
+ *   the original timer as is for the sake of simplicity.
+ *
+ */
+static void restore_original_timer_interval() {
+    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() 
+{
+  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;
+}
+
+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;
+}
+
+
+static VALUE debug_enabled_p(VALUE self) {
+    return debug_enabled ? Qtrue : Qfalse;
+}
+
+static VALUE enable_debug(VALUE self) {
+    debug_enabled = 1;
+    return Qnil;
+}
+
+static VALUE disable_debug(VALUE self) {
+    debug_enabled = 0;
+    return Qnil;	
+}
+
+static void log_debug(char* message, ...) 
+{
+    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;
+}
+
+/*
+ * The intent is to clear SIG_ALRM signals at the Ruby level (green threads),
+ * eventually triggering existing SIG_ALRM handler as a courtesy.
+ * 
+ * As we cannot access trap_pending_list outside of signal.c our best fallback option
+ * is to trigger all pending signals at the Ruby level (potentially triggering
+ * green thread scheduling).
+ */
+static void clear_pending_sigalrm_for_ruby_threads()
+{
+    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, SIGRTMIN + RT_SIGNAL_ID);
+    return;
+}
+
+static void set_itimerval_with_minimum_1s_interval(struct itimerval *value, 
+                                                   VALUE seconds) {
+
+    double sanitized_second_interval;
+                                                     
+    sanitized_second_interval = NUM2DBL(seconds) + MINIMUM_TIMER_INTERVAL_IN_SECONDS;
+    if (sanitized_second_interval < MINIMUM_TIMER_INTERVAL_IN_SECONDS ) {
+        sanitized_second_interval = MINIMUM_TIMER_INTERVAL_IN_SECONDS;
+    }
+    set_itimerval(value, sanitized_second_interval);
+}
+
+static void set_itimerval(struct itimerval *value, double seconds) {
+    if (debug_enabled) {
+      log_debug("[set_itimerval] %.3lfs\n", seconds);
+    }
+    value->it_interval.tv_usec = 0;
+    value->it_interval.tv_sec = 0;
+    value->it_value.tv_sec = (long int) (seconds);
+    value->it_value.tv_usec = (long int) ((seconds - value->it_value.tv_sec) \
+                                          * MICRO_SECONDS);
+    if (debug_enabled) {
+      log_debug("[set_itimerval] Set to %ds + %dus\n", value->it_value.tv_sec, 
+                                                       value->it_value.tv_usec);
+    }
+    return;
+}
+
+
+void Init_system_timer_native() 
+{
+    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);
+}
+
+#else
+
+// Exists just to make things happy
+void Init_system_timer_native()
+{
+  rb_cSystemTimer = rb_define_module("SystemTimer");
+}
+
+#endif