== 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 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'

  SystemTimer.timeout_after(5) do

    # Something that should be interrupted if it takes too much time...
    # ... even if blocked on a system call!

  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>
   
== Copyright

Copyright:: (C) 2008  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  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.