No description, website, or topics provided.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
samples
spec
README
README.tmpl
gemspec.rb
gen_readme.rb
install.rb
terminator-0.4.2.gem
terminator-0.4.3.gem

README

NAME
  Terminator

SYNOPSIS
  An external timeout mechanism based on processes and signals.  Safe on
  windows.  Safe for system calls.  Safe for minors.  but not very safe
  for misbehaving, downtrodden zombied out processes.

DESCRIPTION
  Terminator is a solution to the problem of 'how am I meant to kill a
  system call in Ruby!?'
  
  Ruby (at least MRI) uses green threads to "multitask".  This means that
  there is really only ever one ruby process running which then splits up
  it's processor time between all of it's threads internally.
  
  The processor then only has to deal with one ruby process and the ruby 
  process deals with all it's threads.  There are pros and cons to this
  method, but that is not the point of this library.
  
  The point is, that if you make a system call to an external resource from
  ruby, then the kernel will go and make that call for ruby and NOT COME BACK
  to ruby until that system call completes or fails.  This can take a very 
  long time and is why your feeble attempts at using ruby's internal "Timeout"
  command has failed miserably at timing out your external web service, database
  or network connections.
  
  You see, Ruby just doesn't get a chance to do anything as the kernel goes
  "I'm not going to talk to you again until your system calls complete". Sort
  of a no win situation for Ruby.
  
  That's where Terminator comes in.  Like Arnie, he will come back.  No matter
  what, and complete his mission, unless he gets aborted before his timeout,
  you can trust Terminator to thoroughly and without remorse, nuke your 
  misbehaving and timing out ruby processes efficiently, and quickly.

HOW IT WORKS
  Basically we create a new terminator ruby process, separate to the existing
  running ruby process that has a simple command of sleep for x seconds, and then
  do a process TERM on the PID of the original ruby process that created it.
  
  If your process finishes before the timeout, it will kill the Terminator first.
  
  So really it is a race of who is going to win?
  
INSTALL
  gem install terminator

URIS
  http://codeforpeople.com/lib/ruby
  http://rubyforge.org/projects/codeforpeople

HISTORY
  0.4.2
    initial version

AUTHORS
  ara.t.howard - ara.t.howard@gmail.com
  mikel lindsaar - raasdnil@gmail.com

SAMPLES

  <========< samples/a.rb >========>

  ~ > cat samples/a.rb

    require 'terminator'
    
    Terminator.terminate 2 do
      sleep 4
    end

  ~ > ruby samples/a.rb

    samples/a.rb:3: 2s (Terminator::Error)
    	from samples/a.rb:3


  <========< samples/b.rb >========>

  ~ > cat samples/b.rb

    require 'terminator'
    
    Terminator.terminate 0.2 do
      sleep 0.4 rescue puts 'timed out!'
    end

  ~ > ruby samples/b.rb

    timed out!


  <========< samples/c.rb >========>

  ~ > cat samples/c.rb

    require 'terminator'
    
    begin
      Terminator.terminate :seconds => 0.2 do
        sleep 0.4
      end
    rescue Terminator.error
      puts 'timed out!'
    end

  ~ > ruby samples/c.rb

    timed out!


  <========< samples/d.rb >========>

  ~ > cat samples/d.rb

    require 'terminator'
    
    trap = lambda{ puts "signaled @ #{ Time.now.to_i }" }
    
    Terminator.terminate :seconds => 1, :trap => trap do
      sleep 2
      puts "woke up  @ #{ Time.now.to_i }"
    end

  ~ > ruby samples/d.rb

    signaled @ 1221026177
    woke up  @ 1221026178